Execute a Swap

ACTIVITY_TYPE_EXECUTE_SWAP_V3 runs a swap end-to-end against a quote from ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2. You sign an execute intent carrying the quote’s economics — the quoteId, amounts, minimum output, and destinationAddress when the route is EVM ↔ SVM. Turnkey matches that intent to the bound quote, then constructs the transaction from the quote’s attested execution (including any required ERC-20 approvals), signs it with the wallet derived from the bound quote inside a secure enclave, and broadcasts it. You never construct, see, or sign raw calldata; the intent is the only thing you sign.

Prerequisites

A swap configuration is not required; without one, the quote already carries a client fee of 0. See Enable Swaps.
You are using an unexpired quote from ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2.
The address the quote was created for holds enough of the input asset to cover inputAmount. For non-sponsored swaps it also needs the origin chain’s native asset for gas; if sponsor: true, your organization can sponsor the gas for the user’s trade. To use the sponsored path gas sponsorship must be enabled for your organization.
For cross-chain or EVM ↔ SVM routes, the destination chain is supported by the provider. See Supported providers, chains, and routes.
For EVM ↔ SVM, the quote and execute intents both set destinationAddress to the same raw output-protocol address.

Submit the swap

string

required

The quote to execute, from ACTIVITY_TYPE_CREATE_SWAP_QUOTE_V2. Execution is pinned to this quote’s pricing and provider. Must be unexpired.

string

required

CAIP-19 identifiers for the assets being sold and bought, matching the quoted pair. The origin chain derives from inputToken; a differing CAIP-2 prefix on outputToken makes the route cross-chain.

string

required

In raw onchain units, matching the quoted amount.

string

required

The quote’s expected output, in raw onchain units. Informational in settlement but part of the signed intent: the user signs the economics they were shown.

string

required

The quote’s floor, in raw onchain units. Enforced at execution time — if the swap would return less, it fails rather than filling worse.

Required. When true, your organization sponsors gas for the transaction; requires gas sponsorship to be enabled for your organization. Set to false to have the swapping wallet pay its own gas.

string

Required for EVM ↔ SVM. Must match the quote: a raw public address on the output token protocol. Omit it for same-protocol routes. Wallet account IDs, private key IDs, and CAIP identifiers are not accepted.

cURL:

cURL

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/execute_swap \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_EXECUTE_SWAP_V3",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<ORGANIZATION_ID>",
    "parameters": {
      "quoteId": "<QUOTE_ID>",
      "inputToken": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
      "inputAmount": "1000000",
      "quotedOutputAmount": "<EXPECTED_OUTPUT>",
      "minOutputAmount": "<MINIMUM_OUTPUT>",
      "sponsor": false
    }
  }'

JavaScript:

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/execute_swap", {
  type: "ACTIVITY_TYPE_EXECUTE_SWAP_V3",
  timestampMs: String(Date.now()),
  organizationId: "<ORGANIZATION_ID>",
  parameters: {
    quoteId: "<QUOTE_ID>",
    inputToken: "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    outputToken: "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
    inputAmount: "1000000",
    quotedOutputAmount: "<EXPECTED_OUTPUT>",
    minOutputAmount: "<MINIMUM_OUTPUT>",
    sponsor: false,
  },
});

The activity result returns a poll handle:

{
  "activity": {
    "id": "<ACTIVITY_ID>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_EXECUTE_SWAP_V3",
    "result": {
      "executeSwapResult": {
        "swapRequestId": "sha256:9a80031c2def40d9294900fb99be914999cea3dbe9a4dd4841a8e52ee29f09f5",
        "provider": "relay",
        "quoteId": "<QUOTE_ID>"
      }
    }
  }
}

ExecuteSwapResult returns swapRequestId (used to poll status), plus optional provider and quoteId.

Gas: sponsored vs. self-funded

With sponsor: true, Gas Station pays the gas and the swapping wallet account needs no native asset at all — approvals and the swap execute in one sponsored batch. Gas sponsorship must be enabled for your organization; sponsored gas accrues to your monthly gas bill and counts toward your spend limits. With sponsor: false, the wallet account performing the swap pays its own gas. The wallet account must be funded with a sufficient amount of the origin chain’s gas asset before executing.

