Quickstart: Swap tokens on a blockchain

This quickstart walks you through how to use the App Kit SDK’s Swap capability to swap tokens on the same blockchain. The example swaps USDC for EURC on Arc Testnet with the Circle Wallets adapter. Swap is intended for server-side applications and is not specific to Circle Wallets; you can use any compatible EVM adapter with supported tokens or blockchains. Passing an API key to Swap is optional—without one, swap requests run against a rate limit. Add one from the Circle Console if you hit rate limit errors or expect high request volume.

If your Circle Wallet is a smart contract account (SCA), set allowanceStrategy: "approve". USDC permit signatures use ecrecover, which does not accept the SCA’s ERC-1271 signature, so the SDK uses an onchain approve.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22+.
Obtained the following from the Circle Console:
- API key: required for wallet operations, and optionally used to authenticate Swap requests (recommended for production or high-volume usage)
- Entity secret: generated and registered using the Circle Console or the SDK
Created a developer-controlled wallet on Arc Testnet.
Funded your Arc Testnet wallet with enough testnet USDC for the swap amount and transaction fees from the Circle Faucet.

Step 1. Set up the project

1.1. Create the project and install dependencies

Create a project directory, initialize a Node.js project with an ES module type and start script, then install runtime and dev dependencies:

Shell

mkdir app-kit-swap-same-chain-circle-wallets
cd app-kit-swap-same-chain-circle-wallets
npm init -y
npm pkg set type=module
npm pkg set scripts.start="tsx --env-file=.env index.ts"
npm install @circle-fin/app-kit @circle-fin/adapter-circle-wallets tsx {extraPackages}
npm install --save-dev typescript @types/node

Only need to swap and want a lighter install than the full App Kit SDK? Install the standalone Swap Kit instead: @circle-fin/swap-kit.For server-side scripts, you can use any compatible EVM adapter, including the private key adapter. Keep private keys on the server and configure the adapter in the wallet adapter setup guide.

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file configured for ESM and Node:

Shell

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

1.3. Set environment variables

Create an .env file in the project directory:

Shell

touch .env

Add your server-side credentials. Replace YOUR_API_KEY with your Circle Developer API key and YOUR_ENTITY_SECRET with your entity secret. The same API key authenticates both the wallet operations and the swap request:

.env

CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET

Edit .env files in your IDE or editor so credentials are not leaked to your shell history.

Step 2. Swap tokens

2.1. Create the script

Create an index.ts file in the project directory and add the following code. This code swaps 1.00 USDC for EURC from your Circle Wallets-controlled Arc Testnet wallet. Replace YOUR_SOURCE_WALLET_ADDRESS with the wallet address from the Circle Console or the list wallets endpoint:

Using another token pair or blockchain? Change the tokenIn, tokenOut, and chain values in swapParams and ensure the source wallet has enough input tokens and gas.

TypeScript

import { AppKit } from "@circle-fin/app-kit";
import { createCircleWalletsAdapter } from "@circle-fin/adapter-circle-wallets";
import type { SwapParams } from "@circle-fin/app-kit";

const kit = new AppKit();

const sourceWalletAddress = "YOUR_SOURCE_WALLET_ADDRESS";

const adapter = createCircleWalletsAdapter({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

const swapParams: SwapParams = {
  from: {
    adapter,
    chain: "Arc_Testnet",
    address: sourceWalletAddress, // Omit the address if using Viem or Ethers adapters.
  },
  tokenIn: "USDC",
  tokenOut: "EURC",
  amountIn: "1.00",
  config: {
    apiKey: process.env.CIRCLE_API_KEY as string, // optional for swaps; recommended for production or high-volume usage
  },
};

const estimate = await kit.estimateSwap(swapParams);
console.dir({ estimate }, { depth: null, colors: true });

const result = await kit.swap(swapParams);
console.dir({ result }, { depth: null, colors: true });

Customize your swaps to collect a custom fee, set a slippage tolerance or stop limit, or get a pre-swap estimate.

2.2. Run the script

Save the index.ts file and run the script in your terminal:

Shell

npm run start

Arc Testnet swap liquidity can be unstable. If a simulation reverts or a quote looks far from the expected rate, the testnet pool may be imbalanced or low on liquidity. Mainnet pools are typically deeper, but execution still depends on pool conditions, trade size, and slippage.

2.3. Verify the transaction

After the script finishes, inspect the returned result in the terminal output. Use the transaction explorer URL to verify the swap transaction and confirm the output amount. The following is an example of how the estimate and result of a successful swap might look in the terminal output.

{
  estimate: {
    tokenIn: 'USDC',
    tokenOut: 'EURC',
    amountIn: '1.00',
    chainIn: 'Arc_Testnet',
    chainOut: 'Arc_Testnet',
    chain: 'Arc_Testnet',
    fromAddress: '0xabcd...1234',
    toAddress: '0xabcd...1234',
    stopLimit: { amount: '0.959901', token: 'EURC' },
    estimatedOutput: { amount: '0.989589', token: 'EURC' },
    fees: [
      { token: 'USDC', amount: '0.0002', type: 'provider' },
      { token: 'USDC', amount: '0.021106828371967574', type: 'gas' }
    ]
  }
}

{
  result: {
    tokenIn: 'USDC',
    tokenOut: 'EURC',
    chainIn: 'Arc_Testnet',
    chainOut: 'Arc_Testnet',
    amountIn: '1.0',
    fromAddress: '0xabcd...1234',
    toAddress: '0xabcd...1234',
    txHash: '0x43cb...c801',
    explorerUrl: 'https://testnet.arcscan.app/tx/0x43cb...c801',
    fees: [{ token: 'USDC', amount: '0.0002', type: 'provider' }],
    progress: {
      status: 'DONE',
      substatus: 'COMPLETED',
      substatusMessage: 'The transfer is complete.'
    },
    amountOut: '0.989589',
  }
}

Send

Bridge

Swap

Unified Balance

Quickstart: Swap tokens on a blockchain

Prerequisites

Step 1. Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Swap tokens

2.1. Create the script

2.2. Run the script

2.3. Verify the transaction

​Prerequisites

​Step 1. Set up the project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​1.3. Set environment variables

​Step 2. Swap tokens

​2.1. Create the script

​2.2. Run the script

​2.3. Verify the transaction

Prerequisites

Step 1. Set up the project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

1.3. Set environment variables

Step 2. Swap tokens

2.1. Create the script

2.2. Run the script

2.3. Verify the transaction