# Netaro sandbox API > Financial infrastructure for agents — accounts, payments, stablecoins and global payouts in one API, where every payment is checked against a plan a person signed. This is the sandbox: everything is simulated (no bank, no chain, no real money), with the real API shapes. MCP server (streamable HTTP): https://api.netaro.xyz/mcp OpenAPI: https://api.netaro.xyz/openapi.json ## Rules - The plan decides what each call may do. An agent's key can never change its own plan. - A held reply is a normal result, not an error: read held_reason and follow next_action. next_action.type is always the name of an MCP tool to call next. - Every write needs an idempotency key: the idempotency_key argument over MCP, the Idempotency-Key header over REST. A fresh UUID per intended action; reuse it only to retry that action. - Money is an object in integer minor units (cents): 1,250.00 USD is {"value": 125000, "currency": "USD"}. Never a decimal, a string or a bare number. The same object over MCP and REST; a decimal gets invalid_amount. ## What you can do alone, and what only a person can do You can, with your own key: - sign up (`signup`) and collect your key with your claim token (`get_signup`) - read yourself, your plan and your balances (`get_me`, `get_plan`, `list_balances`) - add payees (`add_payee`) — adding one does not put it in your plan - quote, convert between USD, USDC, USDT and OUSD, pay and pay out inside your plan (`create_quote`, `convert`, `pay`, `create_payout`); dry_run: true checks without moving money - ask a person for more when a payment is held (`request_escalation`), and answer an information request from Netaro compliance (`answer_compliance`) - follow anything you started (`get_payment`, `get_payout`, `get_approval`, `get_escalation`, `get_compliance`, `get_request`, `list_events`, `list_activity`, `list_alerts`) - freeze yourself at once (`freeze_self`) Only a person (a signer at your business, signed in at https://app.netaro.xyz/app with a passkey) can do the following. When you need one, tell your owner in these words, filling in the {…} parts: - **Confirm the owner email after sign-up.** Netaro reviews a sign-up only once its owner has confirmed. The link is emailed to the owner_email you signed up with. Relay: "I signed up for a Netaro sandbox account with your work email as owner. Please open the email from Netaro titled "Confirm your email for your agent’s Netaro sandbox sign-up" and click the link. Nothing moves money until Netaro has reviewed the sign-up." - **Approve a payment or payout waiting for approval (pending_approval).** It is above approve_above or matched an approval rule; only a signer with a passkey approves. Relay: "A payment I made is waiting for your approval: {amount} to {payee}, payment {payment_id}. Please sign in at https://app.netaro.xyz/app and approve or decline it with your passkey. Approval requests expire after 3 days." - **Approve an escalation (a request for more than the plan allows).** An escalation asks to change the signed plan; only signers approve, and a widening then waits plan_change_delay. Relay: "A payment I tried was held by our plan ({held_code}). I asked to {amendment} in escalation {escalation_id}. Please review it at https://app.netaro.xyz/app and approve or decline it with your passkey. If you approve, the plan change applies after the plan’s delay ({plan_change_delay} seconds) and the payment is released." - **Unfreeze the agent.** An agent can freeze itself, but only a person can unfreeze it. Relay: "I froze myself on Netaro ({reason}). I can read but cannot move money. When you are satisfied, sign in at https://app.netaro.xyz/app and unfreeze me with your passkey." - **Reissue the API key.** A lost or never-collected key is revoked and reissued by a signed-in signer; the agent then collects the new key with its claim token. Relay: "I lost my Netaro API key. Please sign in at https://app.netaro.xyz/app and reissue the key for agent {agent_id}. I will collect the new one with my claim token; nobody needs to send it to me." - **Change the plan or the workspace settings.** An agent key can never change its plan, approvals or settings (person_required). Ask with request_escalation when a payment is held, or ask the owner for a plan change. Relay: "I need a change to my Netaro plan or settings: {change}. Please sign in at https://app.netaro.xyz/app to make it. A widening of the plan waits its plan_change_delay before it applies." Netaro itself (not your business) reviews sign-ups and clears its own compliance holds; nobody at your business can speed that up. ## Your default test plan Your sandbox test plan: one payee (Sandbox Supplies Co, seeded for you); max_per_payment {"value": 500000, "currency": "USD"}; max_per_day {"value": 2500000, "currency": "USD"}; approve_above {"value": 250000, "currency": "USD"} (above it a person approves); rails ach, same_day_ach, wire, fednow, rtp, stablecoins; currencies USD, USDC, USDT, OUSD; payout currencies none (a payout is held until a person adds one); max_fx_deviation_bps 100; plan_change_delay 300 seconds; expires 90 days after approval. Read the live values with get_plan (plan_id from get_me) and your payees with list_payees. ## Your claim token signup returns claim_token (claim_…) once. Keep it: it is how you collect your key, and how you collect a reissued one later. It can only read your sign-up. - Over MCP: pass it as the claim_token argument of get_signup (an MCP client cannot change its headers mid-session). Never as a header. - Over REST: send it as the header "Authorization: Bearer claim_…" on GET /v1/signups/{agent_id}. Never in the URL or the body. ## Polling Poll only what is waiting on someone else, at these intervals, and stop at a final state. Webhooks (below) can replace polling. - get_signup while pending_review: every 30 seconds; final: sandbox (your key is in api_key, once) or rejected (read rejection_reason); how long: a person and Netaro act: usually minutes, possibly hours. - get_payment / get_payout while pending_approval: every 30 seconds; final: cleared or delivered, declined (decline_reason; expired after 3 days), returned, failed; how long: a person approves; the request expires after 3 days. - get_payment / get_payout while held with an escalation (or get_escalation): every 30 seconds; final: the payment reaches cleared, delivered or declined; how long: a person approves, then the plan change waits plan_change_delay (300 s in the sandbox) and the scheduler releases it within about 5 seconds; escalations expire after 3 days. - get_compliance while review_required or information_requested: every 60 seconds; final: cleared or declined; how long: Netaro compliance acts; no fixed time. - get_request after a timeout: every 2 seconds; final: completed (act on the stored reply); how long: seconds. - get_quote: no polling: read it once, just before you pay; final: used or expired (PHP quotes lock for 10 minutes); how long: 10 minutes. - in_flight is never final; in the sandbox rails settle at once, so you will rarely see it. - On rate_limited, wait retry_after seconds before the next call. ## Docs - [Full reference](https://api.netaro.xyz/llms-full.txt): every tool, endpoint, error, held code and approval reason - [agents.md](https://api.netaro.xyz/agents.md): how an agent works with Netaro, step by step - [Errors, held codes and approval reasons](https://api.netaro.xyz/errors): each doc_url in a reply resolves here ## MCP tools - `signup` (no key): Sign the agent up with its KYA record: the owner's work email, the company, what the agent is built with and what it will do with money. Needs no key. Returns the agent ID and a one-time claim_token: keep it. Then ask your owner to confirm their email (Netaro emails them a link); only a person can. - `get_signup` (no key): Read the sign-up's review status. Over MCP the claim token is this tool's claim_token argument, never a header (over REST it is the header Authorization: Bearer claim_…). After Netaro approves, the first call returns the test API key (api_key.secret) exactly once. - `get_me`: Read the agent, its business, its plan and what it may do now (the may block). - `get_plan`: Read the agent's plan: payees, limits, rails, currencies, policies and approval rules, and any change waiting. - `list_balances`: List the USD account and the USDC, USDT and OUSD wallets, with balances as held by our partner bank. - `list_external_accounts`: List company bank accounts linked through Plaid (read-only). Not in the sandbox: always empty. - `list_payees`: List the agent's payees, each with whether its plan lists it. - `add_payee`: Add a payee: a name and a destination (bank_account for US dollars, php_bank, aed_bank, sgd_bank, or wallet; shapes in llms.txt). This doesn't add it to the plan: an agent never changes its own plan. - `create_quote`: Quote a conversion (1:1 between USD, USDC, USDT and OUSD) or a payout (PHP locked for 10 minutes; AED and SGD set at payout). - `get_quote`: Read a quote: its rate, status (open, used, expired) and expires_at. - `convert`: Convert between USD, USDC, USDT and OUSD, 1:1, inside the plan. - `pay`: Pay on US rails (USD to a bank account) or in stablecoins (to a wallet). Above approve_above it waits for a person (pending_approval). dry_run: true checks everything and moves nothing. - `create_payout`: Pay out in PHP (with a locked quote), AED or SGD (rate set now, inside max_fx_deviation_bps) to a payee with the matching bank destination. dry_run works here too. - `create_card`: Issue a card that spends inside the plan. Not in the sandbox. - `request_escalation`: Ask a person for more: escalate a held payment or payout. Netaro pre-fills the plan amendment its held_reason calls for; the workspace's signers approve or decline it. - `get_payment`: Read a payment (pay_…) or payout (po_…): its status, held_reason, approval and compliance. - `get_payout`: Read a payout (po_…): its status, rate, held_reason, approval and compliance. - `get_request`: Read what happened to a write you sent with this idempotency_key: in progress, or completed with its stored reply. Use it after a timeout instead of guessing. - `get_escalation`: Read an escalation (esc_…): open, approved, declined or expired, the plan amendment it asks for, and its approval. - `get_compliance`: Read a compliance check (cmp_…): why a payment is held for review, any information Netaro asked for, and who clears it (cleared_by). - `answer_compliance`: Answer Netaro compliance's information request on a held payment or payout (status information_requested), once. Netaro compliance then clears or declines it. - `list_events`: Read this agent's events (payment.cleared, plan.change_applied, …), oldest first; filter by type. - `get_approval`: Read an approval request: who has approved, what is left ("1 of 2") and whether it completed. - `attach_record`: Attach or link an invoice, purchase order or delivery record. Not in the sandbox. - `list_activity`: Read Overwatch's activity log for this agent: every call, held and refused ones included, hash-chained. - `list_alerts`: Read Overwatch's alerts about this agent. Overwatch never holds or moves anything; people decide. - `freeze_self`: Freeze this agent, at once. It can still read; it can no longer move money. Only a person can unfreeze it. ## API - GET /v1/health: Service health - GET /v1/requests/{key}: What happened to a call made with this Idempotency-Key - POST /v1/signup: Sign up an agent with its KYA record - GET /v1/signups/{id}: Review status of a sign-up; collects the test key once approved - GET /v1/signup/confirm_email: Owner confirms their email (the simulated email's link) - GET /v1/me: The agent, its business, its plan, its status and what it may do - POST /v1/me/freeze: The agent freezes itself - POST /v1/agents/{id}/freeze: A person freezes an agent - POST /v1/agents/{id}/unfreeze: A person unfreezes an agent (needs approval) - GET /v1/events: This agent's events, oldest first - GET /v1/accounts: The agent's US dollar account, with its balance as held - GET /v1/wallets: The agent's USDC, USDT and OUSD wallets, with balances as held - GET /v1/balances: Every balance in one list: the USD account, then the OUSD, USDC and USDT wallets - POST /v1/payees: Add a payee - GET /v1/payees: The agent's payees, each with whether its current plan lists it - GET /v1/plans/{id}: Read the plan, policies and approval rules - POST /v1/plans/{id}/changes: A person changes a plan - POST /v1/quotes: Quote a payout or conversion - POST /v1/conversions: Convert between USD, USDC, USDT and OUSD, 1:1 - POST /v1/payments: Pay on US rails or in stablecoins - POST /v1/payouts: Global payout in PHP, AED or SGD - GET /v1/quotes/{id}: Read a quote - GET /v1/payments/{id}: Read a payment - GET /v1/payouts/{id}: Read a payout - POST /v1/people/sign_in: Email a one-time sign-in link to a signer - POST /v1/people/sessions: Exchange a sign-in or invite link for a session - POST /v1/people/sign_out: End this session - GET /v1/people/me: The signed-in person: their signer record and workspace - GET /v1/signers: This workspace's signers and their devices - POST /v1/signers: Invite a signer by email (admin signers) - POST /v1/signers/{id}/remove: Remove a signer (admin signers) - POST /v1/people/devices/options: WebAuthn options to register a passkey or security key - POST /v1/people/devices: Register a device: the browser’s WebAuthn registration response - POST /v1/people/devices/{id}/remove: Remove one of your devices - GET /v1/workspace_settings: Read the workspace settings (signed-in person only) - POST /v1/workspace_settings: Change the workspace settings (admin signers only) - GET /v1/approvals: This workspace's approval requests - GET /v1/approvals/{id}: Read an approval request's state and progress - POST /v1/approvals/{id}/options: Start approving: passkey options bound to this request’s details - POST /v1/approvals/{id}/approve: Approve with a passkey tap - POST /v1/approvals/{id}/decline: Decline an approval request - POST /v1/escalations: Ask a person for more: escalate a held payment or payout - GET /v1/escalations/{id}: Read an escalation and whether its payment was released - POST /v1/plans/{id}/sign: Ask for the plan in force to be signed - GET /v1/activity: Overwatch activity log, oldest first, filterable - GET /v1/activity/verify: Walk a chain of the activity log and report the first broken link - GET /v1/activity/checkpoints: Signed checkpoints of a chain head, newest first - GET /v1/activity/checkpoints/key: Netaro's public keys for activity checkpoints (by kid) - GET /v1/alerts: Overwatch's alerts for this agent - GET /v1/alerts/{id}: Read an alert - POST /v1/alerts/{id}/acknowledge: Acknowledge an alert - POST /v1/alerts/{id}/resolve: Resolve an alert, with a note - GET /v1/compliance: This agent's compliance checks and reviews - POST /v1/compliance: Open a business-level compliance review (a person, e.g. from an alert) - GET /v1/compliance/{id}: Read a compliance check and any request for information - POST /v1/compliance/{id}/clear: Clear the business's own review: asks its signers to approve with a passkey (review_clear) - POST /v1/compliance/{id}/decline: Decline the business's own review: the payments it held are declined - POST /v1/compliance/{id}/information: Answer Netaro's information request on a held payment - GET /v1/ready: Ready to serve: the database answers and every migration is applied - POST /v1/webhook_endpoints: Register a signed webhook endpoint for this agent’s events - GET /v1/webhook_endpoints: This agent's webhook endpoints - GET /v1/webhook_endpoints/{id}: Read a webhook endpoint - POST /v1/webhook_endpoints/{id}/rotate_secret: Rotate the signing secret: the new one is shown once; the old one signs for 24 h more - POST /v1/webhook_endpoints/{id}/disable: Stop deliveries to an endpoint (webhook_endpoint.disabled) - GET /v1/webhook_endpoints/{id}/deliveries: The delivery log (webhook_delivery objects): each attempt’s status, newest first ## Closed sets (every value the API accepts or returns) Values are written as code. Send them exactly as shown. - rails: `ach`, `same_day_ach`, `wire`, `fednow`, `rtp`, `stablecoins` - account currencies: `USD`, `USDC`, `USDT`, `OUSD`; payout currencies and their destination: `PHP` → `php_bank`, `AED` → `aed_bank`, `SGD` → `sgd_bank` - payee destination shapes (destination.type): - `bank_account` {`routing_number`, `account_number`, `account_type`}: A US bank account (ACH, same-day ACH, wire, FedNow, RTP). Receives USD. - `wallet` {`network`, `address`}: A stablecoin wallet on ethereum, base, solana. Receives USDC, USDT or OUSD over the stablecoins rail. - `php_bank` {`bank_code`, `account_number`}: A Philippine bank account, paid over InstaPay or PESONet. Receives PHP. - `aed_bank` {`iban`}: A UAE bank account by IBAN. Receives AED. - `sgd_bank` {`bank_code`, `account_number`}: A Singapore bank account. Receives SGD. - wallet networks: `ethereum`, `base`, `solana` - `bank_account` account_type: `checking`, `savings` - statuses (final states in brackets): - sign-up / agent (get_signup, get_me): `pending_review`, `sandbox`, `live`, `rejected`, `frozen` [final: `sandbox`, `live`, `rejected`] - plan (get_plan): `created`, `signed`, `active`, `expired`, `revoked` [final: `active`, `expired`, `revoked`] - payment: `pending_approval`, `held`, `in_flight`, `cleared`, `declined`, `returned`, `failed` [final: `cleared`, `declined`, `returned`, `failed`] - payout: `pending_approval`, `held`, `in_flight`, `delivered`, `declined`, `returned`, `failed` [final: `delivered`, `declined`, `returned`, `failed`] - conversion (convert): `completed`, `held` [final: `completed`] - deposit: `received`, `converted` [final: `received`, `converted`] - quote (get_quote): `open`, `used`, `expired` [final: `used`, `expired`] - approval (get_approval): `pending`, `completed`, `declined` [final: `completed`, `declined`] - escalation (get_escalation): `open`, `approved`, `declined` [final: `declined`] - compliance check (get_compliance): `passed`, `review_required`, `information_requested`, `information_provided`, `cleared`, `declined` [final: `passed`, `cleared`, `declined`] - request (get_request): `in_progress`, `completed` [final: `completed`] - held codes (a held reply is a normal result; source says who holds it): - `payee_not_in_plan` (source `plan`, plan field `payees`): This payee isn't in the agent's plan. - `rail_not_in_plan` (source `plan`, plan field `rails`): This payment rail isn't in the agent's plan. - `currency_not_in_plan` (source `plan`, plan field `currencies`): This currency isn't in the agent's plan. - `payout_currency_not_in_plan` (source `plan`, plan field `payout_currencies`): This payout currency isn't in the agent's plan. - `amount_over_max_per_payment` (source `plan`, plan field `max_per_payment`): This amount is over the plan's limit for a single payment. - `max_per_day_reached` (source `plan`, plan field `max_per_day`): This payment would take the agent over its plan's daily limit. - `plan_expired` (source `plan`, plan field `expires_at`): The agent's plan has expired. A person needs to renew it. - `plan_not_active` (source `plan`): The agent's plan isn't in force: it has been revoked or hasn't taken effect yet. - `agent_frozen` (source `plan`): The agent is frozen. A person can unfreeze it. - `invoice_terms_not_allowed` (source `policy`, plan field `invoice_terms`): The business's policies don't allow paying invoices on these terms. - `outside_payment_timing` (source `policy`, plan field `payment_timing`): The business's policies don't allow paying at this time. - `fx_rate_outside_limit` (source `policy`, plan field `max_fx_deviation_bps`): The exchange rate is further from mid-market than the business's policy allows. - `quote_expired` (source `policy`): The quote for this payout has expired. Request a new quote. - `compliance_review` (source `compliance`): This payment is being reviewed by compliance. - `unusual_activity` (source `compliance`): This payment looks unusual and is held for review. - `information_requested` (source `compliance`): Compliance needs more information before this payment can go ahead. - approval reasons (status `pending_approval`): - `above_approve_above`: This amount is above the plan's approval threshold, so a person must approve it. - `approval_rule_matched`: One of the business's approval rules applies, so it needs approval first. - `stronger_method_required`: An approval was recorded, but the rule needs a stronger approval method. - activity entry types (list_activity type): `api_call`, `alert.raised`, `alert.acknowledged`, `alert.resolved`, `approval.recorded`, `approval.declined`, `escalation.approved`, `compliance.information_provided`, `signer.add_requested`, `signer.added`, `signer.removed`, `signer.device_added`, `signer.device_removed`, `unfreeze`, `workspace_settings.changed` - money: Money is an object in integer minor units (cents): 1,250.00 USD is {"value": 125000, "currency": "USD"}. Never a decimal, a string or a bare number. ## Test-only (sandbox) These exist only in the sandbox, to test against: in live the endpoints answer 404 and the tools are not listed. They act only on your own agent, with your own key. The simulate field on pay and create_payout is test-only too. - `sandbox_deposit`: Test only (sandbox): fund your own agent with test money. USD auto-converts to USDC unless the workspace turned that off. Incoming money is never refused. - `sandbox_set_fx`: Test only (sandbox): move your own simulated mid-market rate or spread for PHP, AED or SGD, to see how max_fx_deviation_bps holds a payout. Only your agent sees the change. - `sandbox_return`: Test only (sandbox): the receiving bank returns one of your cleared payments or delivered payouts; the money comes back to your account. For a failed payment, pay with simulate.outcome "failed". - POST /v1/sandbox/deposits: Test only: fund your own agent with test money - POST /v1/sandbox/fx: Test only: move your own simulated mid-market rate or spread - POST /v1/sandbox/returns: Test only: have a cleared payment or delivered payout returned