ada-agent-wallet

Out-of-process spend control for AI agents that pay with x402. The agent gets MCP tools that can pay — for an HTTP endpoint, or for a paid tool on another MCP server — and never holds the key. That sits in a separate daemon, which enforces the spend policy, queues what needs a human, and writes a hash-chained audit log the agent cannot rewrite to hand itself more budget.

Why a separate process: @x402/core's spend controls and @x402/mcp's onPaymentRequested hook — the two places the official stack puts a limit — both run inside the agent. An agent that has been steered can be steered through them. These limits live where the key lives.

Settles on Cardano, through the official @x402/cardano and @x402/mcp clients — nothing forked.

Status: 0.2.9, preprod only. It has never run on mainnet and has had no external security review. signerd holds a decrypted mnemonic in memory for as long as it runs — that is what a hot wallet is — so keep in it only what you would accept losing outright, and set MAX_HOT_BALANCE_LOVELACE before pointing it at real funds. Apache-2.0: provided as is, without warranty; the risk of running it is yours.

agent (Claude / any MCP client)
   └── mcp.ts        wallet_status · x402_fetch(url) · x402_mcp_tools/call(server, tool)  ← no keys
         ├── gatedSigner.ts  implements ClientCardanoSigner, forwards to ↓
         └── batchProxy.ts   the batch-settlement scheme, forwards to ↓
signerd.ts   127.0.0.1 only, bearer token, holds the mnemonic
   ├── policy.ts    per-tx max · rolling-24h max · payee, resource, asset and transfer-method
   │                allowlists · per-hour rate · approval threshold · channel deposits and keys
   ├── replay.ts    rebuilds the 24h spend window at startup, and checks what it rebuilds from
   ├── expiry.ts    which signed payments the chain has moved past, and reading that from Koios or
   │                Blockfrost: the only way a spend's budget comes back
   ├── retry.ts     which provider read failures are worth a second try, and the retrying
   ├── serialize.ts one lock per agent for the cap, one per wallet for signing
   ├── keystore.ts  scrypt + AES-256-GCM, so the mnemonic is not plaintext at rest
   ├── verifyTx.ts  reads back the signed transaction: does it pay who was authorised, only them
   ├── channelTx.ts the same for channel transactions: deposits, top-ups, refunds, exits
   ├── tidy.ts      the UTxO layout channel steps need, the plan to reach it, and the same
   │                read-back for the one transaction that does
   ├── ledger.json  the spend state the cap is computed from, rewritten after every signature
   ├── audit.jsonl  every decision, hash-chained, the checkpoint pointing into it
   ├── tokens.json  optional: a token per agent, so `agentId` is not self-reported
   ├── channels/    batch-settlement: what was signed on each channel (channelStore.ts), and
   │                subbit-x402's channel records, one directory per agent
   └── @x402/cardano toClientCardanoSigner (Koios by default, Blockfrost optional)
       subbit-x402   the batch-settlement channel client (preprod, Blockfrost)
walletctl.ts  status | preflight | pending | approve <id> | deny <id> | audit
              channels | refund | close | end | elapse | recover | tidy

ledger.json and audit.jsonl are deliberately two files: the cap is state, the log is a log, and conflating them meant rm audit.jsonl handed a spent agent its budget back.

What @x402/core already has: a per-payment USD cap and an asset allowlist, inside the agent process — and @x402/mcp puts its onPaymentRequested approval hook in the same place. What this adds: key isolation, rolling daily/hourly limits, payee allowlist, human approval, audit trail — enforced in the process that holds the key, so an agent cannot loosen its own limits. Masumi's Payment Service (the other Cardano agent-payment stack) has none of these on the buying side.

Install

npm i -g ada-agent-wallet

Node 22 or newer (Node 20 reached end of life in April 2026), on Linux, macOS or Windows; CI runs the tests on all three. Five commands: ada-signerd, ada-wallet-mcp, ada-walletctl, ada-keystore, and ada-agent-wallet (the MCP server again, so an agent config line is npx -y ada-agent-wallet). To work on the code instead, clone this repo and use the flow below.

Related MCP server: @hpp-io/x402-mcp-bridge

Run (preprod)

npm install
cp policy.example.json policy.json            # edit the limits; amounts are in the asset's smallest unit
export SIGNERD_TOKEN=$(openssl rand -hex 16)
export WALLET_MNEMONIC_FILE=~/.ada-agent-wallet/mnemonic   # 24 words, chmod 600
export CARDANO_NETWORK=cardano:preprod                     # or cardano:preview; Koios, no API key needed
npm run signerd                                            # prints the address → fund it from the preprod faucet

The policy file declares the network it was written for, and signerd refuses to start on a mismatch. A plaintext mnemonic is fine for a faucet wallet; for anything else see "The key" below.

Koios is enough for signerd and, since @evolution-sdk/evolution 0.5.14, a whole exact 402 round-trip: before it, the facilitator's verify step could not read most UTXOs through Koios (see "Known behaviour worth expecting"). signerd's batch-settlement runs on Koios too, since 0.2.4 on subbit-x402 0.1.4. The dev/ drivers that reconcile a run against the chain (batch, batchend, batchexit, batchsponsored, contention and mcpbatch) read it through Blockfrost, and need BLOCKFROST_PROJECT_ID.

Where the policy, audit and ledger files live is part of the security model. The daily cap is computed from ledger.json, rebuilt where needed by replaying audit.jsonl, and the limits themselves are re-read from policy.json on every decision. An agent that can write any of the three raises its own budget without going near the key. Put all of them where the agent's user cannot write, and run signerd as a different user. signerd prints the absolute paths at startup so this is checkable rather than assumed.

The example policy's allowedResources names the two local dev sellers — http://127.0.0.1:7401/* for HTTP, http://127.0.0.1:7404/* for MCP — alongside a placeholder, so the round-trips below work from a fresh copy; drop both dev entries before the file governs anything real. The list applies to MCP tool calls too: the resource checked is the MCP server's URL.

Two defaults in policy.example.json are deliberately conservative and worth a look before you widen them: allowedPayees: ["*"] accepts any payee, which is only reasonable while the agent is talking to endpoints you chose; and allowedAssetTransferMethods: ["default"] refuses masumi escrow, whose cost is not only amount — it also locks buyer collateral that no field in the policy can see, up to the SDK's 15 ADA ceiling, and not released until the contract's submit_result_time. Enabling masumi means accepting that charge; bound it with MASUMI_MAX_COLLATERAL_LOVELACE. MCP registration (Claude Desktop / Code / Cowork):

{ "mcpServers": { "ada-wallet": { "command": "npx", "args": ["tsx", "/path/ada-agent-wallet/src/mcp.ts"],
  "env": { "SIGNERD_TOKEN": "<same token>", "AGENT_ID": "default" } } } }

Human approval: npm run walletctl -- pending → npm run walletctl -- approve <id>.

A queued payment holds the agent's /sign request open while the human decides, and that request is the only place the signed transaction can go. Node's fetch stops waiting for a response after five minutes; when the caller's connection drops, signerd withdraws the request from the queue, gives the budget back and logs pending_abandoned, so an approval that comes after that signs nothing rather than recording a spend for a transaction nobody will broadcast. Approve within five minutes, or expect the agent to have to ask again.

