Skip to main content
Swaps are in early access. Contact us to enable it for your organization.
Swaps allow wallets in your organization exchange tokens through DEX aggregators via a single Turnkey activity, with the usual audit trail and policy controls. Same-chain and EVM ↔ EVM cross-chain routes are supported. You can take an integrator fee on every swap, paid on-chain to a wallet you control.

​
What are Swaps

Swaps connects Turnkey wallets to DEX aggregators through a unified interface. 0x is supported today; additional providers are on the roadmap. Callers submit signed intents describing what they want to swap while Turnkey handles quote fetching, transaction construction, ERC-20 approvals via Permit2, and broadcast. Callers never see provider quote payloads, transaction calldata, or approval data. Swaps enablement is a one-time setup step per parent organization. After that, each swap is a signed intent and a poll.

​
How it works

  1. Enable swaps once on your parent organization via upsert_swap_config, setting your integrator fee (bps) and fee-receiver wallet.
  2. Optionally call get_swap_quote for an indicative quote to display to users. Quotes reflect your active fee configuration.
  3. Submit execute_swap from the sub-organization whose wallet is swapping. Turnkey handles quote refresh, Permit2 approvals, and transaction construction internally. For cross-chain routes, the origin-chain transaction is broadcast here.
  4. Poll swap status until settlement. Same-chain swaps complete on origin inclusion; cross-chain swaps have a longer lifecycle that continues until the destination-chain leg settles or funds are recovered. See Track swap status.

​
Supported providers, chains, and routes

Route support in V1:
  • Same-chain EVM ↔ EVM — e.g., USDC → USDT on Base.
  • Cross-chain EVM ↔ EVM — e.g., Arbitrum USDC → Base USDC, where supported by the provider.
On the roadmap: Solana ↔ Solana, EVM ↔ SVM (e.g., Ethereum ↔ Solana), additional providers, provider selection, and multiple quote options.

​
Fees

Swap fees are integrator fees: a percentage of the swap amount, expressed in basis points, applied to quote amounts and collected onchain during execution.
  • Your integrator fee: set via (feeBps), along with the payout wallet (feeReceiverWalletAddress, a wallet address you control). Fees accrue onchain to that wallet.
  • Cap: feeBps is bounded by a Turnkey-controlled maximum threshold. Requests above the cap are rejected.
Fees are configured on the parent organization and applied to every swap submitted by any sub-organization under it. Sub-organizations cannot override the parent’s fee configuration.
To change your fee configuration, submit upsert_swap_config again with the new values. Quote and execute activities submitted after the change immediately use the new fee configuration.

​
API surface

Swaps add three activities: and two queries:
Swap requests are stamped and submitted like any other Turnkey request. See Stamps and Submissions. There are no Swap-specific SDK methods during the early access period, so the examples on these pages use cURL and the generic request method of @turnkey/http’s TurnkeyClient.

​
Trust boundary

Swap intentionally does not expose executable provider data to API callers. The user-signed ExecuteSwapIntent is the source of truth for inputToken, outputToken, inputAmount, walletAccount, sponsor, and slippage. Fee configuration, provider quote payloads, transaction calldata, Permit2 signatures, and approval payloads are all handled server-side and never accepted from callers. Policy engines evaluate the derived on-chain transaction, not the swap intent — so existing wallet policies apply to the resulting transfer behavior.

​
Explore

Enable swaps

One-time parent-org setup with fee configuration.

Get a quote

Indicative fee-aware quote for display.

Execute a swap

One activity, optionally gas-sponsored.

Track swap status

Same-chain and cross-chain lifecycle.