Skip to main content
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, but you can use other supported tokens or blockchains.

​
Prerequisites

Before you begin, ensure that you have:

​
Step 1. Set up the project

​
1.1. Create the project and install dependencies

Create a new directory and install the App Kit SDK with the Circle Wallets adapter and supporting tools: 
# Set up your directory and initialize a Node.js project
mkdir app-kit-swap-circle-wallets
cd app-kit-swap-circle-wallets
npm init -y
npm pkg set type=module

# Set up module type and start command
npm pkg set scripts.start="tsx --env-file=.env index.ts"

# Install runtime dependencies
npm install @circle-fin/app-kit @circle-fin/adapter-circle-wallets tsx

# Install dev dependencies
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:
Shell
npx tsc --init
Then, update the tsconfig.json file:
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, YOUR_ENTITY_SECRET with your entity secret, and YOUR_KIT_KEY with your kit key from the Circle Console:
.env
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
KIT_KEY=YOUR_KIT_KEY
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 Developer Console or the list wallets endpoint:
Using another token pair or blockchain? Change the tokenIn, tokenOut, and chain values in kit.swap() 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: {
    kitKey: process.env.KIT_KEY!,
  },
};

const estimate = await kit.estimateSwap(swapParams);
const result = await kit.swap(swapParams);

console.dir({ estimate, 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

​
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 result of a successful swap might look in the terminal output.
Terminal output
{
  estimate: {
    tokenIn: 'USDC',
    tokenOut: 'EURC',
    amountIn: '1.00',
    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',
    chain: 'Arc_Testnet',
    amountIn: '1.0',
    amountOut: '0.989589',
    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' }]
  }
}