Skip to main content
Swaps allow wallets in your organization to exchange tokens through DEX aggregators via a single Turnkey activity, with the usual audit trail and policy controls. Same-chain EVM and Solana routes are supported, as well as EVM ↔ EVM and EVM ↔ SVM cross-chain. You can charge your own fee on every swap and claim it as USDC on Base.

​
What are Swaps

Swaps connect wallets managed using Turnkey to DEX aggregators and liquidity providers through a single interface. Relay is supported today with more options coming soon. A swap is two steps: you request a quote, then execute it. Execution is a signed intent carrying the caller-supplied economics — input and output assets, input amount, quoted and minimum output amounts, and the quote it executes against. Turnkey matches that intent to the bound quote, then constructs the transaction from the quote’s attested execution (including ERC-20 approvals) and submits it for broadcast. You never handle provider quote payloads, transaction calldata, or approval data. The signed intent is the only caller-supplied source of trade economics. Calldata and approvals come from the attested quote. For EVM ↔ SVM, you also set destinationAddress on the quote and execute intents. Turnkey exercises no discretion over token selection, amounts, or order routing. Every swap is a quote, a signed intent, and a poll. Submit ACTIVITY_TYPE_UPSERT_SWAP_CONFIG only if you want to charge a client fee.
If your application presents Swap functionality to end users, you are responsible for disclosing that: (1) swaps are executed through independent third-party decentralized protocols; (2) quoted prices are estimates and actual execution prices may differ; (3) the transaction is subject to fees, including your fee and gas (or network) fees; (4) swaps are subject to slippage, and that failed transactions may still incur gas costs even when the swap does not complete; and (5) for cross-chain swaps, value is moved across networks by third-party bridge providers, which carries additional risk, including loss of funds. Do not claim or imply that swaps are executed by your application or by Turnkey.
Turnkey provides no investment, financial, legal, or tax advice, and does not offer, list, or recommend any asset available through Swaps. Quote data, available assets, and their ordering are not recommendations or solicitations by Turnkey to enter into any transaction. Any advisory, brokerage, or similar service you provide to your end users is yours alone, and you are responsible for any licensing, registration, disclosure, and suitability obligations it carries.Certain digital assets, including, without limitation, tokenized equities, tokenized funds, and other tokenized real-world assets, may be regulated as securities or other financial instruments in some jurisdictions and may be unavailable to some end users. You, and not Turnkey, are responsible for determining on an ongoing basis which assets your end users may lawfully transact with in each jurisdiction you serve, and for restricting access accordingly.

​
How it works

  1. Optionally set your fee. Submit ACTIVITY_TYPE_UPSERT_SWAP_CONFIG on the parent organization to charge a client fee. feeBps sets your rate; feeReceiverWalletAddress must be an EVM wallet account in your parent organization. Private key addresses are not accepted. If feeBps is a non-empty string and no receiver is provided, Turnkey auto-generates a parent HD wallet. "0" is non-empty and still generates a wallet. To charge no client fee, omit both fields. Enterprise organizations can also set a separate stablepair fee (stableFeeBps), applied when both assets in a trade are stablecoins.
  2. Request a quote. Submit ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2 with the signing address, asset pair, input amount, and optional slippage tolerance. For EVM ↔ SVM, also set destinationAddress to a raw address on the output protocol. Each quote returns the output amount net of all fees, a minimum output amount, an expiry, and a quoteId. Quotes reflect your active fee configuration, or a client fee of 0 if you have none.
  3. Execute the swap. Submit ACTIVITY_TYPE_EXECUTE_SWAP_V3 from the organization that owns the swapping wallet — parent or sub-organization — referencing the quoteId and restating the trade parameters, including destinationAddress when the quote set one. Turnkey constructs the transaction from the bound quote, handles ERC-20 approvals, and broadcasts it. For cross-chain routes, this broadcasts the origin-chain transaction, with the cross-chain swap provider broadcasting the destination-chain transaction.
  4. Poll swap status until settlement. Query get_swap_status with the returned swapRequestId until a terminal state. Same-chain swaps are COMPLETED or FAILED from the origin transaction. Cross-chain swaps stay PENDING until the destination leg settles or the provider reports a fill failure. Refund fields on a cross-chain FAILED can arrive after the status flip. See Track swap status.

​
Supported providers, chains, and routes

Route support:
  • 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.
  • Same-chain Solana ↔ Solana — e.g., SOL → USDC on Solana.
  • Cross-protocol EVM ↔ SVM — e.g., Base USDC → Solana USDC. Set destinationAddress on quote and execute.
On the roadmap: additional providers, provider selection, and multiple quote options. Important: Swaps are routed through independent third-party DEX aggregators (currently Relay). These providers are not subcontractors, agents, or affiliates of Turnkey. Turnkey does not control order routing, execution pricing, or liquidity on any protocol. Turnkey’s role is limited to providing the API infrastructure that prepares, signs, and broadcasts swap transactions at the direction of the calling wallet.

​
Fees

