Quickstart: Swap tokens across blockchains

This quickstart walks you through how to use the App Kit SDK’s Swap capability to swap tokens across blockchains in a single call. The example swaps 1.00 USDC on Base for native POL delivered to a wallet on Polygon. 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. A kit key is optional—without one, requests run against a rate limit. Configure a kit key 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
- Entity secret
- Kit key (optional): recommended for production or high-volume usage
Created a developer-controlled wallet on Base.
Funded your Base wallet with USDC for the swap amount and ETH for gas.

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-crosschain-circle-wallets
cd app-kit-swap-crosschain-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. If you have a kit key, add it as KIT_KEY—it is optional but recommended for production and high-volume usage to avoid rate limits:

.env

CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
KIT_KEY=YOUR_OPTIONAL_KIT_KEY

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

Step 2. Swap tokens

Create a script that estimates the route, submits the source-chain swap, waits for crosschain delivery, and prints the final swap status.

Unlike same-chain swaps, crosschain swaps return immediately with progress.status: 'PENDING'. The destination-chain leg lands shortly after. Use kit.waitForSwap() to poll until the swap reaches a terminal status: DONE, FAILED, or NOT_FOUND.

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 on Base for native POL delivered to your wallet on Polygon. Replace YOUR_SOURCE_WALLET_ADDRESS with your Base wallet address and YOUR_RECIPIENT_ADDRESS with your Polygon recipient address. The recipient address does not need POL to receive the swapped tokens.

Using other tokens or blockchains? Change the source chain, tokenIn, tokenOut, to.chain, and recipientAddress values in swapParams. Both blockchains must support crosschain swap.

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 recipientAddress = "YOUR_RECIPIENT_ADDRESS";

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

const swapParams: SwapParams = {
  from: {
    adapter,
    chain: "Base",
    address: sourceWalletAddress, // Omit the address if using Viem or Ethers adapters.
  },
  tokenIn: "USDC",
  tokenOut: "NATIVE",
  amountIn: "1",
  to: {
    chain: "Polygon",
    recipientAddress,
  },
  config: {
    kitKey: process.env.KIT_KEY as string, // optional — configure for production or high-volume usage
    allowanceStrategy: "approve",
  },
};

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 });

const status = await kit.waitForSwap({
  result,
  kitKey: process.env.KIT_KEY!,
});

console.dir({ status }, { depth: null, colors: true });

Customize your crosschain swaps to collect a custom fee, or set a slippage tolerance or stop limit.

2.2. Run the script

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

Shell

npm run start

Providers enforce route-specific minimum amounts. If estimateSwap() throws a KitError with code INPUT_AMOUNT_OUT_OF_RANGE, increase amountIn and estimate again (inside a try/catch) before calling swap().

2.3. Verify the transactions

After the script finishes, find the returned status object in the terminal output:

Use the source txHash and chainIn to verify the source-chain swap on the Base block explorer.
Use status.destination.txHash to verify the destination-chain delivery on the Polygon block explorer.

The following is an example of how the estimate, result, and final status might look in the terminal output. Values vary by route, liquidity, and gas price.

{
  estimate: {
    tokenIn: 'USDC',
    tokenOut: 'NATIVE',
    amountIn: '1',
    chainIn: 'Base',
    chainOut: 'Polygon',
    fromAddress: '0xabcd...1234',
    toAddress: '0xabcd...1234',
    stopLimit: { amount: '12.1427586417541', token: 'NATIVE' },
    estimatedOutput: { amount: '12.518307878097', token: 'NATIVE' },
    fees: [
      { token: 'USDC', amount: '0.0002', type: 'provider' },
      { token: 'ETH', amount: '0.000010429566703815', type: 'gas' }
    ]
  }
}

{
  result: {
    tokenIn: 'USDC',
    tokenOut: 'NATIVE',
    chainIn: 'Base',
    chainOut: 'Polygon',
    amountIn: '1.0',
    fromAddress: '0xabcd...1234',
    toAddress: '0xabcd...1234',
    txHash: '0x2f11...025e',
    explorerUrl: 'https://basescan.org/tx/0x2f11...025e',
    fees: [{ token: 'USDC', amount: '0.0002', type: 'provider' }],
    config: { allowanceStrategy: 'approve' },
    progress: { status: 'PENDING' }
  }
}

{
  status: {
    progress: {
      status: 'DONE',
      substatus: 'COMPLETED',
      substatusMessage: 'The transfer is complete.'
    },
    source: {
      txHash: '0x2f11...025e'
    },
    destination: {
      txHash: '0xd824...e331',
      token: {
        symbol: 'POL',
        address: '0x0000000000000000000000000000000000000000'
      },
      amount: '12.534043097347965275'
    }
  }
}

Send

Bridge

Swap

Unified Balance

Quickstart: Swap tokens across blockchains

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 transactions

​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 transactions

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 transactions