APN guarded swaps for AI agents

Agent Payment Node (APN) runs four guarded swap families: Uniswap V3 on Ethereum, SunSwap on TRON, and Jupiter and Orca on Solana. None uses an API key for price. Only the profile's local wallet signs, and no swap provider holds the funds or a key. This page lists each swap, the exact commands and the owner admission every swap needs.

Updated

Which swaps can an AI agent run with APN?

ChainCommandSwaps
Ethereumapn swap ethereum uniswapnative ETH to canonical USDC or USDT; native ETH to WBTC with its own admission (Universal Router 2.2.0)
Ethereumapn swap ethereum uniswap-tokencanonical USDC to USDT and USDT to USDC (original V3 SwapRouter)
TRONapn swap tron sunswapnative TRX to canonical USDT (SunSwap V2 router)
Solanaapn swap solana jupiternative SOL to canonical USDC, through four reviewed Orca Whirlpool pools (Jupiter Swap API V1)
Solanaapn swap solana orcaSOL to USDC (sol-usdc) and USDC to USDT (usdc-usdt)

Neither Uniswap family uses an API key, an off-chain quote service or the Uniswap Trading API. SunSwap and Orca need no API key and no off-chain quote. Jupiter's public API supplies the quote and swap instructions, and APN checks every instruction, account and program against fixed pins.

Which owner allowlist rail applies to swaps?

The swap rail. The profile's active allowlist policy must admit both assets of the swap on swap, each with the route or mechanism pin printed by the family's inventory command. Without it, prepare refuses with swap_owner_admission_required. A policy changed after prepare refuses with swap_policy_drift. See security.

  • The per-operation cap is checked at prepare. The daily cap is enforced by the shared usage ledger when approval reserves the input. The output asset's cap is checked against the minimum output.
  • A refusal names the side (source or destination), the chain, the asset and an admissionGap: network_not_listed, asset_not_listed, swap_rail_not_admitted or swap_route_not_admitted.
  • recipients pins are allowed on either swap row. The Jupiter, Orca and SunSwap swaps can pay only the owner's own account.
  • Staging and activation work as for every policy: apn allowlist policy stage and apn allowlist policy activate, in a foreground terminal.

How does the common swap flow work?

  1. inventory lists the pins and routes. It grants nothing.
  2. quote builds, checks and simulates one unsigned quote with a slippage limit and the owner's slippage cap. It signs nothing.
  3. prepare binds the saved quote to the owner policy under an idempotency key.
  4. approve runs in a foreground terminal only. It shows the exact screen, takes the typed code, re-checks, signs locally and sends once.
  5. status observes the exact transaction and never signs or sends. Run it again until the operation is terminal.

Over MCP, inventory, quote, prepare and status are tools. approve and execute are reachable only through apn_foreground_handoff, which returns APN_FOREGROUND_APPROVAL_REQUIRED with the exact CLI command. --slippage-bps must not exceed --owner-slippage-cap-bps, which is at most 10000. No option has a default.

How do I swap ETH to USDC with Uniswap V3?

APN_ETHEREUM_RPC_URL is required: a public HTTPS Ethereum endpoint without credentials. --amount is in wei, --output-token is the pinned USDC, USDT or WBTC address, and --deadline is unix seconds within the next 30 minutes.

QUOTE=$(apn swap ethereum uniswap quote --profile <profile> --account <account-address> --to <recipient-address> --output-token 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1000000000000000 --slippage-bps 50 --owner-slippage-cap-bps 100 --deadline <unix-seconds-within-30-minutes> --max-gas-limit 300000 --max-fee-per-gas 30000000000 --max-priority-fee-per-gas 1000000000 | jq -r .data.quoteHash)
OP=$(apn swap ethereum uniswap prepare --profile <profile> --quote $QUOTE --idempotency-key swap-0001 | jq -r .operation.operationId)
apn swap ethereum uniswap approve --operation $OP
apn swap ethereum uniswap status --operation $OP
  • Every price fact comes from the chain. The quote reads pool slot0 and QuoterV2 at one block, and each contract is pinned to its runtime code hash. Drift fails with uniswap_code_pin_drift.
  • The minimum output is ceil(expected * (10000 - slippageBps) / 10000). A price impact above the owner cap refuses with uniswap_price_impact.
  • Any refusal before the submission marker releases the reservation as failed_before_effect. After the marker, APN never sends again.
  • Run status within about 25 minutes of sending. A pruning public RPC serves the needed balances for only about 128 blocks.

The token-input lane (uniswap-token) supports only canonical USDC to USDT and USDT to USDC through the 0.01% pool. It sends an exact token approval, the swap and, if needed, a zero-allowance cleanup. A reverted or drifted operation enters cleanup_required, and only the foreground cleanup command can send the cleanup. Success proves the exact input debit, the minimum output and zero residual allowance.

How do I swap TRX to USDT with SunSwap on TRON?

The only admitted mechanism is the SunSwap V2 router TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax. The profile's local TRON account must be both --account and --to, and it must be activated. APN_TRON_RPC_URL must be an explicit public HTTPS base with no default. --amount is in SUN (1 TRX = 1,000,000 SUN). --fee-limit-sun is the owner's energy fee limit, and --deadline is at most ten minutes ahead. The whole sequence must finish before the quote deadline.

