APN Solana payments for AI agents

Agent Payment Node (APN) sends native SOL, canonical USDC and pinned USDT on Solana mainnet from a local software wallet. An AI agent prepares the transfer, and the owner approves it in a terminal. This page shows the assets, the exact commands, the two owner limits every transfer must fit, and what recovery looks like.

Updated

Which Solana assets can an AI agent send with APN?

--assetAssetDecimals
solnative SOL9
usdcCircle USDC, mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v6
usdtUSDT from the frozen allowlist, mint Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB6

Both tokens use the canonical SPL Token program and associated token accounts. Arbitrary mints, Token-2022 assets and self-transfers are outside this direct transfer.

A local Solana wallet has its own encrypted ed25519 seed. It never reuses the profile's EVM key. APN signs locally and sends once.

Which wallet profiles work on Solana?

ProfileDirect transfer
Local softwareAvailable. Foreground policy and payment approval required.
Coinbase awal 2.12.1Blocked. The pinned provider contract does not guarantee the fee and rent payer and the sender debit cap.
MetaMask Smart AccountUnavailable
MetaMask Agent WalletUnavailable

A provider refusal never switches an operation to the local signer. See wallets for the profile model.

Which owner allowlist rail applies to Solana transfers?

The direct rail. Every asset starts denied, and two owner decisions are needed. A transfer must fit both.

  1. The owner allowlist policy must admit the asset on the direct rail. Its per-operation and daily caps apply.
  2. The chain policy, admitted in a foreground terminal, caps the fee and rent in SOL and enforces its own per-transfer and UTC-daily principal limits.
{ "chain": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d", "kind": "native", "rail": "direct", "maximumPerTransferAtomic": "28600000", "dailyLimitAtomic": "95500000" }

That row is the repository's example for native SOL. Nothing defaults to those caps. Both checks run at prepare and again before signing. See security for the full custody model.

Solana x402 exact payments use a different rail, x402. They work on the local software profile only, for USDC and USDT that the owner admitted with the x402-exact-svm mechanism pin. Native SOL offers and Token-2022 mints are refused. See x402.

How do I send USDC on Solana from an AI agent?

Create the wallet, fund the returned public address yourself, set the chain policy, then prepare and approve. The --accept-risk true flag is the custody acknowledgement. The command creates a real local wallet when run outside a test fixture.

apn wallet ensure-solana --profile solana-local --provider local --accept-risk true
apn wallet balance-solana --profile solana-local --asset usdc
apn policy admit-solana --profile solana-local --asset usdc \
  --max-per-transfer 1 --daily-limit 3 --max-fee-sol 0.003
apn pay transfer prepare-solana --profile solana-local --asset usdc \
  --to <solana-recipient> --amount 1 --max-fee-sol 0.003 \
  --idempotency-key solana-example-001

apn pay transfer approve --operation <operation-id>
apn operation status --operation <operation-id>
apn operation resume --operation <operation-id>
apn receipt get --operation <operation-id>

The limits in the example only illustrate the syntax. policy admit-solana shows the exact account, genesis, mint, atomic limits and policy identity, then requires the displayed phrase. Over MCP it returns a foreground handoff and cannot approve. To inspect capabilities without network access, run apn wallet capabilities-solana.

  • Amounts must be positive canonical decimal strings such as 1, 1.25 and 0.000001. Signs, exponent notation, leading zeroes and excess precision are refused.
  • --max-fee-sol covers the sender's network fee plus any rent for the recipient's associated token account. It must fit the admitted cap.
  • USDC and USDT transfers still need SOL for these costs. USDC principal is never added to SOL fees as if they were the same currency.
  • Prepare sends no transaction. It freezes an unsigned intent.

Which Solana RPC does APN use?

When APN_SOLANA_RPC_URL is unset or empty, APN uses the anonymous public endpoint https://api.mainnet-beta.solana.com. No signup or API key is required. Set the variable only to choose another public HTTPS endpoint. An invalid non-empty value refuses instead of falling back. URL credentials, query parameters, fragments, private addresses and redirects are rejected. APN verifies mainnet genesis 5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d at execution and observation boundaries.

  • Each command gets a budget of 24 physical POSTs. A JSON-RPC batch counts as one.
  • POST starts to the same provider are paced at least 750 ms apart across processes.
  • HTTP 429 stops the command without a retry and starts a cooldown of 2 to 30 seconds.
  • The common --rpc-url option selects the EVM RPC only.

What does the approval and send guard check?

Approval expires 240 seconds after preparation. That bounds the owner's reading time. The sending window opens after approval, when the send guard takes a fresh block reference. The terminal shows sender, recipient, network, asset, amount, fee and rent payers, caps and policy.

  1. The guard re-acquires the recent blockhash and block height. At least 38 blocks (about 15 seconds) must remain.
  2. It re-proves the frozen fee, rent, recipient-account and funding bounds.
  3. It simulates the exact bytes with simulateTransaction and sigVerify: false. A transaction that would fail on chain is refused while no signature exists.

Only a lost simulation read is retried, up to 4 times, 5 seconds apart. Every chain answer ends the operation before any effect, with nothing signed. A stale preparation needs a new idempotency key.

What happens if a Solana transfer is interrupted?

Local signing stores one encrypted transaction bound to the operation and its fingerprint. Submission intent is durable before the first send. APN never reconstructs or resends a transaction after a possible broadcast. See recovery.

  • A crash before the first submission may recover the same sealed effect. A crash after it permits observation only.
  • operation resume makes one bounded observation. It does not accept --wait-seconds for this rail, and --observe-only true is refused here.
  • Completion needs finalized evidence: verified signed bytes, exact instructions, sender and recipient effects, and actual fees and rent. Token transfers also need the exact mint, account owners and token deltas.
  • If a transfer stays unknown_finality after the blockhash expires and history shows no status, the owner can run apn operation abandon --operation <operation-id> in a foreground terminal. The financial outcome stays unknown.

Can an agent swap on Solana with APN?

Yes, through two keyless guarded swap commands. Both use the swap rail, not direct, and the owner must admit both assets with the route or pin from inventory. Both need the local Solana wallet as payer and recipient. Full commands are on the swaps page.

  • Jupiter: apn swap solana jupiter swaps native SOL for canonical USDC through Jupiter Swap API V1. APN accepts only direct single-step routes through four reviewed Orca Whirlpool SOL/USDC pools.
  • Orca: apn swap solana orca swaps through two pinned Whirlpools: sol-usdc (SOL to USDC) and usdc-usdt (USDC to USDT). APN uses no API key and no off-chain quote.

For moving funds into Solana from other chains, see bridges.

Questions

Does APN support AI agent USDC transfers on Solana?

Yes. The local software profile sends canonical USDC (mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v), native SOL and pinned USDT on Solana mainnet, after two owner decisions (the allowlist admission and the chain policy) and a foreground approval of the payment.

Do I need an RPC provider account for Solana?

No. APN uses the anonymous public mainnet endpoint unless you set APN_SOLANA_RPC_URL. Public RPC can rate-limit requests.

Can the agent use Coinbase or MetaMask wallets on Solana?

No. Direct Solana transfers are blocked for Coinbase awal and unavailable for both MetaMask profiles. Only the local software wallet works.

Which swaps does APN run on Solana?

Jupiter for SOL to USDC through reviewed Orca Whirlpool pools, and Orca directly for SOL to USDC and USDC to USDT.

Sources
  1. solana.md: assets, policy, send guard, recovery
  2. allowlist-direct-integration.md: direct rail and Solana rules
  3. allowlist-policy.md: rails and example caps
  4. jupiter.md: Jupiter swap
  5. orca.md: Orca swap