Two fees apply to a swap: Turnkey’s fee and, optionally, your own. Both are deducted from the swap output — quoted and minimum output amounts are always net of all fees, so the quote’s outputAmount is what the recipient receives. Your fee is the only one surfaced in the quote, as clientFeeBps; Turnkey’s fee is baked into the quoted amounts and does not appear as a separate field. Turnkey’s fee and your fee are settled as separate claim payouts — they do not appear in the user’s swap transaction itself. With Relay, these are two distinct payouts, one for each party. Regardless of how a provider settles them onchain, the quoted amounts you receive from Turnkey are always net of both.

​
Turnkey’s fee

A stablepair swap is one where both assets carry the stable flag in list_supported_assets.

​
Supported stablecoins

Both assets must appear in the list for their network for a swap to qualify for the stablepair fee tier. Turnkey uses the canonical asset identifiers returned by list_supported_assets, not token symbols alone. Mainnets
This list describes fee classification only. A listed asset does not guarantee that a provider offers a route or sufficient liquidity.
These are Turnkey’s current default fee rates and may be revised on notice in accordance with the Terms. Enterprise rates shown are defaults and are negotiable with an Order Form; where an Order Form sets Turnkey Fee rates, the Order Form controls.

​
Your fee

You can charge your own fee on every swap, expressed in basis points. Your fee options mirror your plan’s rate structure: Pay-as-you-go and Pro organizations set a single feeBps applied to every swap; Enterprise organizations can additionally set stableFeeBps, applied to stablepair swaps. Set your fee and fee receiver via ACTIVITY_TYPE_UPSERT_SWAP_CONFIG:
  • feeBps — your fee in basis points, bounded by a maximum of 5%. Requests above the cap will fail with an error. To charge no client fee, omit both feeBps and feeReceiverWalletAddress. Do not send "0" with an omitted receiver: that combination auto-generates a wallet.
  • feeReceiverWalletAddress — an EVM wallet account in your parent organization. Private key addresses are not accepted. The address is validated at upsert; an address that isn’t a parent-organization EVM wallet account will fail. Fees can only accrue to wallet accounts you generate through Turnkey.
Your fees are paid in USDC on Base, regardless of which chains your swaps occur on. Fees accrue to your fee receiver and are collected via ACTIVITY_TYPE_CLAIM_SWAP_FEES. Fees are configured on the parent organization and apply to every swap submitted by any sub-organization under it. Sub-organizations cannot override the parent’s configuration.
To change your fee configuration, submit upsert_swap_config again with the new values. New quotes requested after the change immediately use the new configuration. Executing an existing quote always settles at the fees baked into that quote — execute does not re-read your fee configuration.

​
API surface

Swaps add four activities: and one query:
Swap requests are stamped and submitted like any other Turnkey request. See Stamps and Submissions. The examples on these pages use cURL and @turnkey/http’s TurnkeyClient, but generated SDK methods are available: createSwapQuote, executeSwap, executeSwapV2, getSwapStatus, upsertSwapConfig, and claimSwapFees.

​
Trust boundary

Swaps never expose executable provider data to you or your users. Provider quote payloads, transaction calldata, and approval payloads are constructed and handled entirely server-side — they are never accepted from callers, so they cannot be tampered with before signing. What the user signs is the execute intent. It is the only caller-supplied source of trade economics: the input and output assets, input amount, quoted and minimum output amounts, sponsorship, the quoteId it executes against, and destinationAddress when the route is cross-protocol. Optional replay-protection fields (evmNonce, recentBlockhash, gasStationNonce) can also be signed; omit them to auto-fetch. Turnkey matches the intent to the bound quote and constructs the transaction from that quote’s attested execution. Fees come from the quote snapshot; execute does not re-read your live configuration. This is why execute restates parameters the quote already carries; the signed intent must be self-contained, so a quote cannot be substituted or its economics altered after signing. Turnkey does not exercise discretion over the selection, routing, or execution of any swap transaction. The user-signed intent determines the trade economics, and the provider determines routing and execution.

​
Next steps

Enable swaps

One-time parent-org setup with fee configuration.

Get a quote

Request executable quotes for an asset pair, net of all fees.

Execute a swap

One signed activity, optionally gas-sponsored.

Track swap status

Poll to settlement across same-chain and cross-chain lifecycles.
Important: Token swaps are executed on third-party decentralized exchange protocols. Turnkey does not control the available liquidity, the routing of a swap across liquidity venues, or the price at which it executes - routing and execution are determined by the third-party aggregator and protocols. Turnkey’s role is limited to constructing, signing, and broadcasting the transaction; selection of the broadcasting node is a technical relay function and does not give Turnkey control over trade routing, liquidity, or execution price. Quoted swap rates are estimates only; actual execution prices may differ due to market volatility, liquidity conditions, slippage, and network congestion. This documentation is provided for informational and technical integration purposes only. Nothing in this documentation constitutes investment, financial, legal, or tax advice, or a recommendation or solicitation to engage in any particular transaction.