Dev stack (a whole 402 round-trip, locally)

dev/ runs the seller side so the loop can be closed without an external endpoint. Three shells:

npm run dev:facilitator   # 127.0.0.1:7403  verifies + broadcasts. No key, no funds: the buyer's
                          #                 transaction is already signed and pays its own fee.
npm run dev:resource      # 127.0.0.1:7401  the paid endpoint, settles via the facilitator
npm run dev:mcpresource   # 127.0.0.1:7404  the same three prices as paid MCP tools, through
                          #                 @x402/mcp's own createPaymentWrapper
npm run signerd           # 127.0.0.1:7402  the key + policy

Then drive it with a real MCP client — dev/roundtrip.ts spawns src/mcp.ts over stdio and calls x402_fetch, so the path is exactly the agent's:

npm run roundtrip           # GET /quote    1.5 tADA, under approvalAbove -> signs unattended
npm run roundtrip approve   # GET /report   4 tADA, queues -> npm run walletctl -- approve <id>
npm run roundtrip deny      # GET /premium  6 tADA, over perTxMax -> denied, nothing signed
npm run roundtrip auto mcp  # the same three modes, bought as MCP tools through x402_mcp_call
npm run balance             # BUYER_ADDRESS / SELLER_ADDRESS balances, to see the faucet land
npm run concurrency         # regression check for the spend-cap race (spends nothing)
npm run walletctl -- preflight   # deployment checks; see "Before mainnet"
npm run integrity                # proves no single deletion resets the spend cap
npm run approvals                # every way out of the approval queue gives the budget back
npm run assets                   # per-asset caps and windows, and the rate they share
npm run identity                 # whether an agent can spend a budget that is not its own
npm run queue                    # every exit from the approval queue that does not sign — no chain,
                                 # no wallet, so this one runs wherever the unit tests do
npm run posix                    # mode bits and signals; Linux only, since Windows can check neither
npm run delivery                 # a caller that leaves while a signature is in flight
npm run context                  # two tool calls at once keep their own reasons in the audit
npm run tidy                     # preprod: `walletctl tidy` on a wallet whose ADA is inside token UTxOs,
                                 # read back from the provider; spends one fee, stops on a tidy wallet
npm run keystore -- create ...   # encrypt the mnemonic at rest

npm run concurrency starts a throwaway signerd with a cap that fits one payment, fires several requests at once, and fails unless exactly one is signed. It needs a funded wallet because signing reads its UTXOs, but nothing it signs is ever handed to a facilitator, so no funds move.

Routes pin confirmationPolicy: { l1Confirmations: 0 }. Depth above canonical inclusion needs an evidence hook that only the Blockfrost provider supplies, so a Koios facilitator advertises l1Confirmations 0..0 and the default of 1 would make the 402 unserviceable. Zero still means the transaction is on chain — submitTransaction awaits confirmation — just without extra depth. Set BLOCKFROST_PROJECT_ID (or L1_CONFIRMATIONS) to ask for more.

The trap that goes with it: without an evidence hook the settle verdict is whether submitTransaction's awaitTx returned in time, and the SDK's provider timeout defaults to 10s — under preprod's ~20s block. A default-configured Koios facilitator therefore reports mempool on payments that confirm seconds later, and the buyer gets a 402 for a transaction that settled: funds gone, no goods. dev/facilitator.ts gives awaitTx 100s and dev/resource.ts gives the facilitator client 115s so the wait is not cut off one level up. Anything talking to mainnet needs the same budget chain, or Blockfrost.

batch-settlement (preprod)

An exact payment on Cardano is a transaction whose output to the seller must hold about 0.97 ADA ($0.23), plus a fee. Most of what x402 sells costs less than that. x402's batch-settlement scheme is the answer to small prices: the buyer locks funds in a payment channel once, pays each request with a signed cumulative voucher that stays off chain, and the seller redeems many at a time. This wallet pays it over Subbit channels, with the binding in subbit-x402; the design is in DESIGN-batch-settlement.md.

A voucher is money — the seller can redeem up to the highest one signed, and signing one costs nothing — so the vouchers are signed where the policy is: signerd runs subbit-x402's client, with the wallet and the channels' IOU keys, and the agent's process gets batchProxy.ts, a scheme with no keys that forwards the 402 to signerd and the payload back. x402_fetch prefers batch-settlement when a seller offers it and the agent's policy allows it.

"allowedSchemes": ["exact", "batch-settlement"],
"allowedProviderKeys": ["<the seller's receiverAuthorizer>"],
"channelDepositMax": { "lovelace": "5000000" },
"channelLockedMax": { "lovelace": "10000000" },
"maxWithdrawDelay": 86400,
"maxVouchersPerHour": 600

• A voucher spends what it adds to the most signerd has signed on that channel, and that increment goes through the same rules as an exact payment: payee, resource, perTxMax, dailyMax, approvalAbove. A retry, or the re-sign after a corrective 402, adds nothing and spends nothing. That record is signerd's own (CHANNELS_DIR/index.json): what sellers answer moves the channel's count, never what the policy counts.

• A deposit is locked, not spent: what the vouchers do not give the seller comes back. It has its own limits — channelDepositMax per opening or top-up, channelLockedMax across the agent's open channels, read from the chain — and does not touch dailyMax. A token channel's ADA reserve counts as locked lovelace, so token channels need a lovelace entry too.

• The payee is a key. A channel names the seller's receiverAuthorizer, which redeems, and the validator does not restrict where a redemption pays — so allowedPayees alone binds nothing here, and allowedProviderKeys must list the key.

• The close period is the seller's, up to 30 days, and leaving without the seller keeps the money that long; a channel asking for more than maxWithdrawDelay is not opened.

• Every channel transaction is read back before it leaves, as exact ones are: the channel step it claims to be, every other output to this wallet, a refund paying the seller no more than was signed and not yet redeemed, a fee under 2 ADA and collateral under 5 ADA.

The operator's side: walletctl channels, walletctl refund <channelId> <url> (the seller co-signs; signerd builds and signs it but talks to no seller, walletctl carries the messages; a refund pays the seller what it is still owed in an output of its own, so when that is below an output's minimum, about 1 ADA, the seller has to claim first and the refund then owes it nothing), close, end and elapse to leave without the seller, recover <agentId> to find an agent's channels on chain again after losing the records, and tidy (below). An exit waits for its block inside the wallet lock, so payments pause while one lands.

Every channel transaction but the opening puts up collateral from an ADA-only UTxO and keeps about 1 ADA of it back as change. So the wallet needs one ADA-only UTxO of at least about 2 ADA, and ADA sitting in a UTxO with tokens does not count. A sponsored channel is the exception (below).

