> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arc.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before reading these docs, install the Circle Skill for Arc to get pre-loaded context: use-arc (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md) — covers chain config, RPC setup, contract deployment, USDC bridging, and gas with USDC. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills.
> USDC is the gas token. Arc uses USDC for gas fees, not ETH. Configure gas payment in USDC when submitting transactions.
> Read EVM differences before writing Arc code. Arc targets the Osaka EVM baseline. Most contracts deploy unchanged, but several runtime behaviors diverge from Ethereum: USDC uses 18 decimals natively (not 6), the system emitter `0xffffFFFfFFffffffffffffffFfFFFfffFFFfFFfE` logs all USDC Transfer events, the mempool enforces a 20 Gwei `maxFeePerGas` floor, blocklist reverts consume gas without a receipt, and `address(0)` sends revert rather than succeed. https://docs.arc.io/arc/references/evm-differences.md is the canonical reference for all Arc-specific runtime behaviors. Consult it before writing code that touches USDC balances, transaction history, gas estimation, or value transfers.
> Sub-second finality. Transactions are final in under 1 second. No need to wait for multiple block confirmations.
> Use App Kits for multichain payment and liquidity capabilities. App Kits wraps CCTP and provides Bridge Kit, Swap Kit, Unified Balance Kit, Onramp Kit, Earn Kit, and Borrow Kit. Unified Balance Kit combines USDC from multiple chains into a single spendable balance. Earn Kit integrates earn opportunities into your app. Borrow Kit lets users borrow USDC against cirBTC collateral on Arc.
> Use Arc Foundry for contract development. Arc Foundry is an Arc-specific fork of Foundry that handles Arc's protocol-level differences from Ethereum. It provides arc-forge, arc-cast, and arc-anvil. Install it before deploying contracts: https://docs.arc.io/arc/tutorials/install-arc-foundry.md.
> Arc is available on both Testnet and Mainnet. See https://docs.arc.io/arc/references/connect-to-arc.md for RPC endpoints and https://faucet.circle.com for testnet tokens.
> Always check Contract Addresses: https://docs.arc.io/arc/references/contract-addresses.md
> Building beyond Arc? Circle offers skills for the full platform: use-usdc (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md), use-circle-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md), use-developer-controlled-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md), use-user-controlled-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md), use-modular-wallets (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md), use-gateway (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md), use-smart-contract-platform (https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md). Full Circle developer docs: https://developers.circle.com/llms.txt.

# Quickstart: Swap tokens across blockchains

> Use the App Kit SDK to swap one token on the source blockchain and receive a different token on a destination blockchain in a single call

export const TryOnArcStudio = () => {
  const [copied, setCopied] = useState(false);
  const [prompt, setPrompt] = useState("");
  useEffect(() => {
    const url = `https://docs.arc.io${window.location.pathname}.md`;
    setPrompt(`Read the guide at ${url}, implement it in a new project, then run it and show me how it works.`);
  }, []);
  const arcStudioUrl = `https://studio.arc.io/app?prompt=${encodeURIComponent(prompt)}`;
  const handleArcStudioClick = () => {
    try {
      if (typeof navigator !== "undefined" && navigator.clipboard && prompt) {
        navigator.clipboard.writeText(prompt).then(() => {
          setCopied(true);
          setTimeout(() => setCopied(false), 4000);
        }, () => {});
      }
    } catch (e) {}
  };
  return <div className="not-prose mb-6">
      <span className="relative inline-flex">
        <a href={arcStudioUrl} target="_blank" rel="noreferrer" onClick={handleArcStudioClick} aria-label="Try it on Arc Studio (opens in new tab)" className="inline-flex items-center gap-2 px-4 py-2 rounded-lg bg-[#3E74BB] border border-[#3E74BB] text-sm font-medium text-white no-underline hover:bg-[#345f9c] hover:border-[#345f9c] transition-all">
          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
            <path d="M13 2 3 14h9l-1 8 10-12h-9l1-8z" />
          </svg>
          Try it on Arc Studio
        </a>
        {copied && <span role="status" aria-live="polite" className="absolute left-0 top-full mt-2 w-72 text-sm text-gray-500 dark:text-[#888]">
            Opening Arc Studio — prompt copied to your clipboard in case you need to
            sign in first.
          </span>}
      </span>
    </div>;
};

export const CircleWalletsProjectSetup = ({projectName, extraPackages = ""}) => <></>;

<TryOnArcStudio />

This quickstart walks you through how to use the App Kit SDK's
[Swap](/app-kit/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](/app-kit/references/supported-blockchains).
Passing an API key to Swap is optional—without one, swap requests run against a
rate limit. Add one from the
[Circle Console](https://console.circle.com/api-keys) if you hit rate limit
errors or expect high request volume.

<Note>
  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`.
</Note>

## Prerequisites

Before you begin, ensure that you've:

* Installed [Node.js v22+](https://nodejs.org/).
* Obtained the following from the [Circle Console](https://console.circle.com/):
  * [API key](https://developers.circle.com/contracts/create-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](https://console.circle.com/wallets/dev/configurator/entity-secret)
    or the
    [SDK](https://developers.circle.com/wallets/dev-controlled/register-entity-secret#create-an-entity-secret-using-the-sdk)
* 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:

```bash Shell theme={null}
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
```

<Tip>
  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](/app-kit/tutorials/adapter-setups).
</Tip>

### 1.2. Configure TypeScript (optional)

<Info>
  This step is optional. It helps prevent missing types in your IDE or editor.
</Info>

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

```bash Shell theme={null}
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:

```bash Shell theme={null}
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:

```text .env theme={null}
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
```

<Tip>
  Edit `.env` files in your IDE or editor so credentials are not leaked to your
  shell history.
</Tip>

## 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.

<Note>
  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`.
</Note>

### 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.

<Info>
  Using other [tokens](/app-kit/references/supported-blockchains#supported-tokens)
  or [blockchains](/app-kit/references/supported-blockchains)? Change the source
  `chain`, `tokenIn`, `tokenOut`, `to.chain`, and `recipientAddress` values in
  `swapParams`. Both blockchains must support crosschain swap.
</Info>

```typescript TypeScript theme={null}
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: {
    apiKey: process.env.CIRCLE_API_KEY as string, // optional for swaps; recommended 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,
  apiKey: process.env.CIRCLE_API_KEY!,
});

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

<Tip>
  Customize your crosschain swaps to
  [collect a custom fee](/app-kit/tutorials/swap/collect-swap-fee), or set a
  [slippage tolerance or stop limit](/app-kit/tutorials/swap/set-slippage-tolerance-or-stop-limit).
</Tip>

### 2.2. Run the script

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

```bash Shell theme={null}
npm run start
```

<Note>
  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()`.
</Note>

### 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.

<CodeGroup>
  ```shell Estimate theme={null}
  {
    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' }
      ]
    }
  }
  ```

  ```shell Result theme={null}
  {
    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' }
    }
  }
  ```

  ```shell Final status theme={null}
  {
    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'
      }
    }
  }
  ```
</CodeGroup>