Docs/For AI agents

Agents buy stamps, not gas.

Why it fits agents#

A wallet-holding agent normally needs ETH before it can do anything, and topping it up from the operator's wallet writes a public link between the two. Stamp removes that step: the paymaster pays for an operation of a fresh EIP-7702 address when it carries a stamp, co-signed by the relay. A prepaid stamp comes from a booklet the agent bought once, in ETH, from a payer account; the relay signed it blind, so it cannot tell which purchase a later operation's stamp came from. A mined stamp is 8 keccak sub-solutions, seconds of CPU on a laptop, paid from each epoch's small free budget. The agent's fresh addresses never hold ETH for gas.

What stays visible is everything else. The tokens an address receives link their sender to it, the relay sees the IP address and the time of each send, and every operation is public on chain. The limits are written into the server's instructions and into the descriptions of the tools that lead to a send, so the model reads them too.

Install#

# From a checkout of the monorepo (Node 22+, pnpm)
$ cd /path/to/paravion
$ pnpm install
$ pnpm --filter @paravion/miner build   # the Node miner loads its WASM build
$ node packages/agent/bin/paravion.mjs --help

Keys are generated on the machine that runs the agent and stored encrypted in a local keystore: ~/.paravion (or PARAVION_HOME), directories 0700 and files 0600, sealed with AES-256-GCM under a scrypt key derived from PARAVION_PASSPHRASE. The MCP server has no tool that returns a key; only the CLI's account export prints one, after an explicit flag and a confirmation typed on a terminal.

Connect an MCP client#

The server speaks MCP over stdio (paravion mcp). The network is never chosen by the agent: set PARAVION_NETWORK to mainnet or local in the client's configuration.

$ claude mcp add --transport stdio --scope user \
    --env PARAVION_NETWORK=mainnet \
    --env PARAVION_PASSPHRASE="$PARAVION_PASSPHRASE" \
    --env PARAVION_MAX_AMOUNT='USDG=50,ETH=0.01' \
    paravion -- node /path/to/paravion/packages/agent/bin/paravion.mjs mcp

{
  "mcpServers": {
    "paravion": {
      "command": "node",
      "args": [
        "/path/to/paravion/packages/agent/bin/paravion.mjs",
        "mcp"
      ],
      "env": {
        "PARAVION_NETWORK": "mainnet",
        "PARAVION_PASSPHRASE": "a-long-passphrase-only-this-config-knows",
        "PARAVION_MAX_AMOUNT": "USDG=50,ETH=0.01"
      }
    }
  }
}

{
  "mcpServers": {
    "paravion": {
      "command": "node",
      "args": [
        "/path/to/paravion/packages/agent/bin/paravion.mjs",
        "mcp"
      ],
      "env": {
        "PARAVION_NETWORK": "mainnet",
        "PARAVION_PASSPHRASE": "${PARAVION_PASSPHRASE}",
        "PARAVION_MAX_AMOUNT": "USDG=50,ETH=0.01"
      }
    }
  }
}

A typical session: paravion_network → paravion_buy_stamps (once, from a payer) → paravion_create_account → (the account receives assets) → paravion_quote_send with postage: "stamp" → paravion_send → paravion_get_operation. A send always needs a fresh quote: the quote is the dry run (amount, guardrails, recipient, balance, gas sponsored, work and time), and paravion_send executes exactly what it describes, once, within about 120 seconds. While it mines and waits for inclusion, the server sends notifications/progress to clients that ask for them, and a cancelled call stops mining.

Tools#

Prepaid stamps#

• Buying. paravion_buy_stamps (paravion stamps buy --count N --payer ADDRESS) buys 1 to 100 stamps from the PostOffice, paid in ETH by payer, an account of the local keystore that holds ETH. The serials are drawn and blinded on the agent's machine, the relay signs them blind, and the unblinded stamps are saved, encrypted. The tool spends ETH irreversibly and is marked destructive; stamps are never refunded.
• The payer is public. The purchase names it on chain. The agent records every payer and refuses to use a stamp for a payer's own operations: that would tie the stamps to their purchase in plain sight.
• Saved stamps. <PARAVION_HOME>/carnet/<network>.json, encrypted under PARAVION_PASSPHRASE with the SDK's format (PBKDF2-SHA-256 at 600,000 iterations, AES-256-GCM): a stamp file exported from the web app imports here, and back. Writes are serialized across processes. paravion_list_stamps shows usable stamps by expiry, pending booklets and payers, and finishes the issuance of a booklet that was paid but not issued yet.
• Spending. postage: "stamp" (--postage stamp) in the quote makes the send use one saved stamp instead of mining. The stamp is removed once the paymaster has cancelled it on chain.
• Privacy advice, in the tools too. Buy well before you send, buy several at once, and reach the relay over Tor or a VPN: it sees the IP address at purchase and at use.

