Enable Swaps

​

Prerequisites

• You submit the activity against the parent organization. Submissions from sub-organizations will fail.
• You have an EVM wallet account in the parent organization to receive fees, or you omit feeReceiverWalletAddress and let Turnkey generate one. Fees are paid in USDC on Base regardless of which chains your swaps occur on, so a single receiving account covers all swap volume.
• You’ve decided your fee rate in basis points. See Choose your fee configuration.

​

Submit the configuration

• feeReceiverWalletAddress — an EVM wallet account in your parent organization. Private key addresses are not accepted. Optional: if feeBps is a non-empty string and this is omitted, Turnkey auto-generates a parent HD wallet to receive fees. "0" is non-empty and still generates a wallet. To charge no client fee, omit both feeBps and feeReceiverWalletAddress.
• feeBps — your fee in basis points, as a stringified integer (e.g. "50" for 0.5%). Must be between 0% and 5%; values above the cap will fail.
• stableFeeBps — optional; Enterprise plans only. A separate fee applied when both assets are supported stablecoins. Omit to charge feeBps on every swap.

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": "<WALLET_ADDRESS>",
      "feeBps": "50"
    }
  }'

import { TurnkeyClient } from "@turnkey/http";
import { ApiKeyStamper } from "@turnkey/api-key-stamper";
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,
  }),
);
const { activity } = 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: "<WALLET_ADDRESS>",
    feeBps: "50",
  },
});

{
  "activity": {
    "id": "<ACTIVITY_ID>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_UPSERT_SWAP_CONFIG",
    "result": {
      "upsertSwapConfigResult": {
        "feeReceiverWalletAddress": "<WALLET_ADDRESS>",
        "feeBps": "50"
      }
    }
  }
}

​

Choose your fee configuration

• Cap. feeBps and stableFeeBps must not exceed 500 bps; values above the cap will fail.
• Your fee stacks on Turnkey’s. Turnkey’s fee is baked into every quote (see Fees), so the spread your user experiences is Turnkey’s rate plus yours. Quotes always show the net result — outputAmount reflects both.
• Stablepairs are rate-sensitive. Stable-to-stable swaps are economically tight; a fee that’s reasonable on a volatile pair can exceed the entire spread on a stablepair. If you’re on an Enterprise plan, you’re able to configure lower fees for stablepair trades if that makes sense in the context of your app.
• Fee currency and destination. All of your fees accrue in USDC on Base to your configured feeReceiverWalletAddress, regardless of swap chains or assets — one receiving account, one asset, no in-kind fee management. Submit ACTIVITY_TYPE_CLAIM_SWAP_FEES to collect them.

​

Change your fee configuration

​

Next steps

• Get a quote — fee-aware indicative pricing for display and selection
• Execute a swap — the signing activity that runs the swap end-to-end
• Claim swap fees — pay accrued integrator fees to your fee-receiver wallet