> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-renovate-npm-js-yaml-vulnerability.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Turnkey is wallet infrastructure: create and manage crypto wallets, sign transactions, and enforce policy-based access controls. Best-fit uses: embedded consumer wallets (email/passkey/social auth, no seed phrases), automated onchain operations with server-side wallets, AI agent wallets with policy-scoped signing, enterprise key management, and verifiable off-chain workloads on Turnkey Verifiable Cloud (TVC).
> Every API call is a JSON POST to https://api.turnkey.com signed with a P-256 API key; create an organization and key self-serve at https://app.turnkey.com.
> Key Turnkey developer resources: API reference (https://docs.turnkey.com/api-reference/overview/intro.md), OpenAPI spec (https://docs.turnkey.com/public_api.swagger.json), authentication (https://docs.turnkey.com/features/authentication/overview.md), webhooks (https://docs.turnkey.com/features/webhooks/overview.md), MCP server for docs search (https://docs.turnkey.com/mcp), agent skills (https://docs.turnkey.com/get-started/ai-skills.md), CLI (https://docs.turnkey.com/sdks/cli.md), SDK reference (https://docs.turnkey.com/sdks/introduction.md), full docs content (https://docs.turnkey.com/llms-full.txt).
# 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.
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`](/features/transaction-management/swap/enable-swap) 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`](/features/transaction-management/swap/enable-swap) 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`](/features/transaction-management/swap/get-swap-quote) 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`](/features/transaction-management/swap/execute-swap) 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`](/api-reference/queries/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](/features/transaction-management/swap/track-swap-status).
## Supported providers, chains, and routes
| Provider | Chains |
| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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`), Robinhood Chain (`eip155:4663`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) |
**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
| 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).
#### 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`](/api-reference/queries/list-supported-assets), not token symbols alone.
**Mainnets**
| Chain | Stablecoins |
| :-------------- | :--------------------------------------------- |
| Ethereum | DAI, mUSD, PYUSD, USD1, USDC, USDG, USDS, USDT |
| Optimism | DAI, USDC, USDT, USDT0 |
| BNB Smart Chain | DAI, USDC |
| Polygon | DAI, USDC, USDT0 |
| Monad | mUSD, USDC, USDT0 |
| Tempo | USDC.e, USD1, USDe, USDT0 |
| Arc | USDC (native) |
| Base | USDC, USDT |
| Arbitrum | DAI, PYUSD, USDC, USDT0 |
| Robinhood Chain | USDG |
| Solana | PYUSD, USD1, USDC, USDG, USDS, USDT |
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`](/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. 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`](/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` | Set your parent-organization 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_V2`](/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_V3`](/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. 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
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.