Every tool returns structuredContent that matches its published output schema, and the same JSON as text. Errors are tool results with isError and a JSON { "error": { "code", "message", "details" } }, where code is stable: GUARDRAIL_CAP, RECIPIENT_REFUSED, INSUFFICIENT_BALANCE, QUOTE_EXPIRED, QUOTE_USED, RELAY_REFUSED (with the relay's reason and retryAt), RATE_LIMITED, and so on.

The CLI#

For agents that shell out instead of speaking MCP. Every command takes --json and then prints exactly one JSON object on stdout, {"ok":true,"result":…} or {"ok":false,"error":…}; progress goes to stderr. Exit codes: 0 success, 1 failure, 2 usage or configuration error, 130 interrupted.

$ alias paravion='node /path/to/paravion/packages/agent/bin/paravion.mjs'
$ export PARAVION_NETWORK=mainnet PARAVION_PASSPHRASE='…'
$ paravion account new --json
{"ok":true,"result":{"account":{"address":"0x8f3c…41aE","network":"mainnet",…}}}

# someone sends the account some USDG (that transfer links the sender to it, publicly)
$ paravion quote --to 0x2b1d…09fC --amount 12.5 --asset USDG --json
{"ok":true,"result":{"quoteId":"q_9b1e…","gas":{"sponsored":true,"paidBySenderWei":"0",…},"estimatedSeconds":41,…}}
$ paravion send --quote q_9b1e… --json        # progress on stderr
{"ok":true,"result":{"status":"included","success":true,"userOpHash":"0x…","transactionHash":"0x…",…}}
$ paravion status 0x… --json

A quote made by one paravion quote process is consumed by another paravion send process: quotes live as 0600 files in the keystore home and are claimed with an atomic rename, so two sends of one quote cannot both run.

Guardrails#

• The network is explicit. Nothing runs until PARAVION_NETWORK is set; local reads the e2e stack descriptor. PARAVION_RELAY_URL and PARAVION_RPC_URL accept https, or plain http on a loopback host only.
• Caps per send. PARAVION_MAX_AMOUNT=USDG=50,ETH=0.01 caps each send by symbol, in the asset's own decimals; *=0 blocks every asset you did not list. A malformed value stops the agent instead of running without the cap.
• Recipient allowlist. With PARAVION_ALLOWED_RECIPIENTS, any other recipient is refused.
• The relay's recipient rule for every send. A recipient must be an address without code or an EOA delegated to Simple7702Account v0.9, never the sender itself or a reserved address. The relay enforces it for ETH; the agent applies it to token sends too, so an agent never sends tokens into a contract.
• Checked twice. The quote checks the guardrails, the recipient and the balance; the send checks the guardrails again (a CLI quote and its send are separate processes).
• No key in any output. Tool results, errors, progress messages and logs go through a scrubber that knows every key the process decrypted (by hash) and the passphrase; library errors are reduced to their short message, with URLs cut to their origin.

Honest limits#

• Stamp is not a mixer: it pays gas for one operation at a time and never pools, holds or hides assets. Stamps pay gas only and are never refunded.
• Assets an address receives link the sender to it, publicly and permanently.
• The relay sees your IP address and when you send. It keeps no logs, but you are trusting that; run your own relay or use Tor if it matters.
• Every operation is public on chain: sender, recipient, token, amount and time.
• Robinhood stock tokens are not offered to persons in the US, Canada, the UK or Switzerland.

A few more facts an agent should know. Reads keyed to an address go to the relay only, one account at a time (paravion_list_accounts reads nothing, so the relay cannot see your accounts side by side), and the relay rate-limits them: 10 per minute for pow_getAccountState and pow_checkRecipient together, 60 for epoch and receipt reads. A quote reads the sender's balance, so paravion_send pauses a random time (up to 20 s) before mining or sending, as the SDK does after its own reads: the relay cannot time the send from that read. And proof of work is a rate limiter, not a guarantee: when the epoch's free budget is used up, mined sends wait for the next epoch; stamped sends do not draw on that budget.

Relay JSON-RPC#

The agent talks to the relay's public JSON-RPC API. Its machine-readable description is an OpenRPC document, /openrpc.json (OpenRPC 1.4), derived from the relay's code and checked against it by the agent's tests, and against a live relay by its end-to-end run.

Next steps#

• Privacy guideWhat still links an address to you, and what to do about each.
• Run your own relayThe relay's check order, configuration and bundler setup.
• How it worksThe wire format, the challenge and how much work an op costs.