Docs/For AI agents

Agents have CPUs, not ETH.

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. Unlinked removes that step: the paymaster pays for an operation of a fresh EIP-7702 address when it carries a valid proof of work (8 keccak sub-solutions, seconds of CPU on a laptop), co-signed by the relay. The agent's address never holds 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 Unlinked monorepo (Node 22+, pnpm)
$ cd /path/to/unlinked
$ pnpm install
$ pnpm --filter @unlinked/miner build   # the Node miner loads its WASM build
$ node packages/agent/bin/unlinked.mjs --help

Keys are generated on the machine that runs the agent and stored encrypted in a local keystore: ~/.unlinked (or UNLINKED_HOME), directories 0700 and files 0600, sealed with AES-256-GCM under a scrypt key derived from UNLINKED_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 (unlinked mcp). The network is never chosen by the agent: set UNLINKED_NETWORK to mainnet or local in the client's configuration.

$ claude mcp add --transport stdio --scope user \
    --env UNLINKED_NETWORK=mainnet \
    --env UNLINKED_PASSPHRASE="$UNLINKED_PASSPHRASE" \
    --env UNLINKED_MAX_AMOUNT='USDG=50,ETH=0.01' \
    unlinked -- node /path/to/unlinked/packages/agent/bin/unlinked.mjs mcp

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

{
  "mcpServers": {
    "unlinked": {
      "command": "node",
      "args": [
        "/path/to/unlinked/packages/agent/bin/unlinked.mjs",
        "mcp"
      ],
      "env": {
        "UNLINKED_NETWORK": "mainnet",
        "UNLINKED_PASSPHRASE": "${UNLINKED_PASSPHRASE}",
        "UNLINKED_MAX_AMOUNT": "USDG=50,ETH=0.01"
      }
    }
  }
}

A typical session: unlinked_network → unlinked_create_account → (the account receives assets) → unlinked_quote_send → unlinked_send → unlinked_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 unlinked_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#

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 unlinked='node /path/to/unlinked/packages/agent/bin/unlinked.mjs'
$ export UNLINKED_NETWORK=mainnet UNLINKED_PASSPHRASE='…'
$ unlinked 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)
$ unlinked quote --to 0x2b1d…09fC --amount 12.5 --asset USDG --json
{"ok":true,"result":{"quoteId":"q_9b1e…","gas":{"sponsored":true,"paidBySenderWei":"0",…},"estimatedSeconds":41,…}}
$ unlinked send --quote q_9b1e… --json        # progress on stderr
{"ok":true,"result":{"status":"included","success":true,"userOpHash":"0x…","transactionHash":"0x…",…}}
$ unlinked status 0x… --json

A quote made by one unlinked quote process is consumed by another unlinked 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 UNLINKED_NETWORK is set; local reads the e2e stack descriptor. UNLINKED_RELAY_URL and UNLINKED_RPC_URL accept https, or plain http on a loopback host only.
• Caps per send. UNLINKED_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 UNLINKED_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#

• Unlinked is not a mixer: it pays gas for one operation at a time and never pools, holds or hides assets.
• 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 (unlinked_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 unlinked_send pauses a random time (up to 20 s) before mining, as the SDK does after its own reads: the relay cannot time the mining from that read. And proof of work is a rate limiter, not a guarantee: when the epoch budget is used up, sends wait for the next epoch.

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.