Enable Swaps

ACTIVITY_TYPE_UPSERT_SWAP_CONFIG is a parent-organization configuration activity that writes FEATURE_NAME_SWAP_CONFIG — the source of truth for your integrator fee configuration and the wallet that receives fees. This config must be set before any sub-organization can call get_swap_quote or execute_swap.

Prerequisites

The activity is submitted against the parent organization. Sub-organization requests are rejected.
You control a wallet that will receive integrator fees. It must be a valid address for the target route and provider (To Confirm — likely any EVM address in V1).
You’ve decided on your fee rate in basis points. See Choose your fee configuration.

Submit upsert_swap_config

enum<string>

required

ACTIVITY_TYPE_UPSERT_SWAP_CONFIG

string

required

Timestamp (in milliseconds) of the request, used to verify liveness.

string

required

Unique identifier of the parent organization. Requests from sub-organizations are rejected.

string

required

The wallet address that receives integrator fees on-chain. Must be valid for the route and provider (To Confirm — likely any EVM address in V1).

string

required

Your integrator fee in basis points, expressed as a stringified integer. For example, "50" = 0.5%. Must be non-negative and no greater than the Turnkey-defined maximum.

string

Optional. A separate integrator fee in basis points applied to stablecoin-to-stablecoin swaps (To Confirm — verify this is the exact scope).

string

Optional. The DEX aggregator provider. Omit in V1 — 0x is the only supported provider and is used by default.

cURL

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"
    }
  }'

JavaScript

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

upsert_swap_config completes inline. The activity result echoes the applied configuration:

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

(Response shape To Confirm — assumes enableSwapResult.config echoes the applied configuration for confirmation.)

Choose your fee configuration

Your feeBps applies to every swap submitted under any sub-organization of your parent org. Two constraints to keep in mind:

Cap: Turnkey enforces a maximum feeBps. Requests above the cap are rejected. The current maximum is documented in the API reference and may be adjusted over time (To Confirm — current cap value).
Fee currency: fees accrue on-chain to feeReceiverWalletAddress in the token that the swap route settles the fee in (To Confirm — 0x currently collects the integrator fee in the sell token; document once verified).

Pick a feeBps that reflects your intended margin and confirm the receiver wallet is one you actively control. Fees paid to a wallet you don’t control cannot be recovered by Turnkey.

Change your fee configuration

Configuration changes go through the same ACTIVITY_TYPE_UPSERT_SWAP_CONFIG activity — submit again with the updated feeBps, feeReceiverWalletAddress, or stableFeeBps. There is no separate update activity. Quote and execute activities submitted after the change immediately use the new configuration. Because executable provider data is fetched fresh during execute_swap, an in-flight quote followed by an execute will settle at the fee configuration active at execute time, not at quote time (To Confirm). To disable swaps entirely, submit enable_swap with enabled: false.

Disabling swaps rejects all subsequent get_swap_quote and execute_swap requests until re-enabled. Wallets are unaffected — nothing on-chain changes.

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

Get started

Features

Reference

Prerequisites

Submit upsert_swap_config

Choose your fee configuration

Change your fee configuration

Next steps

​Prerequisites

​Submit upsert_swap_config

​Choose your fee configuration

​Change your fee configuration

​Next steps

Prerequisites

Submit upsert_swap_config

Choose your fee configuration

Change your fee configuration

Next steps