End-to-end example: Swap on Base

This walkthrough runs the complete Swaps lifecycle against Base mainnet: set your fee once, quote 100 USDC into WETH, execute the quote from a Turnkey wallet, and poll until the swap settles onchain. Prerequisites

A Pay As You Go, Pro, or Enterprise parent organization
A Turnkey API key pair
A wallet account holding USDC on Base, plus ETH on Base for gas if you don’t sponsor
An EVM wallet account in your parent organization if you want to charge a client fee. Omit the fee configuration to swap with a client fee of 0.

Initialize the client

All requests go through the generic request method of TurnkeyClient, stamped by your API key. Execution confirms asynchronously, so define a polling helper here as well.

import { TurnkeyClient } from "@turnkey/http";
import { ApiKeyStamper } from "@turnkey/api-key-stamper";

const organizationId = "<ORGANIZATION_ID>";

const client = new TurnkeyClient(
  { baseUrl: "https://api.turnkey.com" },
  new ApiKeyStamper({
    apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY,
    apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY,
  }),
);

// Poll swap status until the swap reaches a terminal state.
async function pollSwapStatus(swapRequestId, intervalMs = 1000, timeoutMs = 120000) {
  const startedAt = Date.now();
  while (Date.now() - startedAt < timeoutMs) {
    const res = await client.request("/public/v1/query/get_swap_status", {
      organizationId,
      swapRequestId,
    });
    if (res.status !== "PENDING") return res;
    await new Promise((r) => setTimeout(r, intervalMs));
  }
  throw new Error(`Swap status polling timed out after ${timeoutMs}ms`);
}

Configure your fee

One-time setup on your parent organization: your rate in basis points and the wallet account that collects it. The configuration applies to every swap under the parent organization, and quotes reflect it from this point on; without one, quotes carry a client fee of 0.

await client.request("/public/v1/submit/upsert_swap_config", {
  type: "ACTIVITY_TYPE_UPSERT_SWAP_CONFIG",
  timestampMs: String(Date.now()),
  organizationId: "<PARENT_ORGANIZATION_ID>",
  parameters: {
    feeReceiverWalletAddress: "<FEE_RECEIVER_ADDRESS>",
    feeBps: "50", // 0.5%
  },
});

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/upsert_swap_config \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_UPSERT_SWAP_CONFIG",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<PARENT_ORGANIZATION_ID>",
    "parameters": {
      "feeReceiverWalletAddress": "<FEE_RECEIVER_ADDRESS>",
      "feeBps": "50"
    }
  }'

Request a quote

USDC has 6 decimals, so 100 USDC is "100000000" raw units. Both chains derive from the CAIP-19 identifiers — matching prefixes here (eip155:8453) make this a same-chain swap.

const inputToken = "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC
const outputToken = "eip155:8453/erc20:0x4200000000000000000000000000000000000006"; // WETH
const inputAmount = "100000000"; // 100 USDC

const { activity: quoteActivity } = await client.request(
  "/public/v1/submit/create_swap_quote",
  {
    type: "ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2",
    timestampMs: String(Date.now()),
    organizationId,
    parameters: {
      signWith: "<WALLET_ACCOUNT_ADDRESS>",
      inputToken,
      outputToken,
      inputAmount,
      slippageBps: "50", // 0.5%
    },
  },
);

const { quotes } = quoteActivity.result.createSwapQuoteResult;
const quote = quotes[0];

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/create_swap_quote \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<ORGANIZATION_ID>",
    "parameters": {
      "signWith": "<WALLET_ACCOUNT_ADDRESS>",
      "inputToken": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
      "inputAmount": "100000000",
      "slippageBps": "50"
    }
  }'

Show the user the quote

Quoted amounts are already net of all fees — Turnkey’s and yours — so outputAmount is what the recipient receives. Check expiresAt before executing; an expired quote fails, and a fresh quote is more likely to fill.

console.log(`you receive:  ${quote.outputAmount} raw WETH`);
console.log(`at minimum:   ${quote.minOutputAmount}`);
console.log(`your fee:     ${quote.clientFeeBps} bps`);

