Agent Payment Node (APN)
A local-first payment runtime for AI agents where a human approves every signature and each payment is a crash-safe, idempotent operation.
- Source repo
- nuanu-ai/agent-payment-node
- Stars
- ★ 73
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 80/100 · Good
At a glance
- How it runs
- Works with
- Portable with changes
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer who wants an agent to prepare payments but insists on personally confirming each signature.
- Not a fit if
- Teams deploying to Linux or Windows
- Teams wanting fully unattended, hosted wallet custody
- Users needing savings-grade or multisig custody
- Website
- agentpaymentnode.com ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-19latest release v0.5.110 (2026-11-18)
- Source review
- 80/100 · Good
What does this agent do, and when should you use it?
APN is an open-source, local-first payment runtime for AI agents. Agents drive it through the apn CLI or a local stdio MCP server, while the human owner sets per-asset and per-rail limits and approves every signature in a foreground terminal. Each operational command prints exactly one apn.cli.v1 JSON envelope with ok, error, operation, receipt and next_actions, and every payment is a durable operation bound to an idempotency key, so crashes or lost responses never send the same money twice. Coverage spans direct native and token transfers on EVM networks, Solana and TRON; x402 purchases (EIP-3009 USDC, Permit2, ERC-20 transfer-proof merchants); USDC transfers with gas paid from the amount; bridges including LI.FI, Relay, Circle CCTP V2, GasZip, NEAR 1Click and Stargate V2; and guarded swaps on Uniswap V3, SunSwap, Jupiter and Orca. It runs on Apple Silicon macOS with Node 24, stores wallets as AES-256-GCM envelopes unlocked by a wrapping secret in the macOS login Keychain, and describes this as local_software_disposable custody rather than savings custody.
On the agent side, prepare commands such as apn pay transfer prepare-asset, x402 fetch prepare, bridge prepare or swap ethereum uniswap prepare freeze one exact effect — chain, asset, amount, recipient, nonce, fee envelope and expiry — under an idempotency key and sign nothing. The human then runs the matching approve/execute in a foreground terminal, which re-checks the frozen facts and the active owner allowlist, shows the exact terms and requires a typed operation-bound code before signing. Every send sits behind a durable marker: an ambiguous send is only observed afterwards, never repeated, and operation status, operation resume, operation abandon and receipt get take a saved operation of any family and run that family's own recovery code. MCP exposes tools projected from the same catalog and running the same code, but never approves: a single apn_foreground_handoff tool validates arguments exactly like the CLI and returns the command for the human to run. RPC endpoints come from an explicit --rpc-url or an APN_<CHAIN>_RPC_URL variable, must be credential-free public HTTPS, and a missing value refuses with APN_RPC_CONFIG rather than substituting another endpoint; apn wallet portfolio performs a read-only balance sweep of the profile's EVM, Solana and TRON accounts.
- A solo developer who wants an agent to prepare payments but insists on personally confirming each signature.
- A service operator letting an agent buy x402 resources in USDC (EIP-3009 or Permit2 paths) under per-operation and daily caps.
- An operator moving stablecoins between Base/Arbitrum, Solana and TRON who needs bridges or swaps with auditable receipts.
- A platform team adding payment ability to its own MCP client via
apn mcp servewhile keeping signing authority with a human. - An organization needing supply-chain verification (GitHub attestation, SPDX SBOM, release manifest) that an installed APN artifact matches the source commit.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
brew install nuanu-ai/tap/apn
- Config files
~/.apn- Runtime
- Node.js 24
- Install notes cover
- macOS
How do you install or deploy this agent?
You need macOS on Apple Silicon and Node 24 (>=24 <27). Install through Homebrew:
brew install nuanu-ai/tap/apnHomebrew's node@24 is keg-only and not on PATH, while apn runs on the first node on PATH; if the version does not match, apn prints one APN_NODE_UNSUPPORTED line and exits 1. Put Node 24 first:
export PATH="/opt/homebrew/opt/node@24/bin:$PATH"The first wallet command creates ~/.apn (mode 0700) and one encrypted wallet envelope per profile (mode 0600). Then inspect the installed contract:
apn --version
apn help --jsonHow do you use this agent?
Create a local wallet, then fund its public address manually with a small amount of Base ETH (gas) and Base USDC:
apn wallet ensure --profile agent
apn wallet status --profile agentWrite an allowlist policy file (1 USDC is 1000000 atomic units; caps are the owner's choice):
{
"schemaVersion": "apn.allowlist-policy-file.v1",
"overlayVersion": "agent.1",
"accounts": { "evm": "<address from wallet status>" },
"effectiveAt": "<ISO-8601 instant>",
"admissions": [
{ "chain": "eip155:8453", "kind": "token", "identifier": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"rail": "direct", "maximumPerTransferAtomic": "3000000", "dailyLimitAtomic": "10000000" }
]
}Stage and activate it in a foreground terminal, then run a first transfer:
apn allowlist policy stage --profile agent --file /absolute/path/policy.json
apn allowlist policy activate --profile agent --revision 1
apn wallet balance --profile agent --chain eip155:8453 --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 --rpc-url https://mainnet.base.org
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
apn pay transfer approve --operation <operation-id> --rpc-url https://mainnet.base.org
apn operation status --operation <operation-id>
apn receipt get --operation <operation-id>To use it from an MCP client, print the launch descriptor and start the stdio server:
apn mcp config
apn mcp serveWhat are this agent's strengths and limitations?
- No-double-spend design: idempotency keys plus durable send markers mean an ambiguous send is observed, never retried, and survives crash, restart, reinstall and upgrade.
- Human approval is a hard boundary: approve/execute/abandon need real TTYs and an operation-bound code, and MCP can only return an
apn_foreground_handoffcommand instead of approving. - Unusually broad coverage under one operation contract: EVM/Solana/TRON transfers, three x402 paths, multiple bridges and several DEXes.
- Fine-grained owner allowlist by asset, rail (
direct,x402,gasless,bridge,swap), mechanism and optional recipient pin, with per-operation and daily caps. - Verifiable supply chain: releases are built twice with Node 24.15.0 and must be byte-identical, with an SPDX 2.3 SBOM, a release manifest and GitHub artifact attestations plus a
verify-supply-chain.mjsscript.
- Narrow platform support: only Apple Silicon macOS with Node 24 is supported;
docs/platform-support.mdrecords what Linux or Windows would need but does not deliver it. - Custody is explicitly
local_software_disposable, not savings custody; it does not protect against compromise of the same unlocked login session, process, user or host, and transient key copies in JavaScript memory are not guaranteed to be zeroized. - Depends on pinned third-party providers (e.g.
[email protected],@metamask/[email protected]); awal starts a detached Electron wallet server, and its one-time verification code is passed as a command-line argument readable viapsby other processes of the same user. - Setup is involved: policy files, a foreground approval terminal, RPC variables and multi-step command sequences, with version, provenance and
apn help --jsonto be cross-checked. - Test evidence is source-level proof; live mainnet acceptance is tracked per family in the guides, with some rows still open.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agent Payment Node (APN) This agent | 80 · Good | CLIFree | ★ 73 | 2d ago | TypeScript | — |
| Agency Orchestrator: One Sentence to Orchestrate an AI Expert Team | 71 · Some gaps | CLIFree + model costs | ★ 2.5k | 10d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| OpenOSINT: AI-Powered OSINT Investigation Agent | 68 · Some gaps | CLIFree + model costs | ★ 2k | 5d ago | Python | Claude Code · Claude.ai · OpenAI API |
| assh | 65 · Some gaps | CLIFree | ★ 22 | 11d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Least privilege: README states MCP never approves, foreground terminal confirmation, owner allowlist per asset/rail caps, and MCP tools projected from the same catalog; well evidenced (3). User confirmation: prepare/approve split, frozen facts, typed code, MCP only for pure decreases; well evidenced (3). Data flow transparency: RPC configuration, env vars, keyless defaults, portfolio sending public addresses are documented (3). Sensitive data: keys never printed/exported, ~/.apn 0700, wallet envelopes 0600, native Keychain agent, zeroize dependency; well evidenced (3). Dependency security: npm-shrinkwrap, exact pins, overrides, SBOM, double-build byte-identical, attestation verify script, CI audit gates; well evidenced (3). External effects: idempotency keys, durable markers, ambiguous sends observed not repeated, finality checks; well evidenced (3). Rollback: operation abandon and resume exist, but abandon keeps ledger reservation and some families lack successors, so recovery is incomplete; deducted (2). Source attribution: MIT and copyright line clear, but publisher identity unverified and no signer identity statement; deducted (2).
Self-consistency: README command catalog, help --json manifest, removed_v1_commands and code error codes (APN_IDEMPOTENCY_CONFLICT, APN_STATE_CORRUPT) align; well evidenced (3). Dependency availability: engines and os/cpu restrict to darwin/arm64, Node >=24 <27, Homebrew keg-only node@24 needs manual PATH; narrow platform surface; deducted (2). Failure messages: APN_NODE_UNSUPPORTED, APN_RPC_CONFIG, APN_RPC_RATE_LIMITED, next_actions, closed_blockers give structured errors and next steps; well evidenced (3).
Audience and scenarios: targets developers/operators needing agent-initiated payments; broad scenarios but high barrier; deducted (2). Capability boundaries: explicitly lists CLI-only families, ten commands without MCP handoff, platform support matrix boundary; well evidenced (3). Trigger precision: commands and tools one-to-one projected, argument validation matches CLI, but very wide command surface raises selection cost; deducted (2). Environment fit: Apple Silicon macOS + Node 24 only; Linux/Windows only described as needing work; deducted (1).
Information architecture: clear README sections, generated command catalog, per-family docs; well evidenced (3). Install notes: brew tap, PATH guidance, version verification steps complete (3). Naming stability: manifest v2 merged/removed v1 commands with replacements, indicating breaking-change history; deducted (2). Examples and FAQ: first-journey example and multiple guides, but no standalone FAQ; deducted (2). Known limitations: platform matrix and per-guide proven/open rows, but limitations scattered and not consolidated; deducted (2). License: full MIT text consistent with package.json (3). Versioning/changelog: semver version and removed_v1_commands, but no standalone CHANGELOG; deducted (2). Maintenance responsibility: SECURITY.md covers only latest release, publisher unverified, no maintainer list or SLA; deducted (1).
Output usability: uniform apn.cli.v1 JSON envelope, receipt, next_actions, machine-consumable; well evidenced (3). Marginal value: local-first, idempotent, owner-capped payment runtime is genuinely differentiated, but ecosystem and platform are limited; deducted (2). Cost benefit: strong safety and auditability, but install barrier, platform restriction and command complexity raise adoption cost; deducted (2).
Claim traceability: most README claims map to code, tests and docs, but some (double-build byte-identical, attestation) are documentation-only and unverifiable statically; deducted (2). Cross-source corroboration: tests and README corroborate allowlist, policy activation and MCP parity, but the sample is limited; deducted (2). Fact/inference separation: docs distinguish source tests from live payment proof and mark proven/open rows, but some security claims remain assertions; deducted (2).
- Supports only Apple Silicon macOS and Node >=24 <27; Homebrew node@24 is keg-only and needs manual PATH adjustment, otherwise apn exits with APN_NODE_UNSUPPORTED.
- Publisher identity is unverified and SECURITY.md covers only the latest release with no maintainer list or support commitment; verify release provenance and attestation before production use.
- operation abandon keeps the ledger reservation (amount stays charged) and some families lack successor recovery commands, so rollback is not fully reversible.
- The command surface is very wide (multi-chain, bridges, swaps, multiple x402 mechanisms); mis-selection risk relies on the owner allowlist and foreground confirmation.
- Supply-chain claims such as double-build byte-identical output, SBOM and attestation appear only in documentation and cannot be verified statically; follow the README steps to verify independently.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.5.110 Agent Payment Node v0.5.110
Release notes excerpt
What's Changed * fix(metamask): 0.5.109 seal the revoke request id and read it on resume by @Oscorped in https://github.com/nuanu-ai/agent-payment-node/pull/630 Full Changelog: https://github.com/nuanu-ai/agent-payment-node/compare/v0.5.109...v0.5.110View on GitHub ↗ -
v0.5.109 Agent Payment Node v0.5.109
Release notes excerpt
What's Changed * fix(metamask): native and revoke sends name their own MetaMask request id (0.5.108) by @Oscorped in https://github.com/nuanu-ai/agent-payment-node/pull/629 Full Changelog: https://github.com/nuanu-ai/agent-payment-node/compare/v0.5.108...v0.5.109View on GitHub ↗ -
v0.5.108 Agent Payment Node v0.5.108
Release notes excerpt
What's Changed * 0.5.107: QA fixes (19 findings + MetaMask request read) by @Oscorped in https://github.com/nuanu-ai/agent-payment-node/pull/628 Full Changelog: https://github.com/nuanu-ai/agent-payment-node/compare/v0.5.107...v0.5.108View on GitHub ↗
FAQ
Can the agent move money without a human?
prepare freezes an exact effect and signs nothing; approve/execute/abandon, wallet connect and allowlist activation require a foreground TTY and a typed operation-bound code. MCP tools cannot approve — they return an apn_foreground_handoff command that validates arguments and reads or writes nothing.Does it run on Linux or Windows?
>=24 <27) is supported. docs/platform-support.md records the boundary and what Linux or Windows would need, but those platforms are not a supported path.Do I need an RPC provider account?
--rpc-url or read APN_<CHAIN>_RPC_URL; endpoints must be credential-free public HTTPS. Some families (portfolio, Circle CCTP source) have pinned keyless defaults, and where no default exists a missing variable refuses with APN_RPC_CONFIG instead of silently substituting an endpoint.What happens if a transfer stalls or its outcome is unknown?
operation resume performs only the next legal transition and an ambiguous send is never resent; operation abandon closes an operation only after the owner accepts the unresolved risk in the terminal, and the ledger reservation stays charged.Where are keys and credentials kept?
~/.apn/wallets/<profile>.json is a versioned AES-256-GCM envelope whose wrapping secret lives in the macOS login Keychain as the generic password ai.nuanu.apn.wrapping-secret.v1/default. APN never prints or exports a private key and never receives QR payloads, browser credentials, provider tokens, seed phrases or private keys.Is Agent Payment Node (APN) free?
Is Agent Payment Node (APN) open source?
Is Agent Payment Node (APN) safe to use?
Is Agent Payment Node (APN) still maintained?
Who makes Agent Payment Node (APN)?
What is Agent Payment Node (APN)'s official website?
Thanks — we use this to improve the page.