Prepare → sign → confirm: the sign loop

An agent action is not done when the transaction is prepared, and it is not done when it is signed. It is done when the agent knows the result. The sign loop is the whole round trip — prepare, sign, confirm — with the confirmation owned by Polypad, not by the user telling the agent “I think it worked.” No signup, no API key, no approval.

The loop in three steps

  1. Prepare. The agent calls a polypad_prepare_* tool with the wallet that will sign — as a walletToken from a single connect (see below), or as the from address on that call. The API simulates the transaction on-chain first. If it would fail, there is no signing link — the agent gets an error and the reason instead. If it passes, the agent gets the unsigned transaction, a plain summary, and a one-tap signing link to polypad.family/sign.
  2. Sign. The user opens the link, connects their wallet, and checks the plain summary on the page — what they pay, the minimum they receive, the fees — against what the agent said in the chat. The page also shows a short fingerprint code for the action, made from the transaction itself (where it sends, what it does, the amount, the chain), so any change to the action changes the code; if the code on the page matches the code the agent showed in the chat, the action on the page is the same one the agent described. If the codes differ, the action on the page is not the one the agent described — stop and ask the agent for a fresh link. Then the user signs in their own wallet. Polypad never holds keys and never signs. Before showing the summary, the signing page asks the API to prepare the same action again for the connected wallet — a fresh on-chain simulation — so a link prepared for one wallet cannot be signed by another. Because the simulation is fresh, the amounts on the page can differ from the chat's numbers if prices or balances moved since the agent prepared it; trust the page's summary, not the chat's.
  3. Confirm. After the transaction is sent, the signing page watches it: it calls polypad_get_tx_status every few seconds until Robinhood Chain confirms it (or it fails), and shows the result in plain words — what was bought, what fund was created — with an explorer link. An agent can do the same check itself from the API; see below.

The way back: returnUrl

A prepare call takes an optional returnUrl — an https:// link back to the agent's own flow, such as its confirmation page. When it is given, the signing page shows a “Back to the agent” button once the transaction confirms (or fails). The button goes to the return link with two values added: tx (the transaction hash) and status (confirmed or failed), so the agent can pick up where it left off without asking the user anything.

The return link has to be an https:// address, at most 2,048 characters. Anything else is ignored — the action still works, it just has no way back. The page never sends the user anywhere on its own; the button is always a tap, and the return link is shown on the page so the user can see where it goes. The same is true after connecting a wallet (below): the way back is always a button the user taps, never an automatic redirect. Without a returnUrl, the page still shows the confirmation and a button to copy a short “Done: 0x…” message back into the chat.

Every prepare tool takes returnUrl — buy, sell, NFT buy and mint, tokenized fund create, mint and redeem, and token launch. The field is listed in the tool reference, and the signing link carries it as the r parameter.

Checking the result yourself

The agent does not have to wait for the user to come back. After any prepare call, it can ask for the transaction's status with polypad_get_tx_status (or the matching REST call) and poll every few seconds until the answer is confirmed or failed. The answer is plain words — what happened, not just a receipt — plus the explorer link.

curl "https://polypad.family/api/agents/v2/tx/status?hash=0x<tx-hash>"

While the transaction is still travelling, the answer is pending. If the hash is unknown — it was never sent — the answer is a 404 (tx_not_found). A mined transaction that failed on-chain still answers failed, with the note that only gas was spent.

A full example

An agent mints 1 share of the Polyfund (a tokenized fund, 0.01 ETH a share) for a wallet, and wants the user sent back to its own confirmation page afterwards:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "polypad_prepare_fund_mint",
    "arguments": {
      "from": "<YOUR_FUNDED_WALLET_ADDRESS>",
      "fund": "0x7c1d31629ac68aebe83f230edbc7eacfc26285ef",
      "quantity": 1,
      "returnUrl": "https://example.com/agent/done"
    }
  }
}

Replace <YOUR_FUNDED_WALLET_ADDRESS> with your own funded wallet address — the prepare step checks that wallet's balance, so the example fails with an empty wallet. The reply includes signing.url (the signing link, already carrying the return link) and signing.returnUrl (the return link echoed back). The agent shows the summary, shares the link, and the user signs. The signing page then confirms the mint and offers the way back.

Which wallet signs? Connect once

The agent passes the signing wallet once — not on every call. The user opens polypad.family/sign?connect=1, connects their wallet, and signs one short message (not a transaction, no funds move). The page gives them a token, good for 90 days. The agent stores it — as POLYPAD_WALLET_TOKEN in the SDKs — and passes it as walletToken instead of a wallet address on every prepare call. The server recovers the wallet from the signature, checks it matches the wallet named in the token and that the token has not expired, and uses that wallet. When the agent passes a returnUrl to the connect page, the page shows a “Back to the agent” button that takes the user back to it with ?walletToken=... and ?wallet=... added. Like the button after a signing, it only goes when tapped — the page never sends the user anywhere on its own.

The token is self-contained — the wallet address, the expiry, and the signature, encoded as text — so Polypad stores nothing about it. The trade-off is honest: a token cannot be revoked from the server. It stops working when it expires, or when the holder deletes it. Treat it like a password for that one wallet and never paste it in a public chat — and do not share the return link the connect page gives you, because the token travels in that link's address. If the token or the link leaks, delete the token and connect again for a fresh one. The token alone cannot move funds: it only tells the API which wallet to prepare actions for, and every prepared action still needs the user's signature in their own wallet before anything is sent.

Per-call from still works as the fallback: a call with no token still needs the wallet address, exactly as before. A call with both must agree — a token and a different address is refused. The SDKs (TypeScript and Python) use the token model throughout: connect once, then no address on any call.

Limits that touch the loop

Prepared actions are limited to 30 per minute per IP address, and 12 per minute per wallet. One action is at most 25 ETH; above 1 ETH the user confirms the amount first. A signing link expires after 20 minutes — after that, the agent prepares the action again with current amounts. The full list is on the rules of the road page.

Contracts are unaudited. The Safe Harbor terms are published; on-chain registration is in progress. See the security page for the full picture.