export APN_TRON_RPC_URL=https://tron-rpc.publicnode.com
apn swap tron sunswap inventory
QUOTE=$(apn swap tron sunswap quote --profile <profile> --account <tron-address> --to <tron-address> --amount 5000000 --slippage-bps 50 --owner-slippage-cap-bps 50 --fee-limit-sun 30000000 --deadline $(( $(date +%s) + 540 )) | jq -r .data.quoteHash)
OP=$(apn swap tron sunswap prepare --profile <profile> --quote $QUOTE --idempotency-key sunswap-0001 | jq -r .operation.operationId)
apn swap tron sunswap approve --operation $OP
apn swap tron sunswap status --operation $OP

Price, expected output and reserves come from the pinned router and pair through wallet/triggerconstantcontract. Each of five pinned contracts is checked by code hash. With a 30 TRX fee_limit, the maximum TRX debit of this example is the 5 TRX input, plus up to 30 TRX of energy, plus the bandwidth budget. A finalized swap needs full-node and solidified history to agree and one USDT Transfer of at least the minimum output to the owner. Keyless TronGrid can throttle bursts with HTTP 429, which fails the quote closed. See TRON.

How do I swap on Solana with Jupiter or Orca?

Both need the profile's local Solana account as payer and recipient. APN_SOLANA_RPC_URL is optional and defaults to the anonymous public endpoint. For Jupiter, --amount is in lamports, and a quote expires 90 seconds after it is made. APN accepts only direct single-step routes through four reviewed Orca Whirlpool SOL/USDC pools, and calls only https://api.jup.ag/swap/v1/quote and /swap-instructions with no key. Jupiter V2 is not used.

apn swap solana jupiter inventory
QUOTE=$(apn swap solana jupiter quote --profile <profile> --account <solana-address> --to <solana-address> --amount 10000000 --slippage-bps 50 --owner-slippage-cap-bps 100 | jq -r .data.quoteHash)
OP=$(apn swap solana jupiter prepare --profile <profile> --quote $QUOTE --idempotency-key jupiter-0001 | jq -r .operation.operationId)
apn swap solana jupiter approve --operation $OP
apn swap solana jupiter status --operation $OP

Orca swaps through two pinned Whirlpools, exact input from token A to token B, using on-chain pool state only. --pool is required. prepare and approve must finish within four minutes of the quote.

apn swap solana orca inventory
QUOTE=$(apn swap solana orca quote --pool sol-usdc --profile <profile> --account <solana-address> --amount 10000000 --slippage-bps 50 --owner-slippage-cap-bps 50 --compute-unit-limit 200000 --compute-unit-price 1000 | jq -r .data.quoteHash)
OP=$(apn swap solana orca prepare --profile <profile> --quote $QUOTE --idempotency-key orca-sol-usdc-0001 | jq -r .operation.operationId)
apn swap solana orca approve --operation $OP
apn swap solana orca status --operation $OP
  • The Orca sol-usdc pool is Czfq3xZZDmsdGdUyrNLtRhGc47cXcZtLG4crryfu44zE. The usdc-usdt pool is 4fuUiYxTQ6QCrdSq9ouBYcTM7bqSwYTSyLueGZLTy4T4. For usdc-usdt, --amount 1000000 is one USDC.
  • APN pins program identities and upgrade authorities, not executable bytes. A different authority refuses with solana_program_authority_changed. Safety rests on the exact-message simulation, the minimum output encoded in the instruction and the finalized receipt checks.
  • Solana finality takes about 13 seconds. Run status until it reports finalized.

What happens if a swap fails or is interrupted?

APN records a submission marker before it signs and sends once. Nothing is signed or sent by status. See recovery.

  • execute continues an approved reservation that has no marker yet. After the marker it only observes.
  • A finalized revert moves the operation to failed_confirmed_revert and releases the reserved input. Only the fee is spent.
  • A lost broadcast answer is unknown_finality. It is observed and never rebroadcast.
  • If the deadline passes without inclusion, status can record expired_unlanded and release the reservation.
  • A finalized swap reports actualEconomics: input, output and fee in the chain's unit.

Questions

Can an AI agent swap on Solana with Jupiter through APN?

Yes. apn swap solana jupiter swaps native SOL for canonical USDC, limited to direct routes through four reviewed Orca Whirlpool pools. The owner must admit both assets on the swap rail.

Does APN swap tokens on Uniswap?

Yes, Uniswap V3 on Ethereum: native ETH to USDC, USDT or WBTC, and USDC to USDT and back. It uses no Uniswap API key.

Which TRON DEX does APN support?

SunSwap V2, for native TRX to canonical USDT only.

Can an agent swap arbitrary token pairs?

No. Each family is finite and pinned, and APN refuses any pair outside these routes.

Sources
  1. uniswap.md: Ethereum swaps
  2. sunswap.md: TRON SunSwap
  3. jupiter.md: Jupiter
  4. orca.md: Orca
  5. allowlist-policy.md: swap rail