Developers
API Reference
The Agent API lets software act for an agent-held sub-wallet: read its state, fetch its sealed key, hand over a transaction it signed itself, and read its history. The base URL is https://api.numerari.io, and every route lives under /api/agent/v1.
Early access
The Agent API and the numerari-agent kit are in early access. The Agent API is deployed: a request to https://api.numerari.io/api/agent/v1/wallet without a valid access key returns 401 invalid_access_key. The kit is not yet published for public download. There is no per-account switch to ask for. Questions: support@numerari.io.
How credentials work
An agent wallet has two separate secrets. Together they let an agent act. Neither one alone can.
- Access key. It looks like nmr_ak_<id>_<secret>. It opens Numerari’s gate: it identifies the wallet and lets the agent call the API. Numerari stores only a one-way hash of it, and the owner can replace it by rotating it. It also stops working when the wallet is revoked or the team member holding the wallet is deactivated. There is no separate way to revoke only the key.
- Signing secret. It looks like nmr_ss_<secret>. It is created in the owner’s browser and is never sent to Numerari in any form. The wallet’s key is sealed with it, so only the holder of the secret can open the key.
- Seed phrase. This is the owner’s recovery words. It is never shared with an agent, an employee or Numerari.
Because Numerari holds the sealed key but not the signing secret, we cannot sign anything for an agent. Signing happens on the agent’s own machine. The owner downloads the credential file when the wallet is created, and it cannot be shown again. Rotating the access key produces a new credential file.
Authenticating a request
Put the access key in a bearer header on every request. There is no other session.
Authorization: Bearer nmr_ak_EXAMPLEID1_example-secret-do-not-useEndpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/agent/v1/wallet | Address, status, policy, holder and supported chains. Readable while the wallet is paused. |
| GET | /api/agent/v1/wallet/sealed-key | The sealed key blob. Only while the wallet is neither paused nor revoked. |
| POST | /api/agent/v1/transactions/relay | Checks a signed transaction against the wallet’s policy, then broadcasts it. |
| GET | /api/agent/v1/transactions | History of transactions relayed for this wallet, newest first. |
GET /api/agent/v1/wallet
Returns the wallet’s state and the chains and tokens the relay accepts.
curl https://api.numerari.io/api/agent/v1/wallet \
-H "Authorization: Bearer nmr_ak_EXAMPLEID1_example-secret-do-not-use"
{
"sub_wallet_id": "00000000-0000-0000-0000-000000000000",
"bot_name": "example-agent",
"address": "0x0000000000000000000000000000000000000000",
"status": "active",
"paused_at": null,
"holder": { "type": "agent", "label": "example-agent" },
"policy": {
"max_per_tx_units": "50.000000",
"max_per_day_units": "200.000000",
"allowed_recipients": []
},
"chains": [
{
"chain_id": 1,
"name": "Ethereum Mainnet",
"native_symbol": "ETH",
"tokens": [{ "symbol": "USDT", "contract_address": "0x...", "decimals": 6 }]
}
]
}status is active, paused or revoked. Policy amounts are decimal strings in USD-stablecoin units with six decimal places, and null means no limit of that kind. An empty allowed_recipients list means any recipient.
GET /api/agent/v1/wallet/sealed-key
Returns the sealed key as an opaque blob. The agent opens it locally with the signing secret. The response is marked Cache-Control: no-store, and each fetch is recorded in the wallet’s event log.
{ "sealed_key": "<opaque base64 blob>", "blob_version": 1 }POST /api/agent/v1/transactions/relay
The agent signs a transaction itself and hands over the raw bytes. Numerari decodes it (it never signs), checks it, and broadcasts it. The body is limited to 64 KB.
curl -X POST https://api.numerari.io/api/agent/v1/transactions/relay \
-H "Authorization: Bearer nmr_ak_EXAMPLEID1_example-secret-do-not-use" \
-H "Content-Type: application/json" \
-d '{ "chain_id": 8453, "raw_tx": "0x02f8..." }'
{
"tx_hash": "0x...",
"chain_id": 8453,
"status": "broadcast",
"to": "0x0000000000000000000000000000000000000000",
"token_symbol": "USDC",
"amount_units": "12.500000"
}Before broadcasting, the relay checks that:
- chain_id is a supported chain and matches the chain the transaction was signed for.
- the transaction was signed by this wallet’s own key.
- it is a plain two-argument token call on a supported token contract, or a plain native-currency call with no data. Approvals, other contract calls and contract creation are refused.
- the recipient is on the allow-list, if the owner set one.
- the amount is within the per-transaction limit and the rolling 24-hour limit, if the owner set them.
- native-currency calls are refused with unsupported_asset while any amount limit is set, because a native amount has no USD value we can trust.
- native-currency calls with no amount limits are allowed only when the owner has set a recipient allow-list. Without one they are refused with recipient_not_allowed, because an uncapped native call has no other bound.
Submitting the same signed bytes again never broadcasts a second transaction. If the earlier attempt was broadcast or confirmed, it returns that outcome. If it is still being relayed, it returns relay_in_progress. If the earlier outcome was unknown, the relay re-broadcasts the identical bytes, which is safe on chain. A resubmission is checked again like any other request, so if the owner has since paused the wallet or tightened a limit, you get that refusal instead of the earlier outcome. A resubmission can also return daily_limit_exceeded without any change by the owner, for example when it arrives more than 24 hours after the original was reserved and other transactions now fill the window. If a node refuses a resubmission, you get broadcast_unconfirmed rather than broadcast_failed, because the earlier attempt may already be on the network. If you receive broadcast_unconfirmed, resend the identical signed bytes (do not sign a new transaction) to learn the result.
GET /api/agent/v1/transactions
Optional query parameters are limit (default 100, at most 100) and offset.
{
"transactions": [
{
"id": "00000000-0000-0000-0000-000000000000",
"chain_id": 8453,
"tx_hash": "0x...",
"from": "0x...",
"to": "0x...",
"token_symbol": "USDC",
"token_address": "0x...",
"amount_units": "12.500000",
"status": "broadcast",
"failure_code": null,
"created_at": "2026-01-01T00:00:00Z",
"confirmed_at": null,
"block_number": null
}
],
"total": 1,
"limit": 100,
"offset": 0
}A relayed transaction’s status is one of five values. Branch on all of them.
| Status | Meaning |
|---|---|
| pending | Accepted and recorded, not yet broadcast. |
| broadcast | Handed to the network. Not yet seen mined. |
| unknown | The outcome is not known: the transaction may or may not be on the network. failure_code says why: broadcast_unconfirmed (the network did not confirm), node_hash_mismatch (the node returned an unexpected hash) or receipt_timeout (no receipt was found in time). Resend the identical signed bytes to learn the result. It counts toward the daily limit for 24 hours from the time it was reserved (reserved_at), after which it no longer does. |
| confirmed | Mined successfully. Set later by Numerari’s reconciler, so a transaction can read broadcast for a while first. |
| failed | The node rejected the transaction (failure_code broadcast_failed), or it was mined and reverted (failure_code reverted). A failed transaction frees its daily-limit slot. Policy refusals never create a row, so they do not appear in history. |
confirmed_at and block_number stay null until the transaction is mined. The relay response can also return status confirmed when you resubmit bytes that were already mined.
Errors
Every error has the same shape, with a human-readable message and a stable code to branch on.
{ "error": "the amount exceeds this wallet's per-transaction limit", "code": "per_tx_limit_exceeded" }| HTTP | Code | Meaning |
|---|---|---|
| 401 | invalid_access_key | The key is malformed, unknown or wrong. |
| 401 | access_key_revoked | The owner revoked or rotated this key. |
| 401 | holder_disabled | The team member holding this wallet was deactivated. |
| 403 | wallet_paused | The owner paused the wallet. Reads still work. |
| 403 | wallet_revoked | The wallet was revoked. |
| 403 | merchant_disabled | The merchant account that owns this wallet was disabled. Reads and relays are both refused. |
| 400 | invalid_request | The body must be JSON with chain_id and raw_tx. |
| 400 | invalid_transaction | raw_tx is not valid hex or not a supported signed transaction. |
| 409 | relay_in_progress | The same transaction is already being relayed. |
| 422 | chain_not_supported | chain_id is not a supported chain. |
| 422 | chain_mismatch | The transaction was signed for a different chain than chain_id. |
| 422 | from_mismatch | The transaction was not signed by this wallet’s key. |
| 422 | unsupported_transaction | Not a plain token call or plain native call (for example an approval or contract creation). |
| 422 | unsupported_asset | A native-currency call while amount limits are set. |
| 422 | recipient_not_allowed | The recipient is not on the allow-list, or the call is a native-currency one with no amount limits and the wallet has no allow-list at all. |
| 422 | per_tx_limit_exceeded | The amount is over the per-transaction limit. |
| 422 | daily_limit_exceeded | The amount would put the wallet over its rolling 24-hour limit. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After header, in seconds. |
| 502 | broadcast_failed | The network node answered and rejected a first submission. If the node could not be reached, or it refused a resubmission, you get broadcast_unconfirmed instead. |
| 502 | broadcast_unconfirmed | The outcome is unknown (including when the node could not be reached). Resend the identical signed bytes. |
| 500 | internal_error | Something went wrong on our side. |
Rate limits
Limits apply per client address before the key is even checked, and per key once its secret has verified. Exceeding one returns 429 with a Retry-After header.
| Limit | Value |
|---|---|
| Any request from one client address | 120 per minute |
| Failed authentications from one client address | 20 per 5 minutes (successful requests do not count) |
| Read routes, per key | 60 per minute |
| Relay route, per key | 10 per minute |
Counters are kept in memory on each server process, so treat these as approximate ceilings rather than exact quotas.
The numerari-agent kit
One binary that works as a command-line tool and as a stdio MCP server. It fetches the sealed key with the access key, opens it locally with the signing secret, signs, and then zeroes the key. The key and the blob are never written to disk, and the credential is never logged.
The kit is not yet published for public download. If you are an early-access partner, we will send you the binary directly.
Credential file
The owner downloads this JSON file when the wallet is created, and again after each rotation. Keep it private. Pass it with --credential FILE or set NUMERARI_AGENT_CREDENTIAL. On Unix the kit refuses a credential file that is readable by other users, so a file downloaded through a browser needs chmod 600 (owner-only) before it will work.
{
"bot_name": "example-agent",
"wallet_address": "0x0000000000000000000000000000000000000000",
"api_base_url": "https://api.numerari.io",
"access_key": "nmr_ak_EXAMPLEID1_example-secret-do-not-use",
"signing_secret": "nmr_ss_example-secret-do-not-use"
}Commands
| Command | What it does |
|---|---|
| address | Prints the wallet address. |
| status | Shows whether the wallet is active, paused or revoked, and its policy. |
| balances | Reads balances from the chain. |
| history [--limit N] [--offset N] | Lists transactions relayed for this wallet, one page at a time. |
| send --token USDC --chain base --to 0x.. --amount 12.50 | Signs locally and relays one transaction. |
| resubmit --chain base --raw-tx 0x.. | Re-posts an already signed payment after an unclear outcome. It never signs anything. |
| mcp | Runs the MCP server over stdio. |
Chain access defaults to public RPC endpoints. Override them with NUMERARI_RPC_BASE and NUMERARI_RPC_ETHEREUM.
Fee caps
Before signing, the kit refuses a transaction whose maximum fee per gas, or whose total gas cost, is above a per-chain cap. It also refuses the send if it cannot read the gas balance, and it refuses payments to the zero address or to the token contract itself. Defaults are 5 gwei and 0.002 ETH on Base, and 150 gwei and 0.02 ETH on Ethereum. Override them with NUMERARI_MAX_FEE_GWEI_BASE, NUMERARI_MAX_FEE_GWEI_ETHEREUM, NUMERARI_MAX_TOTAL_FEE_ETH_BASE and NUMERARI_MAX_TOTAL_FEE_ETH_ETHEREUM.
When a send has an unclear outcome
If the relay answers with a server error or broadcast_unconfirmed, times out, or cannot be reached, the kit does not report a refusal, because the payment may be on the network. The send result is outcome_unknown, and it carries the tx_hash and the signed raw_tx. The kit keeps the signed payment and resubmits the same bytes; it never signs a second payment for the same send. The relay treats identical bytes as the same payment, so resubmitting is safe.
- Do not send again. A new send signs a new payment and could pay twice.
- Check history and the chain for the tx_hash.
- If the payment is absent, use resubmit with the same chain and the raw_tx from the result. From the CLI pass --chain and --raw-tx. In a running MCP server you can refer to the payment by its tx_hash instead.
- While a payment is unresolved, send refuses further payments on that chain.
MCP tools
| Tool | What it does |
|---|---|
| get_wallet | Wallet address, status and policy. |
| get_balances | Balances from the chain. |
| get_history | Relayed transaction history, with optional limit and offset. |
| send | Signs and relays a transaction. Requires confirm: true in the tool call. Returns outcome_unknown when the result is unclear. |
| resubmit | Re-posts the same signed payment after an unclear outcome. It never signs. |
The send tool does nothing unless the call includes confirm: true. The agent sets that flag itself, so it guards against accidental calls. It is not an approval step: use the wallet’s limits and pause to control what an agent can do.
Add the server to your MCP client with a config like this:
{
"command": "numerari-agent",
"args": ["mcp"],
"env": { "NUMERARI_AGENT_CREDENTIAL": "/path/to/credential.json" }
}What pause and limits do not cover
Be clear-eyed about this one. Pausing a wallet, revoking its access key, and the spending policy (per-transaction limit, daily limit, recipient allow-list) apply to transactions relayed through Numerari. That is where we enforce them.
They do not stop an agent that still holds both the signing secret and a sealed key it already fetched. That agent could sign a transaction and broadcast it straight to the network without us. If you think an agent’s credential has leaked, move the funds to a new wallet first, then revoke this one. Revoking does not move any money, and rotating the access key re-seals the same wallet key, so the old address stays exposed until it is empty. Do not rely on pause alone.
Keep the balance in an agent wallet to what you are comfortable having that agent control.