APN quickstart: a direct Base USDC transfer

This is the first journey from the Agent Payment Node (APN) README: a direct USDC transfer on Base. You create a profile, fund it, write an owner policy, prepare the payment, approve it in a terminal and read the receipt.

Updated

Before you start

  • Install APN first. See the install page. You need an Apple Silicon Mac and Node 24 on PATH.
  • Have a small amount of Base ETH for gas and Base USDC to send. APN does not fund the wallet for you.
  • Use a foreground terminal. Two steps ask for a typed code and cannot run in the background or through MCP.
  • Decide the recipient address and the caps. The caps are the owner's choice, and APN never fills them in.

Step 1: create a profile and read its address

Create a local wallet profile named agent, then show its status.

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

wallet status shows the public address. APN never prints or exports the private key. Fund that address manually with a small amount of Base ETH (gas) and Base USDC.

Step 2: write an owner policy file

Nothing moves money until the owner admits the asset. Write a policy file that admits Base USDC on the direct rail for your address. In this example, 1 USDC is 1000000 atomic units, so the per-transfer cap is 3 USDC and the daily cap is 10 USDC.

{
  "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" }
  ]
}
  • Replace <address from wallet status> with the address from step 1.
  • Replace <ISO-8601 instant> with the time the policy takes effect.
  • eip155:8453 is Base. The identifier is the Base USDC contract.

Step 3: stage and activate the policy

apn allowlist policy stage --profile agent --file /absolute/path/policy.json
apn allowlist policy activate --profile agent --revision 1        # foreground terminal, typed code

Staging binds the file to the frozen asset inventory and writes a revision that grants no authority yet. Activation shows the whole revision in a foreground terminal and needs the owner to type the six-character code printed under it. An agent cannot activate its own limits. See security for the allowlist model.

Step 4: check the balance

apn wallet balance --profile agent --chain eip155:8453 --asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --rpc-url https://mainnet.base.org

APN needs no RPC account or API key. Direct EVM transfers take an explicit --rpc-url, here the public Base endpoint.

Step 5: prepare the transfer

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

Prepare signs nothing. It freezes the recipient, amount, nonce, gas limit, fee envelope and expiry into one durable operation. The amount counts against the policy caps. --max-fee-wei is the owner's pre-submission fee budget. The output includes an operation ID and next_actions.

The idempotency key first-transfer-0001 ties this request to one operation. Running the same command again resolves to the same operation instead of creating a second payment.

Step 6: approve in a foreground terminal

apn pay transfer approve --operation <operation-id> --rpc-url https://mainnet.base.org   # foreground terminal

Approval re-checks the frozen facts and the active policy, shows the exact terms and asks for a typed code before signing. It reserves the amount in the shared usage ledger before signing. Approval accepts fee movements that keep the frozen transaction executable. It never re-prices a signed transaction.

Step 7: read the status and the receipt

apn operation status --operation <operation-id>
apn receipt get --operation <operation-id>

Completion needs the exact receipt and Transfer log at the network's required finality. receipt get names the frozen profile, chain, token, sender (wallet_address), recipient and amount, as operation status does.

What if the transfer stalls?

Run operation resume --operation <id> --rpc-url <url>. It performs only the next legal transition.

  • --observe-only true inspects an already submitted local EVM transfer without custody access.
  • A plain resume of a local EVM transfer sends a signature APN never dispatched, once.
  • After a dispatch, resume can pass the same signed transaction to the RPC again. It does so only when the RPC holds neither a receipt nor the transaction for the saved hash and the sender's finalized nonce is not past the frozen nonce.
  • The hash and nonce stay the same, so at most one copy can be included. APN never signs a second transfer.
  • operation abandon lets the owner close an eligible operation whose outcome cannot be proven, after accepting the unresolved risk in the terminal.

More on this in recovery.

Where do I go from here?

  • The same commands work for native coins (--asset native) and every listed token on the eleven direct EVM networks. See EVM.
  • Solana and TRON have their own -solana and -tron commands. See Solana and TRON.
  • To let an agent call APN, read the MCP page. MCP can prepare and read, but the human still approves.
  • To buy from a paid HTTP resource, see x402.

Questions about funding, limits or platforms are answered in the APN FAQ.

Questions

Does the agent need to hold my private key to send USDC?

No. APN holds an encrypted local wallet and never prints or exports the private key. The agent prepares, and the owner approves in a terminal.

How much is one USDC in the policy file?

1000000 atomic units. In the example, the per-transfer cap is 3000000 and the daily cap is 10000000.

What happens if I run prepare twice with the same idempotency key?

The key resolves to one durable operation, so you do not create a second payment.

Sources
  1. README: first journey, a direct Base USDC transfer
  2. README: how APN works
  3. README: recovery guarantees
  4. EVM asset transfers
  5. Allowlist policy guide