exact payments undo that. Each one merges every token and the leftover ADA into a single change output, so after a few token payments all of the wallet's ADA can be inside token-bearing UTxOs, and a channel step fails insufficient_funds although the wallet holds plenty. walletctl tidy [--dry-run] [--collateral <ada>] puts it right: it spends every UTxO into one output with every token at its min-ADA, one ADA-only output of the collateral size (5 ADA unless --collateral says between 2 and 5), and the rest as ADA-only change. It does nothing when the wallet is already in that shape, that is when at most one UTxO holds tokens, it holds no more than its min-ADA and 1 ADA, and an ADA-only UTxO holds the collateral. --dry-run reads the wallet and says what it would do, and builds nothing. It refuses, as utxo_busy, while any of the wallet's UTxOs is committed to a payment or a channel step that has not settled, and while an output of the wallet's own transaction is not listed yet; it refuses more than 60 UTxOs, and a wallet that lacks the ADA for the layout. The transaction is read back before it is submitted, as every other is: its inputs are the wallet's UTxOs and no others, every output goes to the wallet, every token comes out as it went in, and the fee is under 1 ADA. The fee is the wallet's, and no agent's budget is charged for it. Like the channel endpoints it is the operator's, and preprod's.

signerd also does it by itself. When a channel opening, a top-up or the operator's refund fails short of ADA-only funds (the client's no UTxO to open, would leave no ADA-only UTxOs, a failed coin selection), signerd reads the wallet, and if a tidy would leave more ADA in ADA-only UTxOs than there is now, with its fee counted at 1 ADA, it starts one in the background and answers 409 wallet_tidying: retryable, "the wallet is rearranging its funds; try again in about a minute". That replaces insufficient_funds, which says the wallet lacks the funds and not to ask again. The agent is not held while the tidy confirms. The provider lists its outputs 20 to 60 seconds after the block, and a step that comes up short until then gets the same answer. The agent's tools pass it on as denied: true, rule: "wallet_tidying", retryable: true, retryAfterSeconds: 60. The audit has auto_tidy, naming the agent, the step and the shortage, and the tidy's tidied record says auto: true. It costs one tidy fee, about 0.2 to 0.3 ADA, paid by the wallet; no agent's budget is charged. There is at most one automatic tidy per AUTO_TIDY_MIN_INTERVAL_SECONDS (600; at least 60), whether or not the last one went through. A shortage inside that time, or one a tidy would not fix, is insufficient_funds as before, and its audit record says why no tidy was tried: the wallet is already tidy, lacks the ADA for the layout, holds its ADA in ADA-only UTxOs that are merely small, or is short of the token itself. An exact payment never starts a tidy. AUTO_TIDY=0 turns it off, and then only walletctl tidy does it.

Sponsored channels (subbit-x402 0.2.1). A seller may pay for a token channel. Its 402 then carries a fee-sponsor offer, one of the seller's ADA-only UTxOs. The channel client opens, tops up and refunds on that offer, so a wallet that holds only a stablecoin can pay (subbit-x402's SPONSORSHIP.md). The seller's ADA pays the fees, the channel's reserve and the collateral. The wallet's own ADA only passes through. signerd checks a sponsored transaction as it checks the others, and more:

• signerd reads the offer from the chain itself. A step whose offer is not, on chain, an ADA-only UTxO at the offer's address with the offer's lovelace, and not this wallet's, is refused (sponsor_offer).

• What the channel keeps, what the seller gets and the fee must all come out of the offer and the channel. So this wallet's ADA comes back to it in full, and the offer is the only collateral.

• The reserve is the seller's. The policy does not count it, so a sponsored token channel needs no lovelace entry in channelDepositMax or channelLockedMax, and the refund pays the reserve back to the seller. signerd records the channel as reserveFrom: "seller", and pays a reserve to the seller only on a channel recorded that way. recover finds it out again from the chain (subbit-x402 0.2.2): the client walks a token channel back to its opening, and one whose opening took none of the wallet's ADA was opened on an offer.

• Leaving without the seller (close, end, elapse) still needs ADA of the wallet's own.

A walkthrough, from the seller to the refund, is in docs/usdm-only-agent.md (a draft).

A top-up is sized for BATCH_DEPOSIT_REQUESTS requests at the price that ran short. When the wallet cannot fund that much, it tops up what it can, keeping back the fee and such a UTxO for the refund. Failing that, it tops up at least what this request is short of. A top-up that would leave nothing to put up as the refund's collateral is refused as insufficient_funds, or as wallet_tidying when signerd tidies the wallet in answer. Right after a channel transaction of its own, the client waits, for up to a minute, for Blockfrost to list that transaction's change before it builds again.

Limits: preprod only, and Subbit's validator is alpha software. The channel client reads the chain as the exact signer does: through Blockfrost with BLOCKFROST_PROJECT_ID, and through Koios, which needs no key, without it. Koios' preprod index has trailed the chain by over two minutes, so there an opening or top-up can take a minute or more to confirm.

x402_mcp_call pays paid MCP tools the same way, through the same proxy and on the same channels. A seller's HTTP routes and MCP tools share one channel when they name the same provider.

A paid answer lost in transit is given again to its retry, over MCP as over HTTP, when the seller runs subbit-x402 0.1.2 or later. The retry carries the same voucher, signerd re-signs it without spending anything (voucher_resigned), and the seller hands back the answer it kept. Over MCP it keeps a tool's result only when @x402/mcp can give it back unchanged: one text block, or structured content with its JSON as that block. A retry after any other result is charged again, one voucher's worth.

npm run batchseller is the preprod seller, with its MCP tools on :7414. npm run batch, batchexit, batchend, mcpbatch, batchsponsored and autotidy are the round trips against it; the results are under "Verified".

Verified

• npm test: 207 unit tests over the policy engine, the startup replay and the release of expired spends, the locks, the keystore, the network table, the signed-transaction and channel-transaction checks (sponsored steps included), the channel index, the batch-settlement proxy, the settlement receipt, the build retry, the known assets, the tidy plan and when to tidy by itself. None needs a chain. npm run typecheck covers dev/ and test/ too, which tsx runs without checking.

• CI (.github/workflows/ci.yml) runs both on Linux, macOS and Windows, each on Node 22 and 24, and npm run posix (real mode bits, SIGTERM draining the approval queue) on Linux and macOS. All six passed on 2026-09-29. That is the only macOS this has run on: nothing here has been driven on a Mac by hand, and no preprod round trip has run there.

• npm run batch on preprod (2026-09-25), a real MCP client paying dev/batchseller.ts through x402_fetch, 0.1 tADA a request: the first purchase opened a channel in 38 s (deposit 2.732620 tADA, reserve included), the next nine were vouchers at 33–39 ms each; a response the seller dropped was retried with the same voucher and spent nothing twice (voucher_resigned); a 0.2 tADA purchase over approvalAbove queued, was approved with the operator's token, and paid; the channel was topped up twice as it ran short; the 25th voucher was refused by dailyMax; a seller naming a provider key outside allowedProviderKeys was refused and got no channel; and walletctl refund closed the channel with the seller co-signing. 24 vouchers for 2.500000 tADA in the audit log, in the ledger and in signerd's channel index alike; on chain the seller received exactly 2.500000 and the wallet lost exactly that plus the four transactions' fees, 0.923814 (opening 1ea7adcb… 0.178173, top-ups 4b373326… and 38170b84… 0.253535 and 0.253533, refund 13808a96… 0.238573).

