> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turnkey.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Execute token swaps from wallets you manage with Turnkey through a unified interface over independent third-party DEX aggregators, and take your own fee on every swap, paid onchain.
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 cross-chain. You can charge your own fee on every swap, collected onchain to a wallet you control.
Swaps is currently an Early Access Product. [Contact us](https://www.turnkey.com/contact-us) to enable it for your organization.
## 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 full trade parameters — input and output assets, input amount, quoted and minimum output amounts, and the quote it executes against. From that intent, Turnkey constructs the transaction (we handle ERC-20 token approvals for you as part of this) and submits it for broadcast. You never handle provider quote payloads, transaction calldata, or approval data. Your signed intent is the sole source of trade parameters. Turnkey exercises no discretion over token selection, amounts, or order routing.
Enabling Swaps is a one-time setup step per parent organization. After that, every swap is a quote, a signed intent, and a poll.
If your application presents Swap functionality to end users, you should clearly disclose that: (1) swaps are executed through independent third-party decentralized protocols; (2) quoted prices are estimates and actual execution prices may differ; (3) all fees applicable to the transaction, including your fee and gas (or network) fees; (4) the risks of slippage, including that failed transactions may still incur gas costs; (5) for cross-chain swaps, value is moved across networks by third-party bridge providers, which carries additional risk, including loss of funds, and (6) nothing constitutes investment, financial, legal, or tax advice or a recommendation or solicitation. Do not claim or imply that swaps are executed by your application or by Turnkey.
## How it works
1. **Swaps are enabled once per parent organization.** Once enabled, submit [`ACTIVITY_TYPE_UPSERT_SWAP_CONFIG`](/features/transaction-management/swap/enable-swap) to configure your fee. `feeBps` sets your rate; `feeReceiverWalletAddress` sets the receiving address, which must be an EVM wallet account in your parent organization. If `feeBps` is set and no receiver is provided, Turnkey auto-generates one in your parent organization — solely controlled by your parent org — to receive fees. Setting `feeBps` to 0 with no receiver is valid if you don't want to charge a fee. 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`](/features/transaction-management/swap/get-swap-quote) with the signing address, asset pair, input amount, and slippage tolerance. 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.
3. **Execute the swap.** Submit [`ACTIVITY_TYPE_EXECUTE_SWAP_V2`](/features/transaction-management/swap/execute-swap) from the sub-organization whose wallet is swapping, referencing the `quoteId` and restating the trade parameters. Turnkey constructs the transaction, handles ERC-20 approvals, and broadcasts it. For cross-chain routes, this broadcasts the origin-chain transaction, with the cross chain swap provider (Relay) broadcasting the destination-chain transaction.
4. **Poll swap status until settlement.** Query [`get_swap_status`](/api-reference/queries/get-swap-status) with the returned `swapRequestId` until a terminal state. Same-chain swaps are `COMPLETED` on origin-chain inclusion; cross-chain swaps stay `PENDING` until the destination leg settles or funds are refunded. See [Track swap status](/features/transaction-management/swap/track-swap-status).
## Supported providers, chains, and routes
| Provider | Chains (V1) |
| :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Relay | Ethereum (`eip155:1`), Base (`eip155:8453`), Optimism (`eip155:10`), Arbitrum (`eip155:42161`), Polygon (`eip155:137`), BNB Chain (`eip155:56`), Monad (`eip155:143`), Tempo (`eip155:4217`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) |
**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.
* **Same-chain Solana ↔ Solana** — e.g., SOL → USDC on Solana.
**On the roadmap:** EVM ↔ SVM (e.g., Ethereum ↔ Solana), 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 on behalf 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
| Plan | Standard swaps | Stablepair swaps |
| :-------------------- | :------------- | :--------------- |
| Pay-as-you-go and Pro | 20 bps | 20 bps |
| Enterprise | 20 bps | 10 bps |
A stablepair swap is one where both assets carry the `stable` flag in [`list_supported_assets`](/api-reference/queries/list-supported-assets).
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`](/features/transaction-management/swap/enable-swap):
* `feeBps` — your fee in basis points, bounded by a maximum of 5%. Requests above the cap will fail with an error.
* `feeReceiverWalletAddress` — an EVM wallet account in your parent organization. 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`](/api-reference/activities/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:
| Activity | Endpoint | Purpose |
| :--------------------------------------------------------------------------------- | :------------------------------------------ | :---------------------------------------------------------------------- |
| [`ACTIVITY_TYPE_UPSERT_SWAP_CONFIG`](/api-reference/activities/upsert-swap-config) | `POST /public/v1/submit/upsert_swap_config` | Enable swaps on your parent organization and set your fee configuration |
| [`ACTIVITY_TYPE_CLAIM_SWAP_FEES`](/api-reference/activities/claim-swap-fees) | `POST /public/v1/submit/claim_swap_fees` | Claim accrued integrator fees to your fee-receiver wallet |
| [`ACTIVITY_TYPE_CREATE_SWAP_QUOTE`](/api-reference/activities/get-swap-quote) | `POST /public/v1/submit/create_swap_quote` | Request an executable quote for a token pair |
| [`ACTIVITY_TYPE_EXECUTE_SWAP_V2`](/api-reference/activities/execute-swap) | `POST /public/v1/submit/execute_swap` | Execute the quoted swap identified by `quote_id` |
and one query:
| Query | Endpoint | Purpose |
| :------------------------------------------------------ | :-------------------------------------- | :---------------------------------------------------------------------------------------------- |
| [`Swap status`](/api-reference/queries/get-swap-status) | `POST /public/v1/query/get_swap_status` | Poll the full swap lifecycle. Handles same-chain and cross-chain with a unified response shape. |
Swap requests are stamped and submitted like any other Turnkey request. See [Stamps](/api-reference/overview/stamps) and [Submissions](/api-reference/activities/overview). The examples on these pages use cURL and [`@turnkey/http`](https://www.npmjs.com/package/@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, and it is the sole source of trade parameters: the input and output assets, input amount, quoted and minimum output amounts, sponsorship, and the `quoteId` it executes against. Turnkey constructs the transaction deterministically from that intent. 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 parameters, and the provider determines routing and execution.
## Next steps
One-time parent-org setup with fee configuration.
Request executable quotes for an asset pair, net of all fees.
One signed activity, optionally gas-sponsored.
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.