Payments

Link a wallet with a passkey to let an agent pay for 402-gated requests. Scoped permissions, approval checks, and receipts limit and record spending.

How it works

The paid_fetch tool can pay when a resource returns 402 Payment Required. After authorization and settlement, it returns the response body and a receipt. The control plane signs using a delegated access key for your linked wallet. The sandbox receives no signing keys.

Payment authorization has four requirements:

  • Caller ownership. Payments use the requesting person's linked wallet. The tool does not substitute a shared or platform account.
  • Approval. The paid_fetch tool requires approval independently of whether the conversation has read outside content. The approval card shows the amount and destination.
  • Receipts. Each settlement records a signed receipt with its amount and onchain reference. Use the reference to check the payment on the explorer.
  • Expiration. Linking authorizes a delegated key with spending limits and an expiration time. Once it expires, payment requires you to authorize a new key with your passkey. You can revoke the delegated key from your wallet before it expires.
Payment requests use the control plane's delegated key. Human approval precedes settlement. The control plane records a signed receipt in the event log. The harness holds no payment signing key.sandboxHarnessrun_turn · no payment keyUpstream servicereturns HTTP 402Key custodydelegated keyControl planethe only signerHumanapprovesYour walletpasskey · your fundsSettlementTempo networkEvent logsigned receiptGET402paid_fetchapprove?approvedresolve keyauthorizesign + settlereceipt
unary callstreamasync / eventual

Ask to link a wallet, open the one-time link, and authorize spending with your passkey. Your passkey stays on your device. The control plane stores the delegated access key in a Kubernetes Secret or the configured local key directory. Your persona stores a reference to that key. The sandbox never receives the key material.

A testnet deployment can fund newly linked wallets when TEMPO_TESTNET_FAUCET is enabled. This option is off by default. To request a wallet link:

Shell
you:    link a wallet
agent:  Here's a secure link to set up your spending wallet: …
        (open it, approve with your passkey, done)

Check and manage your wallet

Use the wallet tools to check your balance, inspect payment history, or manage your wallet link. These tools do not transfer funds.

Ask forWhat you get
"what's my wallet / balance / am I linked?"Your wallet's address, whether it's linked and ready to pay, its balance, and the network
"what have I spent / show my payments"Your payments in this conversation: amount, settlement reference, a verified explorer link, and when each settled
"link a wallet"A fresh one-time link to set up or replace your spending wallet
"unlink my wallet / stop using it"Removes your wallet link and prevents further payments through it. You can link a wallet again.
"list everyone's wallets" (admins)Conversation participants and whether each has linked a wallet. Only admins can view this roster.

Asking to list or inspect your wallet does not initiate a payment.

Payment controls

Your passkey authorizes a delegated key with spending limits and an expiration time. You can revoke that key from your wallet. Payment requests also pass these checks:

  • Wallet ownership. A caller can pay only from their own linked wallet.
  • Access controls. Participants can inspect their own balances, payment history, and wallet links. The admin roster requires a durable administrator permission.
  • Caps and budgets. The linked key carries onchain spend limits, and the control plane enforces per-request and per-conversation ceilings before signing.
  • Approval. paid_fetch declares approval as an intrinsic requirement. This check applies even before the conversation reads outside content. See Trust for approval policies.

Configuration

Payments are off until a deployment configures them. The settlement network and wallet-link page use these settings:

EnvWhat it does
TEMPO_RPC_URLSettlement network endpoint the control plane signs and reads balances against
POLYCHROME_WALLET_KEYS_DIRLocal directory that holds each linked wallet's delegated signing key. Optional: set it for a filesystem deployment, or leave it unset in-cluster to keep each key in its own Kubernetes Secret automatically
POLYCHROME_WALLET_LINK_URLPublic base URL of the wallet-link page the one-time card points at
TEMPO_TESTNET_FAUCETTestnet only: auto-fund a freshly linked wallet so its first payment can cover the onchain fee. Off by default; never set on mainnet
TEMPO_CURRENCY, TEMPO_CURRENCY_DECIMALSSettlement-token contract and its decimal scale, for amounts and balances

The wallet tools are built-in, so an agent scoped to an explicit tool set needs wallet_status, wallet_history, wallet_link, wallet_roster, and unlink_self in its allowlist. unlink_self removes the caller's own linked email or wallet by a target argument.