APN payment recovery

Agent Payment Node (APN) keeps every payment as a durable operation with an idempotency key, so a crash or a lost response never sends the same money twice. This page explains what is saved, what resume and abandon do, why an unknown outcome is never treated as success, and where APN's proof stops.

Updated

What is a durable operation in APN?

A prepare command freezes one exact effect and signs nothing. For a direct transfer that means chain, asset, amount, recipient, nonce, gas limit, fee envelope and expiry. The effect is stored as an operation. Status and receipts survive restart, reinstall and upgrades, because Homebrew does not own ~/.apn.

Every send sits behind a durable marker. Local execution persists the effect binding before submission and recovers only the exact encrypted signed transaction or authorization. Provider-atomic execution (for example Coinbase or MetaMask wallets) persists a no-replay start before it invokes the provider.

How do idempotency keys prevent double payments?

Idempotency keys resolve to one durable operation. Repeating the same request returns the existing operation before any metadata refresh. Changing material inputs under the same key is a conflict, including a different operation kind.

apn pay transfer prepare-asset --profile agent --chain eip155:8453 \
  --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --to <recipient-address> --amount 0.01 \
  --max-fee-wei <fee-budget-wei> --idempotency-key first-transfer-0001 --rpc-url https://mainnet.base.org

If an agent crashes after this call, it runs the same command again with the same key and gets the same operation back. Public RPCs can rate-limit, and APN reports a 429 as APN_RPC_RATE_LIMITED. Rerunning the same command is safe because prepared operations are idempotent.

What is an ambiguous send, and how does APN handle it?

An ambiguous send is one where APN started to send but cannot prove what happened: the process died, the RPC timed out, or a provider call returned nothing. APN observes before it does anything else. Lost outcomes are ambiguous and need independent receipt evidence. They are never resent blindly.

  • A saved signature is dispatched only as its exact bytes, or kept for operation resume. APN never signs a second transaction for a transfer and never changes its nonce or fees.
  • After a restart APN retrieves only the saved signature. If none exists, the operation fails before effect rather than signing a replacement.
  • A provider wallet that may have acted without proof becomes a no-replay ambiguous_effect.
  • A transaction hash or a successful receipt alone never proves an exact token payment. APN also requires the sole Transfer log with the exact amount, recipient and token.

An operation that is not terminal blocks new money operations only on its own network and sending account. The refusal names the blocking operation. Another chain, another wallet, or the Solana or TRON account of the same profile stays available.

How do operation status, resume and abandon work?

These commands take a saved operation of any family and run that family's own recovery code. A family whose recovery is a separate command (Circle, x402 merchant, Permit2, Relay, GasZip funding, Uniswap token, Stargate token cleanup) answers with that command.

apn operation status --operation <operation-id>
apn operation resume --operation <operation-id> [--rpc-url <https-url>] [--wait-seconds <1..300>] [--observe-only true] [--coinbase-observation-rpc publicnode-base] [--observation-rpc-env <APN_ENV_RPC_URL>]
apn operation abandon --operation <operation-id>
apn receipt get --operation <operation-id>
  • operation status reads the saved record.
  • operation resume performs only the next legal transition. --observe-only true inspects an already submitted local EVM transfer without custody access and never broadcasts. Solana and TRON refuse it.
  • operation abandon lets the owner close an eligible operation whose outcome cannot be proven, after accepting the unresolved risk in the terminal.
  • receipt get names the frozen profile, chain, token, sender, recipient and amount.

For a local EVM transfer, a plain resume first reads the receipt of the saved hash. Only when the RPC holds neither a receipt nor the transaction for that hash, and the sender's finalized nonce is not past the frozen nonce, may it pass the same signed transaction to the RPC again. Hash and nonce are the same, so at most one copy can be included. If the sender's finalized nonce has moved past the frozen one and no node knows the transaction, the transfer ends failed_proven_superseded, the usage hold is released and nothing is sent.

Abandon is the last exit. A dispatched transfer that no proof can decide ends abandoned_unknown, is never sent again, and its usage hold stays charged. A saved record APN can no longer read blocks only the accounts it names. Abandon releases those claims but leaves the file and any usage-ledger reservation as they are, so the amount stays charged.

Why is an unknown payment outcome never treated as success?

APN completes a payment only on proof. For EVM transfers, completion needs the exact receipt and Transfer log at the network's required finality. For x402, HTTP success alone never completes a payment, and settlement is proven on chain. unknown_finality is an open outcome APN keeps observing, and abandoned_unknown is an open risk the owner accepted. Neither is a payment that happened.

StateWhat it means
submitted_pendingThe approving invocation found no receipt yet. Resume or observe it later.
unknown_finalityA receipt is not yet at the required head, or the outcome is unclear. Resume completes it later without a new signature.
failed_proven_supersededThe chain proved the dispatched transaction can no longer land, so the amount did not move. APN sends nothing more, and the hold is released.
abandoned_unknownThe owner closed an undecidable operation. It is never sent again and the hold stays charged.

An agent reading an apn.cli.v1 envelope should follow next_actions, not assume. The envelope names the next command to run or the option to fix.

Recovery guarantees: what APN promises

  • Idempotency keys resolve to one durable operation.
  • Local execution persists the effect binding before submission and recovers only the exact encrypted signed transaction or authorization.
  • Provider-atomic execution persists a no-replay start before invoking the provider.
  • Lost outcomes are ambiguous and need independent receipt evidence. They are never resent.
  • Status and receipts survive restart, reinstall and upgrades.
  • A non-terminal operation blocks new money operations only on its own network and sending account.

When a new prepare is refused by a blocker, APN first runs the blocker's own bounded observation once, with no signature, send or consent. If that proves the blocker terminal, the prepare runs again once and the answer lists the closed operation in optional closed_blockers. Otherwise the first refusal returns.

Proof boundary: what APN does not prove

The test suite covers encryption, permissions, concurrency, restart, byte-identical recovery, idempotency, receipts and every family's journeys without public network traffic or money. Deterministic tests are source proof, not live provider acceptance or payment proof. Live mainnet acceptance, public release and Homebrew delivery are separate gates recorded per family in its guide.

Hub, contracts, remote MCP and Stellar are outside the repository. Some completion rules also trust the RPC. For safe networks the receipt must be at or below the selected RPC's safe head, and the guide notes this trusts the RPC and is not a trustless rollup proof. See security for the wider model and x402 for settlement proof on x402 purchases.

Questions

Can APN send the same payment twice?

No by design. An idempotency key resolves to one durable operation, and APN never signs a second transaction for a transfer. At most the same signed bytes may be passed to the RPC again under exact conditions.

What if my agent crashes mid-payment?

Run apn operation status --operation <id>, then apn operation resume. Resume performs only the next legal transition and never signs a replacement.

What does operation abandon do?

It closes an eligible operation whose outcome cannot be proven, after the owner accepts the risk in the terminal. The operation is never sent again. A dispatched transfer keeps its usage hold charged; a direct EVM transfer abandoned before its signature was dispatched releases it.

How do I get a receipt?

Run apn receipt get --operation <operation-id>. It names the frozen profile, chain, token, sender, recipient and amount.

Is an unknown outcome the same as a failed payment?

No. Unknown means APN could not prove either result. It needs independent receipt evidence or the owner's abandon, and it is never counted as success.

Sources
  1. README: Recovery guarantees
  2. README: Proof boundary
  3. README: How APN works (Prepare, approve, recover)
  4. README: First journey (resume and abandon)
  5. docs/evm-assets.md: Safety and recovery
  6. docs/allowlist-policy.md: How caps are counted
  7. docs/x402-settlement-compatibility.md