• npm run mcpbatch on preprod (2026-09-26, subbit-x402 0.1.3): paid MCP tools, bought through x402_mcp_call, at prices no Cardano output could carry.

  • The calls. One channel paid 107 calls. Over MCP there were 100 quote at 0.01 tADA, 5 report at 0.05 tADA and one digest at 0.02 tADA; over HTTP, one /data at 0.1 tADA from the same seller.

  • Speed. The first call opened the channel in 23.5 s. The other calls were vouchers at 37–65 ms each, median 46 ms, except the report that topped the channel up (53 s).

  • A top-up the wallet could not fund in full. With the opening in, the wallet held 5.758573 tADA in ADA-only UTxOs. That is more than the 5 tADA the top-up asked for, but not enough for its fee and a change output as well. The index did not list the opening's change yet, so the client waited for it. It then topped up 3.258573 tADA, all it could, keeping back an ADA-only UTxO of 2.244289 for the refund's collateral.

  • A lost answer. The seller charged the digest and dropped its answer. The retry carried the same voucher, which signerd re-signed without spending anything (voucher_resigned), and got the lost call's answer back: the tool did not run again.

  • Settlement. The seller claimed all 1.370000 tADA in one transaction into its own wallet. It had to claim before the refund, since a refund cannot pay an amount below an output's minimum. walletctl refund then returned the rest, 4.388648 tADA, owing it nothing.

  • Reconciliation. 107 vouchers for 1.370000 tADA in the audit log, the ledger and signerd's channel index alike. On chain, the seller gained exactly 1.370000 less its claim's fee, and the wallet lost exactly that plus its own fees. That is four transactions and 0.922743 tADA, or 0.008623 per call:

    • opening 1d0cb8cc… 0.176589, top-up d417da2a… 0.255711, refund a1010bac… 0.232545;

    • claim b834de67…, 0.257898.