if (Number(quote.expiresAt) <= Date.now()) {
  throw new Error("Quote expired — request a new one.");
}

// Without a floor there is no price protection at execution.
if (!quote.minOutputAmount) {
  throw new Error("Quote is missing minOutputAmount — do not execute.");
}

Execute the swap

Execution is pinned to the quote: pass its quoteId and restate the economics the user was shown. Turnkey constructs the transaction, batches any required ERC-20 approval into it, signs with the wallet derived from the quote, and broadcasts. The signer is not resupplied here — it comes from the bound quote.With sponsor: false, the wallet pays its own gas. Set it to true to have Gas Station cover it (requires gas sponsorship enabled for your organization).

const { activity: execActivity } = await client.request(
  "/public/v1/submit/execute_swap",
  {
    type: "ACTIVITY_TYPE_EXECUTE_SWAP_V3",
    timestampMs: String(Date.now()),
    organizationId,
    parameters: {
      quoteId: quote.quoteId,
      inputToken,
      outputToken,
      inputAmount,
      quotedOutputAmount: quote.outputAmount,
      minOutputAmount: quote.minOutputAmount,
      sponsor: false,
    },
  },
);

const { swapRequestId } = execActivity.result.executeSwapResult;

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/execute_swap \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_EXECUTE_SWAP_V3",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<ORGANIZATION_ID>",
    "parameters": {
      "quoteId": "<QUOTE_ID>",
      "inputToken": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
      "inputAmount": "100000000",
      "quotedOutputAmount": "<EXPECTED_OUTPUT>",
      "minOutputAmount": "<MINIMUM_OUTPUT>",
      "sponsor": false
    }
  }'

Poll to settlement

ACTIVITY_STATUS_COMPLETED on the execute activity only means the swap was accepted and enqueued. Poll get_swap_status with the swapRequestId until it reports a terminal state — that’s the only place the actual settled amount appears.

const result = await pollSwapStatus(swapRequestId);

if (result.status === "COMPLETED") {
  // outputAmount can lag the status flip by a few seconds.
  console.log("received:", result.outputAmount ?? "(not yet available)");
  console.log("origin tx:", result.originTxHash);
} else {
  // FAILED — read what the user is left holding.
  console.error(result.error.reason, result.error.message);
  if (result.refund) {
    console.log(`refunded ${result.refund.amount} of ${result.refund.asset}`);
  }
}

This Base example is same-chain, so FAILED is ORIGIN_TRANSACTION_FAILED and has no refund. PROVIDER_FILL_FAILED and refund enrichment apply to cross-chain swaps. See What FAILED means.

Going cross-chain

The same code runs a cross-chain EVM ↔ EVM swap — only the outputToken changes. Give it a different EVM CAIP-2 prefix — say USDC on Arbitrum, eip155:42161/erc20:<USDC_ON_ARBITRUM> — and omit destinationAddress. Asset identifiers come from list_supported_assets. For EVM ↔ SVM, change the output protocol as well — say Solana USDC, solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v — and set destinationAddress on both the quote and the execute to a raw Solana address. Do not pass a wallet account ID, a private key ID, or a CAIP identifier. After broadcast:

The swap stays PENDING past origin-chain inclusion until the destination leg settles, so poll every 5–10 seconds rather than every second.
On COMPLETED, destinationTxHashes carries the destination-chain transactions. swapKind in the response tells you which model applied.
On FAILED, refund fields can arrive after the status flip. Keep polling if refund is absent.

Dive deeper

Swaps overview

— Fee model, chains, routes, and the full API surface.

Enable swaps

— Fee configuration and the fee receiver.

Get a quote

— Quote fields, expiry, and slippage.

Execute a swap

— Gas sponsorship, approvals, and the trust boundary.

Track swap status

— Lifecycle states, failures, and refunds.

Get started

Features

Reference

End-to-end example: Swap on Base

Going cross-chain

Dive deeper

Swaps overview

Enable swaps

Get a quote

Execute a swap

Track swap status

​Going cross-chain

​Dive deeper

Swaps overview

Enable swaps

Get a quote

Execute a swap

Track swap status

Going cross-chain

Dive deeper