How-to: Swap tokens

Swap one token for another from your agent wallet.

Swap tokens from your agent wallet using circle wallet swap. Optionally get a price quote first to verify the expected output before committing funds.

Prerequisites

Before you begin, ensure you have:

• Installed Node.js v20.18.2 or later.

• Installed Circle CLI:

  npm install -g @circle-fin/cli
  

• Completed the Agent Wallets quickstart (authenticates and funds your wallet).

Steps

1. Get a quote (optional)

   Run circle wallet swap with --quote to see the estimated output without executing the swap:

   circle wallet swap EURC 10 USDC --chain BASE --quote
   

   {
     "data": {
       "message": "Quote: 10 EURC → ~9.95 USDC (min 0.000001) on BASE",
       "sellToken": "EURC",
       "sellAmount": "10",
       "buyToken": "USDC",
       "chain": "BASE",
       "estimatedOutput": "9.95",
       "stopLimit": "0.000001"
     }
   }
   
2. Swap tokens

   Run circle wallet swap with your wallet address and a <buyAmount> stop-limit. If the estimated output falls below this value onchain, the swap fails instead of settling at an unfavorable rate:

   circle wallet swap EURC 10 USDC 9.9 --address 0xYourWalletAddress --chain BASE
   

   {
     "data": {
       "message": "Swap complete: 10 EURC → min 9.9 USDC on BASE",
       "sellToken": "EURC",
       "sellAmount": "10",
       "buyToken": "USDC",
       "buyMin": "9.9",
       "chain": "BASE"
     }
   }
   

See the CLI command reference for full syntax and options, including --slippage-bps to set maximum slippage.