• npm run mcpbatch again, on Koios alone (2026-09-26): signerd and the seller had no Blockfrost key. Only the demo's own checks used one, so they do not rest on what they check.

  • Every step passed, on the same 107 calls as the run above: the opening, the fallback top-up (0.674183 tADA, with the validator evaluated through Koios' Ogmios endpoint), the lost answer's retry, the seller's claim, and the refund.

  • Reconciled to the lovelace. Fees were 0.915222 tADA over four transactions: opening 8c8e4807…, top-up f6302be7…, claim 40248f9e…, refund afddfdf7….

  • Slower. The opening took 52.6 s, against 17–33 s on Blockfrost. Koios' preprod index has trailed the chain by over two minutes.

  • A fault, found by an earlier attempt, and fixed in subbit-x402. That attempt found that the seller's facilitator checked a settlement_pending retry again, and refused it when its transaction had landed in between.

• npm run contention on preprod (2026-09-26): an exact payment and a channel transaction never go out spending the same UTxO while the first is unsettled.

  • exact first. A 1.5 tADA purchase was built on the wallet's first-listed UTxO, its largest ADA-only one. A channel asked to open meanwhile could not use that UTxO, and the wallet could not fund the opening without it, so it was refused as insufficient_funds. It opened from other UTxOs once the purchase was on chain.

  • Channel first. While a top-up was in flight, a purchase was built on the wallet's token UTxO, which holds only its min-UTxO of ADA, so the SDK added the largest ADA-only UTxO: the top-up's. signerd refused it as utxo_busy and audited input_in_flight, naming that input. Asked again once the top-up was on chain, it went through.

  • On chain. All four transactions handed out landed, and no two share an input: purchases 708aa478… and 4b6c31bd…, opening 60f4363b…, top-up a408c7a2…. Buyer and seller reconciled to the lovelace across the run's eight transactions. Those count the layout before it, the seller's claim, the refund, and 3 tADA sent to the buyer for the refund's collateral.

  • What it cost the wallet's ADA. An exact payment's change keeps the wallet's tokens and its leftover ADA in one output. ADA held with tokens counts neither for channels nor as collateral, so after the two purchases the wallet held no ADA-only UTxO, and its refund had to wait for more.

• npm run batchsponsored on preprod (2026-09-28, subbit-x402 0.2.1): a token channel the seller paid for, through signerd, from a wallet holding only tUSDM and the 1.176630 tADA that came with it. The seller ran dev/batchseller.ts with BATCH_SELLER_SPONSOR_ACCOUNT=9. The run made 25 purchases at 0.001 tUSDM, with BATCH_DEPOSIT_REQUESTS=10 and a policy with no lovelace entry at all.

  • The opening 8c4f3373… (fee 0.190097) and the top-ups 440e17e5… and 951dc64d… (0.266094 each) each used another of the seller's offers, named in the audit as sponsoredBy. signerd recorded the channel as reserveFrom: "seller".

  • The seller claimed (4dc5c0eb…, 0.268721). Then walletctl refund (6053f5a2…, 0.244491) put up the seller's offer as its collateral, and did not spend it.

  • Reconciled on chain across the five: the wallet's ADA did not move, to the lovelace, and its tUSDM went down exactly the 0.025 the vouchers signed. The seller, across payTo and its sponsor key, got +0.025 tUSDM and paid −1.235497 tADA, the five fees exactly, so its reserve came back.

  • The first attempt stopped at the second top-up. Two seconds after the first top-up's block, the SDK's script evaluation through Blockfrost failed ("Blockfrost evaluateTx failed"), and the agent got batch_failed, with nothing signed or sent. Resumed 22 minutes later on the same channel, that top-up passed. Why it failed is not established.

• npm run batchsponsored again (2026-09-28, 0.2.6 on subbit-x402 0.2.2), in two phases with the wallet's records lost in between (BATCHSPONSORED_PHASE=pay, then recover).

  • On Blockfrost, signerd paid 25 purchases: the opening 1342b697…, the top-ups eb562bb1… and 1341473d… (in blocks 5228801 and 5228804), and then the seller claimed (f3d51a24…).

  • signerd was stopped, its channels directory deleted, and started again with no Blockfrost key, so it read the chain through Koios. walletctl recover found the channel with its reserve the seller's, and walletctl refund was sponsored (470822ba…).

  • The wallet's ADA did not move, to the lovelace, and its tUSDM went down the 0.025 the vouchers signed. The seller paid the five fees, 1.235908 tADA.

• npm run expiry on preprod (2026-09-29, Blockfrost, the release margin at its 60 s floor). Payment A (34c64379…, 1.5 tADA, 60 s TTL) was signed and never submitted; payment B (f1bfe56b…, 1.6 tADA, 180 s TTL) was submitted straight to the provider and landed. A's budget came back 183 s into the run, once the tip was past its TTL plus the margin, with one spend_released naming its transaction, agent, asset, amount and TTL slot. B stayed counted through its own TTL and margin. After a restart the ledger still held B and not A, and the checkpoint kept B's transaction and TTL slot. The first attempt had not got that far: the public test wallet's only UTxO held its tokens and 4.7 tADA, too little to pay 1.5 tADA and still leave its tokens their min-ADA in the change, which is what the next entry is for.

  • Again through Koios alone (no Blockfrost key), on @evolution-sdk/evolution 0.5.15, whose Koios decoding was rewritten: A (2518cb91…) came back 191 s into the run on Koios's /tx_status, B (93255b7e…, landed 59 s after its submit) stayed counted past its TTL and margin and across the restart.

• npm run tidy on preprod (2026-09-29). The wallet as the provider listed it: 3 UTxOs, one of them holding every token and 15.82 of its 27.02 tADA, since B's change in the entry above had folded them together. tidy (79b7b679…, fee 0.200921) left the tokens in one UTxO at their min-ADA (3.59023), one ADA-only UTxO of exactly 5 tADA for collateral, and the rest ADA-only; every token came through in the same amount, and the wallet's ADA went down by the fee and nothing else. A second tidy straight after was refused utxo_busy, a dry run once the provider listed the outputs said the wallet was already tidy, and an agent's token was refused operator_only.

• npm run autotidy on preprod (2026-09-29, Blockfrost), through a real MCP client. The script put the wallet out of order itself (e84e5c63…): every token and 19.25 of its 21.16 tADA in one UTxO, 1.90 tADA ADA-only. The agent's purchase could not fund an opening; signerd answered wallet_tidying within 2 s, retryable after 60 s, and started one tidy in the background (123d865d…, auto: true); a second ask straight after was told to wait and started none. Once the tidy was listed (21 s), the same purchase opened the channel (1ef92388…) and paid by voucher. Put out of order again two minutes later, the top-up's shortage was insufficient_funds, with "tidied 2 minutes ago; at most one automatic tidy every 10 minutes" in its audit record; a tidy by hand (b9ad35ba…) let the same purchase top the channel up (336d32f7…). After the refund (ecf439de…) the seller had +1.3 tADA, what the vouchers signed, and the wallet −2.927010: that and the seven transactions' fees, the automatic tidy's 0.199337 among them, to the lovelace.

• npm run batch again on @evolution-sdk/evolution 0.5.15 with subbit-x402 0.2.3 (2026-09-29, Blockfrost): 22 purchases on one channel (vouchers 27–38 ms after the opening's first), the lost response and its re-sign, the approval, the dailyMax refusal with a top-up on the way, the refused provider key, and walletctl refund. Four transactions (5119e404…, 8c7c1f74…, 5b65a64b…, 4b9cb79f…); the seller +2.5 tADA, what the vouchers signed, and the wallet −3.667211, that and the fees (1.167211), to the lovelace.

• npm run batchexit on preprod (2026-09-25), the way out without the seller: three purchases, walletctl close (95f5f833…), then signerd restarted with its channel directory deleted; walletctl recover found the closed channel on chain with its IOU key derived again, and walletctl elapse (262b5b15…) took everything back. The seller never settled, so it received nothing, and the wallet was down exactly the three fees, 0.751551 tADA; the three vouchers stay spent in the ledger, as any signed payment does.

• the batch-settlement runs again on @evolution-sdk/evolution 0.5.14 (2026-09-25), with subbit-x402 0.1.1: npm run batch passed with the same reconciliation to the lovelace, and npm run batchend too. Each first found a race that 0.5.13's runs had missed by timing: a retry 16 s after a top-up's block built a second top-up of the output the first had spent (the client now waits for the index, and the retry in the passing run came 13 s after its block); and an elapse straight after a close was let through by a check that read the chain separately from the elapse itself, which then waited out elapse_at inside the wallet lock (the client now decides on the one read, and refuses). On Koios alone, roundtrip deny and roundtrip auto passed (3bb30455…, 31.9 s).

• npm run batchend on preprod (2026-09-25), a token channel and the seller's side of an exit: five purchases priced at 0.001 tUSDM opened a tUSDM channel through signerd (6829d63d…, 45 s, then 36–53 ms a voucher); walletctl close (b7dbfbba…); an elapse straight after was refused as not_yet rather than waited out inside the wallet lock; the seller's watcher settled the latest voucher 20 s after it saw the close (4c76972b…); walletctl end (71d076bc…) took the rest back. The seller received exactly 0.005 tUSDM and paid only its settle fee (0.275504 tADA); the wallet gave exactly 0.005 tUSDM and its ADA was down only its three fees, 0.687401 — the channel's ADA reserve came back.

• the modules that say "no chain, no keys, no I/O" are checked to import nothing that would make that false, and to still say it — the first run of that check found one that had stopped

• signerd asks the socket what address it bound and refuses anything but the loopback, so the one line that decides whether the wallet is on the network is not taken on trust

• every signature is read back before it is handed over: an output pays the authorised payee at least the authorised amount, the nonce is spent, and nothing else is paid at all

• npm run integrity: no single deletion resets the spend cap, and restarting does not re-count what the checkpoint already holds

• npm run concurrency: the cap holds under simultaneous requests, and two agents sharing one wallet contend for its UTXO without either being handed a transaction that cannot settle

• npm run approvals: approved, denied and timed out all give the held budget back, two queued payments cannot promise the same budget twice, and a limit tightened while one waits is applied to it rather than bypassed by the approval

• npm run assets: caps and 24h windows are per asset, the hourly rate is shared across them, and an asset the wallet does not hold is refused as insufficient_funds rather than as a fault. Not covered: an actual native-asset settlement, which needs a wallet holding one.

• npm run identity: with AGENT_TOKENS_FILE, an agent cannot sign as another or read another's budget, and the operator token cannot sign at all. Without it, the same check demonstrates that it can.

• npm run queue: every exit from the approval queue that does not sign — denied, timed out, the caller leaving, the policy tightening underneath it, and a SIGKILL'd run's orphan closed at the next start — each giving the held budget back. No chain and no wallet, so it runs in CI

• npm run posix: on Linux, where the mode-bit checks and the shutdown signal can actually run. SIGTERM drains the queue and answers whoever was waiting; a group-writable policy warns on preprod and refuses to start on mainnet; malformed, oversize and wrong-chain requests are 4xx without writing to the log; a torn append is repaired and an edited record refuses to start

• npm run delivery: a caller that leaves while a payment ahead of it is signing takes its request with it, and a signature that lands after its one recipient has gone is recorded as signed_undelivered rather than counted silently

• npm run context: two x402_fetch calls in flight at once each keep their own reason all the way into the audit, which is what the AsyncLocalStorage in mcp.ts exists for

• mcp: tool listing and wallet_status through a real MCP client

• npm run mcptools: the MCP-side tools register, and the payment client src/mcp.ts builds is accepted by @x402/mcp's wrapMCPClientWithPayment. Types agreeing is not the hand-off working, so it is run rather than assumed.

• npm run roundtrip deny mcp: a paid MCP tool over perTxMax, bought through x402_mcp_call from a seller built on @x402/mcp's own createPaymentWrapper, comes back per_tx_max in 0.1s with nothing signed.

• both tools used to report a payment that did not settle as paid. x402_fetch read "paid" off whether a PAYMENT-RESPONSE header existed, and core sends one with success: false on every settle failure; x402_mcp_call read it off paymentMade, which means sent. Both now read the settlement itself (src/receipt.ts, tested against core's real header encoding), carry the transaction as a receipt, and say unsettled when signerd signed something that did not settle — checked on preprod against a real facilitator rejection on both transports.

• a paid MCP tool call, settled on preprod, 2026-09-16 — x402_mcp_call bought quote from dev/mcpresource.ts and came back paid: true with its transaction in 33s. Facilitator verify isValid:true, then settle success:true status:"confirmed" confirmations:1, transaction 15f100abe211a43f711371c4854cc43aed18978d0ffed8630c6c17daeae9642b in block 5183279. Not taken on the facilitator's word: read back from Blockfrost, it pays the seller exactly 1.5 tADA, returns the change to the buyer, pays nobody else, and spends only the buyer's inputs. signed in audit.jsonl with the reason tagged [mcp tool quote], and the chain replays clean through replayAudit. The seller is @x402/mcp's own createPaymentWrapper, so this is the wallet against the official stack on both sides of the call.

• the approval queue over MCP, settled on preprod, 2026-09-21 — x402_mcp_call report (4 tADA, over approvalAbove) parked as pending carrying the agent's reason tagged [mcp tool report], walletctl approve released it, and the call came back paid: true in 25.2s. pending → signed → approved in audit.jsonl, transaction adb52eb1cdb6878fc72943894ee95477be992ccad49cd8b418bef0b4eb606285 in block 5202188, read back from Blockfrost: exactly 4 tADA to the seller and nothing to anyone else. The nonce it spent was an output of 01b6275f8f…, a Plutus transaction — the case Koios could not look up before evolution-sdk#544, so this one ran on Blockfrost.

• the whole matrix on @x402/* 2.27.0, preprod, 2026-09-23 — 2.27.0 shipped on 2026-09-22 and a ^2.26.0 range floats onto it, so what someone installs today is not the build the round-trips had been run against. All six combinations of {deny, auto, approve} x {HTTP, MCP} pass on it. deny denies on per_tx_max and broadcasts nothing on either transport; the payments read back from Blockfrost as exactly 1.5, 1.5, 4 and 4 tADA to the seller, no output to a third address and every input the buyer's — b99226d5… (block 5209209), 38046624… (5209211), ff9705f4… (5209214), and for approve over MCP a92857ee… (5209223). That last one is a re-run: on the first pass the harness approved within a second of the entry appearing, so roundtrip.ts's own once-a-second watch on /pending never saw the queue non-empty and failed the run — the payment itself had settled correctly as 5a59f437… (5209217), and the audit recorded pending → signed → approved for it. Both harnesses polling on the same interval is the whole of it. replayAudit clean afterwards, and dailyRemaining and paymentsLastHour match what was spent.

• off vendor/ and onto the published packages, 2026-09-21 — @x402/cardano reached npm as 2.26.0 on 2026-09-18, so the vendored tarballs, their checksums and the second copy of @x402/core are gone, and with them the casts that let one copy's client reach the other's API. Re-run on preprod against the published build: deny and auto on both transports, auto settling as 3eb923952376ce5299f8cba6a70e3979fca92d3bd6ec82a738c5f4204d8f5344 over MCP and 1061f314b2ea23e906e3293a9f0bade743c2dd5bedd43b28dd659072e96d2319 over HTTP, each read back from Blockfrost as exactly 1.5 tADA to the seller and nothing to anyone else.

• the same run bought /quote over HTTP after the receipt change: status 200, paid: true, transaction ba269ae6f25b2ba505d3da251bbed9904f10466db05ed87c163edec66145eb3e in block 5183281, checked the same way. The fix that stopped failures reading as paid did not stop successes.

• one MCP payment before that settled on Koios at confirmations:0 (37120eda…, block 5183270), between runs where Koios verify failed on the same wallet. Koios is intermittent for this, not unusable; Blockfrost is what gets past it every time, and the only way to ask for depth.

• deny path, end to end: MCP x402_fetch → 402 → gated signer → signerd → per_tx_max → structured verdict back at the tool, denied in audit.jsonl

• a whole 402 round-trip on preprod, 2026-09-15 — x402_fetch GET /quote returned status 200, paid true with the real body in 72s. Facilitator verify isValid:true, then settle success:true status:"confirmed", transaction 6d94fdc0617a8e58ca23402826f36767bab9a00a77dfe02de851d5828428e7e0 on preprod; signed in audit.jsonl with the agent's stated reason and the UTXO it spent as nonce; 1.5 tADA landed at the seller address. The first real signature and the facilitator settlement are no longer unrun.

• the same round-trip with a human in it, 2026-09-16 — x402_fetch GET /report at 4 tADA is over approvalAbove, so it parked in the queue and held the agent's request open while walletctl approve 4df1a492 was run from another shell; status 200, paid true came back 179s later, the audit reading pending → signed → approved. Over the same session the buyer went from 169.638625 to 163.780519 tADA and the seller from nothing to 5.5 in two UTXOs, which is the 1.5 and the 4 arriving. On Blockfrost: this cannot be done on Koios, see below.

• approve → sign, on chain — a 4 tADA route parked in the queue as pending with the agent's reason and the threshold that caught it, walletctl approve released it, and the same call returned 200 paid true in 48.7s. Transaction 020af86ddcd581e3379305d832b5da957b877fb0edca97dab1ab3457ce93a72b; pending → signed → approved all in audit.jsonl.

• ledger accounting against the real chain: three payments (1.5 + 1.5 + 4 tADA) left dailyRemaining 13000000 of a 20 tADA cap and paymentsLastHour 3, and 7 tADA arrived at the seller address in three UTXOs.

• the spend cap holds under concurrency: four simultaneous requests against a cap that fits one produce one signed and three daily_max denials. Before the agent lock the same probe signed every one of them, on one shared nonce.

• on subbit-x402@0.3.0, which opens channels at Subbit's fixed validator (6d877463…), batch and batchexit passed again (2026-10-07): both channels sat at that validator, and recover found channels at the build before it as well. Channels opened at that earlier build keep working, and a record that names no validator is read as one of them.

• what the registry serves is what was built: ada-agent-wallet@0.2.9 on npm is byte for byte the tarball checked before publishing (24 files, shasum 478a9fca…, the one npm publish printed), and says Node 22 or newer. Its subbit-x402@0.3.0 is byte for byte the tarball the wallet was tested against (shasum 3388ca55…). Both pin the SDK at 0.5.15, so an install holds one copy of it, and neither needs typescript or tsx, because both packages ship prebuilt.

  • ada-walletctl prints its usage, tidy included.

  • ada-wallet-mcp gets as far as its own "signerd is not answering" check.

  • ada-signerd, from the same bytes installed before publishing, comes up on preprod on Koios with batch-settlement available and the release loop on.

  Earlier releases were checked the same way: 0.2.7 (94736c62…), 0.2.6 (44bfa586…), 0.2.5 (43b7f48d…), 0.2.4 (87f7ffb1…), 0.2.3 (dde3cc15…), 0.2.2 (b27996d7…), 0.2.1 (e11f0510…), 0.2.0 (6edfe7ba…) and 0.1.0 (17 files, a6c269ca…).

Before mainnet

npm run walletctl -- preflight     # fails on anything that must be fixed, warns on every decision

ALLOW_UNVERIFIED_AUDIT=1 is the way past a refused startup when the audit log was rotated on purpose; it waives the check, not the ledger. LEDGER_FILE and AUDIT_FILE say where both live.

preflight refuses to pass until the policy declares "network": "cardano:mainnet", and signerd refuses to start on mainnet without it: caps here are bare integers with no unit, so a file tuned against 10,000 faucet tADA says exactly the same thing to a wallet holding real ADA. It also warns on each choice that is yours rather than a bug — a payee allowlist of ["*"], a missing resource allowlist, no approval threshold, masumi enabled, Koios as the provider.

On mainnet signerd additionally refuses to start when the policy, audit or ledger file is group- or world-writable, because "the agent cannot raise its own limits" stops being true the moment the agent's user can write any of them. On Windows the mode bits do not carry that meaning, so the check reports that it could not run rather than passing: verify the ACL yourself.

allowedResources bounds which URLs an agent may buy from. It is checked against a URL the agent process reports, because the reference @x402/cardano client does not pass the resource through to the signer — so it constrains an agent that is running this code and being steered, which is the prompt-injection case, and not one whose process has been replaced. allowedPayees is the control that binds the transaction itself; treat the resource list as the layer above it.

Which asset id

Caps in policy.json are keyed by "lovelace" or "<policyId>.<assetNameHex>", and the amounts are in the smallest unit: "1000000" of a 6-decimal token is one token, so "1f3aec8bfe7ea4fe14c5f121e2a92e301afe414147860d557cac7e34.5553444378": "5000000" caps USDCx at 5 per payment. The wallet pays only assets that are listed, so a lookalike token cannot be paid unless you list it. The way that happens is a wrong copy: token names are not unique, and an explorer search for "USDCx" returns five policies, only one of them the xReserve USDCx that IOG bridges.

The mainnet stablecoins this wallet knows (src/assets.ts), checked on 2026-09-29 against the chain (Koios), the Cardano token registry and one more source each (Moneta's policy-id page, the fingerprint in Circle's announcement, Indigo's contract repository, the Open DJED protocol datum; USDA has only CoinGecko besides the registry):

USDM is a CIP-68 token, so its name is the label prefix 0014df10 and USDM; DJED's on-chain name is DjedMicroUSD. Decimals are what the token registry says (for USDM and the preprod test token also the CIP-68 datum); nothing on chain enforces them for a plain native asset, so they are the issuer's word. On preprod the wallet knows tUSDM, e675b46e4d2242c991a8932a99db3044e80515ae14b4c4ccf6b3f4c9.0014df10745553444d, also 6 decimals.

Copycats seen on mainnet on 2026-09-29, searching Koios by exact asset name. None is a token you want; all of them are worth nothing next to the real ones:

• USDCx, four: 038f14bd637e6c7b4ecdb2bf5dde2ccfd69b415f10d01bb5bd0f31da, 325fb65426e2a2af4749d9347e28d4c109d0895340dec5547036ab05, 4e74a46ecac6d7cde02e07e4e829659dcec39bc4704b0a40506f2c70, 82db3e78cea2810a39a97a65820d19621848d132db566ae88105813e. They are tiny next to the real one: about 2,010 USDCx between them at 6 decimals, in at most five addresses each, against 46.25 million across 1,381 addresses.

• USDM, twenty-two: fifteen with the same CIP-68 name as Moneta's (3aba99e1… even copied the reference token, and did it before Moneta minted its own), five plain USDM, two lowercase usdm. Most hold a single unit. Moneta's has 6,218 holding addresses.

• USDA, four: 0b17e18e…, 203b808c…, 36a2d845…, 8bb07d0a…. 36a2d845… also mints a fake USDM.

• iUSD, one: 648823ffdad1610b4162f4dbc87bd47f6f9cf45d772ddef661eff198.

• DJED, one, burned to nothing: 4eea0f3c96825d83a42ecffd9f2b4fb6683977ffc557284644c4ee3c.

preflight reads every asset id in every agent's perTxMax. A listed one prints its ticker and decimals; one whose name matches a known ticker but whose id does not fails on mainnet (warns elsewhere) and names the real id; anything else warns that it is not a known stablecoin, so check the policy id and its decimals yourself.

The key

npm run keystore -- create --mnemonic-file ~/.ada-agent-wallet/mnemonic --out ~/.ada-agent-wallet/keystore.json

scrypt and AES-256-GCM, asked for the passphrase twice, proved to round-trip before anything is written. Point signerd at it with WALLET_KEYSTORE_FILE, then delete the plaintext mnemonic — once you are certain the passphrase is recoverable, because at that point the keystore is the wallet.

The passphrase comes from WALLET_PASSPHRASE_FILE, or a terminal prompt when there is one. Deliberately not an environment variable: the point of a keystore is that reading one thing is not enough, and an env var is readable by anything that can read the process. And if the passphrase file lives next to the keystore, preflight says so — encryption with the key taped to the box is worth about what it sounds like.

What this buys: reading a file is no longer enough. A stolen backup, a disk image, a stray copy in a repository, a directory whose permissions were wrong for a week — all of those now yield ciphertext. What it does not buy: anything at all against a compromised signerd, which holds the decrypted mnemonic in memory for as long as it runs. That is what a hot wallet is.

Which is why MAX_HOT_BALANCE_LOVELACE exists and why preflight fails on mainnet without it. The daily cap bounds an agent. Nothing bounds someone who has the key, except how much is in the wallet, so decide that number deliberately and alert on ada_wallet_balance_over_ceiling.

Who an agent is

By default there is one token, and agentId arrives in the request body. With a single agent that is fine. With several it means the split between them is a convention: any process holding that token can spend any agent's budget by naming it, which is the opposite of what a per-agent policy is for. Preflight says so when the policy has more than one agent.

AGENT_TOKENS_FILE is a JSON map of {"<token>": "<agentId>"}. With it, a token is an identity: /sign takes the agent from the token and refuses a body that names another, /status returns only that agent's budget, the approval queue and everything else is the operator's alone, and the operator token stops signing at all. Operating and paying become different authorities, which they were not.

Monitoring

GET /metrics is Prometheus exposition behind the same bearer token — it reports what this wallet has spent, which is not public. Counters restart with the process, as is conventional; the gauges carry the live state counters cannot.

Alert on: any increase in ada_wallet_audit_events_total{event="denied"}, {event="policy_error"} or {event="nonce_collision"}; ada_wallet_over_budget reaching 1; ada_wallet_pending_approvals staying above zero longer than a human should take; ada_wallet_policy_readable reaching 0. A denial is not by itself an incident — an agent hitting its cap is the system working — but a change in the rate of them is the first sign that something upstream is steering it somewhere new.

{event="signed_undelivered"} is the one that means the ledger and the world have come apart: a transaction was signed and its spend recorded, and the single request it could have been handed to had closed. Nothing will broadcast it, and the budget stays spent — a transaction is not unsigned by nobody having read it — until its TTL and the release margin have passed and the chain shows it was never included. It takes a caller leaving during the seconds a signature is in flight, so it should be rare; each one is a payment the agent will have to ask for again.

{event="spend_released"} counts budget given back for payments that never landed, and {event="provider_retry"} counts builds that had to be tried again. Neither is an incident on its own; a rate that keeps climbing is the provider, or a facilitator that is not settling what it is sent, and worth knowing about before the free tier's rate limit finds it for you.

{event="auto_tidy"} counts the tidies signerd started itself because a channel step ran short of ADA-only funds. Each costs a fee, and there is at most one per AUTO_TIDY_MIN_INTERVAL_SECONDS, so a count that keeps climbing means exact payments keep folding the wallet's ADA into its tokens about as fast as the tidies undo it. auto_tidy_failed and auto_tidy_skipped are the ones that did not go through.

What this still does not do

Naming these is the point; none is fixed by more policy code.

• There is no hardware-wallet or KMS path. The keystore means a file read is no longer enough, but signerd still decrypts the mnemonic into its own memory and keeps it there. A key that never leaves a device is a different architecture, not a setting — and the honest mitigation for this one is the balance ceiling: keep in the wallet only what you would accept losing outright.

• Nothing scrapes /metrics for you. The signals are exposed and the alerts worth writing are listed above, but wiring them to something that pages a human is deployment work, not code here.

• Deleting both ledger.json and audit.jsonl together still resets the cap. No single deletion does — see npm run integrity — but two coordinated ones against files the agent is not supposed to be able to write is the residual risk, and file permissions are what covers it.

• On mainnet you want more than zero confirmations, which needs Blockfrost: Koios exposes no transaction-evidence hook, so a facilitator on it can only settle at l1Confirmations: 0. As a buyer you do not choose this — the seller's 402 does — but it governs any facilitator you run.

Known behaviour worth expecting

• A signed payment counts against the budget when it is signed, and comes back only when the chain shows it never landed. signerd records the spend at signing and never hears whether the facilitator got the transaction on chain, so a transient submit failure costs budget without moving funds — observed once here: dailySpent of 16.5 tADA against 12.5 tADA actually delivered. What signerd can know is this: the exact signer always gives a transaction a TTL, and one the chain has passed without including it never will be. So once a minute signerd reads the chain's tip from its own provider, and for every payment whose TTL plus RELEASE_MARGIN_SECONDS (default 1800, so half an hour) is behind the tip, asks whether the transaction is in a block. A definite no takes the spend off the ledger: spend_released in the audit, counted in /metrics, and kept across a restart. Anything else leaves it counted — yes, an HTTP error, a timeout, a reply that is not what was asked for. The budget comes back on evidence signerd read itself and on nothing the agent or the seller says about the payment; the agent cannot talk its way to it, and a payment it submitted on its own shows up as in a block and stays spent. RELEASE_EXPIRED_SPENDS=0 turns it off. Three limits. It trusts the provider's "not found": a provider that answered a clean 404 for a transaction that did land would give back budget that was spent, and what bounds that is the balance ceiling, MAX_HOT_BALANCE_LOVELACE, not this. A payment signed before this existed carries no transaction hash in its record and is never given back. And a batch-settlement voucher's spend, or budget held by an approval still waiting, is not a signed transaction with a TTL, so neither is released. The tools say so when it happens: paid: false with an unsettled note, and the transaction if one was broadcast, since a settlement reported failed can still confirm.

• Before @evolution-sdk/evolution 0.5.14, a 402 round-trip could not complete on Koios at all. Fixed upstream in evolution-sdk#544 (reported from here as #540), released in 0.5.14 on 2026-09-24, which this package now pins; the exact round trip passed on Koios alone the next day. What it was: the facilitator's verify resolves each input the buyer's transaction spends, and @evolution-sdk's Koios provider failed that lookup for almost all of them. Over one wallet's 19 UTXOs, asked three ways: the Koios provider resolved 3, the Blockfrost provider resolved 19, and plain HTTP to the same Koios endpoint returned all 19. So the data is there and Koios is serving it; the provider cannot read it. The failures are deterministic, ~1.4s on an idle box, and grouped by the transaction that created the UTXO — not a timeout, not rate limiting, not native assets, not a UTXO that is missing or spent. All you are told is Koios getUtxosByOutRef failed, with the cause discarded. There is no steering around it either, because the SDK always takes utxos[0] as the payment nonce: if the wallet's first UTXO is one it cannot read, nothing that wallet does can pay. The cause was the provider decoding the creating transaction's whole /tx_info row, three fields of which Koios returns as null.

• Three batch-settlement answers mean "ask again", not "broken". channel_busy (409, retryable): the channel is between two states the chain has not finished showing — right after a top-up of this wallet's own, Blockfrost's index can still show the channel where the top-up spent it, and the client waits up to 30 s for it before saying so. wallet_tidying (409, retryable, 60 s): a channel step ran short of ADA-only funds and signerd is tidying the wallet, or has and the provider does not list the result yet (see the tidy paragraph under batch-settlement). not_yet (409): walletctl elapse before the channel's elapse_at, refused rather than waited out inside the wallet lock. Only insufficient_funds is an answer about the wallet.

• A wallet that cannot fund an exact payment is insufficient_funds, in three of the builder's wordings. Coin selection failed, Cannot create valid change, and Cannot balance transaction: Native assets present in leftover but insufficient lovelace, the last seen from a wallet whose one UTxO held many tokens and 4.7 tADA: it could pay, but not and still give the tokens back their min-ADA. That one was a 500 sign_failed until it was classed with the others. An exact payment does not start a tidy, whichever it is; only channel steps do.

• Koios can refuse a submit moments after confirming the transaction it chains from. A payment spending the change of a just-confirmed transaction was rejected with Koios submitTx failed, and the identical payment succeeded on retry: its query view had the new UTXO before its submit node had the block. Retry rather than treat it as fatal — and note this is why the in-flight UTXO hold is short, since an over-long one makes that retry impossible.

• A payment started moments after the previous one settled can fail at sign_failed: Blockfrost getUtxos failed. Seen once, about ten seconds after an MCP payment had settled: signerd's provider call for the wallet's UTxOs failed in under a second, while the identical run passed on its own a minute later, as did a direct query of the same endpoint. The cause was not captured — a free key's burst limit is the obvious suspect and not a proven one — so treat it as retryable, the way Koios submitTx failed above is. signerd now does that itself for the build: a provider read that failed, or the network under one (fetch failed, ECONNRESET, a timeout), is tried again after 1s and then 3s, each try logged as provider_retry, and only then reported as sign_failed. Nothing has been signed or handed out when a build throws, so a second try cannot commit anything twice. A submit failure is never retried this way — the facilitator does the submitting — and neither is insufficient_funds, which is an answer about the wallet.

• The in-flight hold is not what keeps an agent inside its cap; the ledger is. NONCE_HOLD_SECONDS (120s) only avoids handing back a transaction some other unsettled one has already doomed.

Not yet

• direct send (non-x402 transfer) — needs our own submit path; v1 is x402 only

• Masumi escrow flows (assetTransferMethod: masumi) pass through untouched; policy still applies to the amount

• policy is per-agent, not per-resource; add allowedResources if needed

License

Apache-2.0 — see LICENSE.