Gas Sponsorship is available on Enterprise plans. Enterprise: Unlimited spend, with configurable time windows. Pay-as-you-go and Pro customers can still access transaction construction, signing, and broadcast. If you’d like to leverage gas sponsorship, please reach out!

What is abstracted away

The signed intent carries only the swap parameters listed above. Everything else is handled by Turnkey:

Provider quote payloads
Transaction calldata and serialized transactions
Token approval signatures and payloads
Fee configuration — rates and the fee receiver are snapshotted into the quote at quote time; execute does not re-read your live configuration, and you cannot override fees per swap

Execute only accepts the bound quote terms. You do not pass provider payloads, calldata, or fee overrides. Because none of these inputs exist in the execute intent, none of them can be tampered with before signing. Optional replay-protection fields (evmNonce, recentBlockhash, gasStationNonce) can be set on the intent; omit them to auto-fetch. See Trust boundary for the full model.

Approvals

For ERC-20 inputs, Turnkey batches any required token approval into the swap transaction — there is no separate approval activity to run, no standing allowance to manage, and no second signature from your user. Approvals are handled automatically as part of execution. Native token swaps (e.g., ETH as inputToken) do not require an approval step.

Some non-standard ERC-20 tokens may not be compatible with the batched approval flow. If a swap fails with an approval-related error, verify the token supports standard ERC-20 approval mechanics before retrying.

Same-chain vs. cross-chain execution

The execute activity is the same for same-chain, cross-chain, and EVM ↔ SVM routes — the route is fixed by the quote you reference. For EVM ↔ SVM, restating destinationAddress is required. The difference after broadcast:

Same-chain swaps reach a terminal status from the origin transaction: COMPLETED with the settled outputAmount, or FAILED with ORIGIN_TRANSACTION_FAILED. Same-chain status does not return refund or PROVIDER_FILL_FAILED.
Cross-chain swaps stay PENDING past origin inclusion until the destination leg settles (COMPLETED, with destinationTxHashes) or the provider reports a fill failure (FAILED). The refund object can be absent when FAILED first appears.

In both cases, poll get_swap_status with the swapRequestId returned by the execute activity. See Track swap status for terminal states and error handling.

Poll swap status

A successful execute activity returns an ID which you will use to track the status of the swap:

{
  "provider": "relay",
  "quoteId": "sq_v1_d47bcb2192150649280454baa8a48f1cf4b1e5270997901436c2d907eecca6ac",
  "swapRequestId": "sha256:9a80031c2def40d9294900fb99be914999cea3dbe9a4dd4841a8e52ee29f09f5"
}

swapRequestId — the handle for polling. Pass it to get_swap_status.
quoteId / provider — echoed for correlation with the quote you executed.

ACTIVITY_STATUS_COMPLETED on the execute activity means the swap was accepted and enqueued for broadcast. It does not mean the transaction landed onchain, and it does not mean the swap filled. Settlement — including the actual outputAmount received — is only knowable through swap status.

Poll get_swap_status with the swapRequestId until it reports a terminal state: COMPLETED with the settled amounts, or FAILED with a structured error. Same-chain FAILED has no refund. Cross-chain FAILED can omit refund on the first responses. Cross-chain swaps remain PENDING longer, until the destination leg settles. Full lifecycle semantics on Track swap status.

Next steps

Track swap status: same-chain vs. cross-chain polling.
End-to-end example: full flow from enable to confirmation.

Get started

Features

Reference

Prerequisites

Submit the swap

Gas: sponsored vs. self-funded

What is abstracted away

Approvals

Same-chain vs. cross-chain execution

Poll swap status

Next steps

​Prerequisites

​Submit the swap

​Gas: sponsored vs. self-funded

​What is abstracted away

​Approvals

​Same-chain vs. cross-chain execution

​Poll swap status

​Next steps

Prerequisites

Submit the swap

Gas: sponsored vs. self-funded

What is abstracted away

Approvals

Same-chain vs. cross-chain execution

Poll swap status

Next steps