APN wallets and profiles

Agent Payment Node (APN) gives an AI agent a wallet through profiles. A profile is either a local wallet APN creates or imports, or a provider-managed wallet that APN binds without ever holding its key. This page explains each kind, who holds the key, and what limits still apply.

Updated

What is an APN profile?

Every money command in APN names a profile with --profile. The profile decides which wallet signs. There are two families:

  • A local wallet that APN creates (wallet ensure, wallet ensure-solana, wallet ensure-tron) or imports (wallet import).
  • A provider-managed wallet bound with wallet connect: Coinbase Agentic Wallet, MetaMask Agent Wallet or MetaMask Smart Account.

APN never prints or exports a private key. Provider balance is never spending authority either: a funded provider wallet can spend only through the limits described below. See security for the owner limits.

How do I create a local wallet for my AI agent?

The EVM wallet comes first. It is the one used in the quickstart:

apn wallet ensure --profile agent
apn wallet status --profile agent

wallet status shows the public address. Fund it manually. The first wallet command creates ~/.apn with mode 0700 and one encrypted wallet envelope per profile with mode 0600. wallet ensure also checks that an existing wallet's Keychain secret is still present, and it decrypts nothing.

Solana and TRON have their own commands, and each wallet has its own encrypted key. A local Solana wallet never reuses the profile's EVM key:

apn wallet ensure-solana --profile solana-local --provider local --accept-risk true
apn wallet ensure-tron --profile tron-local --provider local --accept-risk true

--accept-risk true is the explicit custody acknowledgement. wallet ensure-solana also accepts --provider coinbase-awal for an existing Coinbase Solana account, while wallet ensure-tron takes local only. For chain details see Solana, TRON and EVM.

Can I import an existing private key into APN?

Yes, with wallet import. It reads the key from a file and checks it against the address you expect:

apn wallet import --profile <profile> --key-file <absolute-path> --key-name <env-name> --expected-address <checksummed-address>
  • --key-file must be an owner-only file with mode 0600, a single link, a regular file, at most 64 KiB, reached without symbolic links.
  • A FIFO, device, socket or directory is refused at once with APN_STATE_SECURITY before anything is opened, and no key is written.
  • An import never replaces a sealed key. A retried import into an incomplete profile finishes it only when the file holds that very key. Any other key is refused with APN_PROFILE_DRIFT.

After import, APN seals the key like a generated one. You can import a key, but you can never read it back out through APN.

How does APN store local wallet keys?

Each profile's key lives in ~/.apn/wallets/<profile>.json, a versioned AES-256-GCM envelope. A random 256-bit wrapping secret is stored as a generic password in the macOS login Keychain. APN writes that secret to /usr/bin/security -i on stdin, never in its arguments, so ps does not show it.

The README calls this local_software_disposable custody, not savings custody. Encryption protects a copied ~/.apn without the Keychain secret. It does not protect against compromise of the same unlocked login session, process, user or host. Keep only what the agent needs to spend in a local wallet. The full threat model is on the security page.

Missing Keychain material, failed authentication, unsafe permissions or an identity mismatch fail closed. APN never rotates a wallet silently. If the wrapping secret is lost while sealed records exist, APN refuses to mint a new one and tells the owner to restore the login Keychain item.

How do I connect Coinbase or MetaMask wallets to APN?

wallet connect binds a provider wallet to a profile. Authentication stays in the foreground terminal:

apn wallet connect --profile provider-one --provider coinbase-agentic-wallet
apn wallet connect --profile mm --provider metamask-agent-wallet [--auth-method browser]
apn wallet connect --profile sa --provider metamask-smart-account --auth-method browser \
  --permission-cap-usdc-atomic <cap> --permission-expires-at <unix-seconds> --idempotency-key sa-connect-0001

APN binds the exact address the completed provider session reports. If a later session selects another address, APN fails closed with APN_PROFILE_DRIFT; rebind with --expected-revision. APN never receives QR payloads, browser credentials, provider tokens, seed phrases or private keys. Over MCP, wallet connect returns a handoff because it needs a human (see APN MCP).

How do the provider wallets differ?

ProfileWho holds the keyWhat APN does
Local walletAPN, encrypted under a macOS login Keychain secretSigns locally and sends once: after foreground approval, or for x402 within the owner's profile policy
Coinbase Agentic Wallet (awal@2.12.1)The providerMarks started durably, invokes the provider once, and requires an independent Base receipt with the exact USDC Transfer to complete
MetaMask Agent Wallet (@metamask/agent-wallet@6.1.5, Guard server wallet)The providerDirect transfers and x402 use the same operation contract. Guard MFA returns provider_pending, and operation resume --wait-seconds watches that request
MetaMask Smart AccountAPN keeps one encrypted session account plus the ERC-7715 grantDerives one exact child delegation per transfer after foreground approval
  • For Coinbase Agentic Wallet, any possible effect without proof becomes a no-replay ambiguous_effect.
  • For the MetaMask Smart Account, wallet permission list|sync|disable|forget manage the binding. sync, disable and forget take --expected-revision, and a stale one is refused with APN_PROFILE_REVISION_CONFLICT.
  • operation recover-provider-request binds an independently known MetaMask request to an ambiguous transfer without replaying it.

wallet connect is a binding, not a custody transfer. The provider keeps control of its own wallet and its own controls.

Which limits apply to provider wallets?

Provider balance is never spending authority. Local x402 and Coinbase Agentic Wallet x402 payments are governed by the profile policy. Direct USDC transfers from a Coinbase, MetaMask Agent or MetaMask Smart Account profile are not admitted by the owner allowlist at all, so no allowlist row, cap or usage hold applies to them. Their limits are the provider's: the Agent wallet's Guard policy and MFA, the Smart Account's root permission, and the Coinbase wallet's own controls.

Provider profiles are also narrower than local ones. Provider profiles cannot use generic direct transfers of native coins and listed tokens; their direct path is Base USDC through the provider route. For x402 they are refused before provider execution on networks other than Base, and Solana x402 is available on the local profile only. See the x402 page and the gasless page for lane details.

Questions

Does APN export my private key?

No. APN never prints or exports a private key. Raw private keys never appear in command output, public operation state or receipts.

Which wallets does APN support for AI agents?

Local wallets (EVM, Solana, TRON), plus Coinbase Agentic Wallet, MetaMask Agent Wallet and MetaMask Smart Account as provider-managed profiles.

Is an APN local wallet safe for large amounts?

The README says it is disposable custody, not savings custody. It does not protect against compromise of the same unlocked login session, process, user or host.

Can I use more than one wallet?

Yes. Each profile has its own name. One profile can also hold EVM, Solana and TRON accounts, and APN keeps a separate key for each chain family.

What happens if I lose the Keychain secret?

APN fails closed and does not create a new secret over sealed records. Restore the login Keychain item from a backup, and every sealed record opens again.

Sources
  1. README: How APN works (Profiles)
  2. README: Provider wallets
  3. README: Custody and threat model
  4. docs/solana.md
  5. docs/tron.md
  6. docs/allowlist-policy.md: where pins do not reach
  7. docs/evm-assets.md: x402 on Ethereum and Arbitrum