Agent API — rules of the road

The limits, the caps, and every error the Polypad agent API can return — written down so a developer finds them here instead of discovering them by hitting a wall. No signup, no API key, no approval: the limits below are the only gate, and they apply per IP address (and per wallet for prepared actions).

Rate limits

Limits reset every minute. If you hit one, the reply is HTTP 429 and names how long to wait (retry-after, in seconds).

  • Reads — 120 per minute, per IP. Listings, quotes, details, portfolio, transaction status.
  • Prepares — 30 per minute, per IP. Anything that builds an unsigned transaction.
  • Prepares per wallet — 12 per minute. Counted per signing wallet, on top of the IP limit.
  • Intent — 40 per minute, per IP. The plain-language tool (polypad_intent) has its own limit.

Pro — 10x the free limits, $0 while growing. With a free API key from /agents/accounts: reads 1,200 per minute, prepares 300 per minute, prepares per wallet 120 per minute, intent 400 per minute. Same 21 tools, same 25 ETH cap per action. A key only identifies your calls — it never moves money. See Pricing.

Size and safety caps

  • One action, at most 25 ETH. Above that the API refuses (amount_too_large). Split it into smaller actions.
  • Above 1 ETH, confirm first. Actions over 1 ETH need the user to confirm the amount, then the call is resent with confirmLarge: true.
  • Request body, at most 16 KB. Above that the API answers 413.
  • Batch, at most 10 messages. One MCP request can carry 1 to 10 JSON-RPC messages.
  • Listings, at most 50 results. The limit parameter caps at 50.
  • Slippage, 100 basis points by default, 1,000 at most. 100 basis points is 1%.

Every prepare call is simulated on-chain before the unsigned transaction is returned. If the simulation fails, you get simulation_reverted and nothing is sent. The API never signs and never holds keys — the transaction it returns is unsigned, and your wallet signs it.

Error codes

Errors always arrive in the same shape: { ok: false, error: { code, message } }. The message is plain language and often names the field to fix. This table lists every code the API can return, grouped by HTTP status.

  • amount_too_large (400) — One action is above the 25 ETH cap. Split it into smaller actions.
  • confirm_large_required (400) — The amount is above 1 ETH. Confirm it with the user first, then resend with "confirmLarge": true.
  • invalid_json (400) — The request body was not valid JSON, or was not a JSON object.
  • invalid_params (400) — A field was missing, the wrong type, or out of range (bad address, bad number, bad hash). The error names the field.
  • key_material_rejected (400) — The request contained a private key or seed phrase. Never send one — Polypad never needs it. Nothing was processed.
  • invalid_api_key (401) — The API key sent was unknown or revoked. Free calls need no key — send no key at all, or get a Pro key from /agents/accounts.
  • not_found (404) — No token, tokenized fund, collection, listing, or endpoint matched.
  • tx_not_found (404) — No transaction with that hash on Robinhood Chain yet — it may not have been sent.
  • unknown_template (404) — No Strategy with that id. List the strategies first.
  • method_not_allowed (405) — Wrong HTTP method for the endpoint (GET vs POST).
  • ambiguous_collection (409) — More than one collection matches. Use the collection address.
  • ambiguous_fund (409) — More than one tokenized fund matches. Use the fund address.
  • ambiguous_token (409) — More than one token matches. Use the token address.
  • amount_exceeds_curve (409) — More tokens than the bonding curve can buy back right now. Try a smaller amount.
  • choose_template (409) — More than one Strategy fits the assets. Ask the user which one.
  • commit_window_open (409) — The collection is still in its commitment window. Commit from the collection page.
  • insufficient_balance (409) — The wallet holds less than the amount requested.
  • listing_not_valid (409) — The listing is sold, cancelled, expired, or no longer backed by the seller.
  • no_shares (409) — The wallet holds no shares of that tokenized fund.
  • not_holder (409) — The wallet does not hold the share(s) being redeemed.
  • not_tradable (409) — The token is in a phase that cannot be traded right now.
  • own_listing (409) — This wallet is the seller of that listing.
  • raise_closed (409) — The tokenized fund is not open for minting.
  • raise_open (409) — The tokenized fund is still raising. Exit opens after the raise closes; a refund opens only if the raise fails.
  • skin_required (409) — Public minting is not open yet — the manager must mint their required shares first.
  • sold_out (409) — Sold out (NFT collection, or no shares left).
  • unsupported_fund (409) — Exits from this fund type are not prepared by the API yet. Open the fund page.
  • wallet_cap (409) — The collection’s per-wallet mint limit is reached.
  • payload_too_large (413) — Request body over 16 KB.
  • no_matching_template (422) — No Strategy can hold the requested assets.
  • quote_failed (422) — The pool could not quote that amount. Try a smaller amount.
  • simulation_reverted (422) — The on-chain simulation reverted — the transaction as built would fail. Nothing was sent.
  • rate_limited (429) — Too many requests from this IP. Wait a minute; the reply says how long (retry-after).
  • rate_limited_wallet (429) — Too many prepared actions for this wallet. Wait a minute.
  • internal_error (500) — Unexpected error. Nothing was signed or sent.
  • unsupported_collection_type (501) — Buys from bonding-curve collections are not prepared by the API yet. Open the collection page.
  • rpc_unavailable (503) — The chain data source could not be reached. Retry shortly.

MCP errors (JSON-RPC layer)

When you call the MCP endpoint, JSON-RPC-level problems use numeric codes instead of the named codes above. A tool that fails inside a call still answers 200 with isError: true and the named error in the text.

  • -32700 — Parse error — the request body was not valid JSON.
  • -32600 — Invalid request — not a valid JSON-RPC 2.0 message, or a batch with 0 or more than 10 messages.
  • -32601 — Method not found — the MCP method does not exist. Supported: initialize, ping, tools/list, tools/call.
  • -32602 — Unknown tool, or arguments that are not an object.
  • -32000 — Server error — wraps one of the API errors below. A tools/call that fails this way answers with isError: true and the same error body.

Versioning and deprecation

The agent API server is v2.0.0. It speaks MCP protocol versions 2025-06-18 (default), 2025-03-26, and 2024-11-05 — send the version you want in the initialize call and the server answers with the one it will use. Tool names, inputs, and limits can change in a new major version; when they do, the change is listed on the changelog first.

The older v1 REST API (/api/agents/v1) is deprecated: it still works, but new work should use the MCP server or the v2 REST endpoints. v1 will be switched off on February 16, 2027 — after that date, v1 calls will stop working. Migrate to the MCP server or the v2 REST endpoints before then.

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