Get a Swap Quote

• Your parent organization has enabled Swaps via ACTIVITY_TYPE_UPSERT_SWAP_CONFIG with a valid feeReceiverWalletAddress and feeBps. Quote requests against organizations without the Swaps feature flag will fail. Without a swap configuration, quotes default to a client fee of 0. See Enable Swaps.
• The signing address (signWith) is a wallet account in the organization submitting the activity. Parent organization wallets and sub-organization wallets can both swap: the activity belongs to the organization that owns the wallet. In a delegated access setup, a delegate can submit the activity to the wallet owner’s organization or act as the second signer on an activity submitted by the wallet owner.

​

Call create_swap_quote

curl --request POST \
  --url https://api.turnkey.com/public/v1/submit/create_swap_quote \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "type": "ACTIVITY_TYPE_CREATE_SWAP_QUOTE",
    "timestampMs": "<string> (e.g. 1745474677453)",
    "organizationId": "<ORGANIZATION_ID>",
    "parameters": {
      "signWith": "<WALLET_ACCOUNT_ADDRESS>",
      "inputToken": "eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913",
      "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
      "inputAmount": "1000000",
      "slippageBps": "50"
    }
  }'

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/create_swap_quote", {
  type: "ACTIVITY_TYPE_CREATE_SWAP_QUOTE",
  timestampMs: String(Date.now()),
  organizationId: "<ORGANIZATION_ID>",
  parameters: {
    signWith: "<WALLET_ACCOUNT_ADDRESS>",
    inputToken: "eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913",
    outputToken: "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
    inputAmount: "1000000",
    slippageBps: "50",
  },
});

const { quotes } = activity.result.createSwapQuoteResult;
const bestQuote = quotes[0];

{
  "activity": {
    "id": "<ACTIVITY_ID>",
    "status": "ACTIVITY_STATUS_COMPLETED",
    "type": "ACTIVITY_TYPE_CREATE_SWAP_QUOTE",
    "result": {
      "createSwapQuoteResult": {
        "quotes": [
          {
            "quoteId": "<QUOTE_ID>",
            "provider": "relay",
            "outputAmount": "<EXPECTED_OUTPUT>",
            "minOutputAmount": "<MINIMUM_OUTPUT>",
            "clientFeeBps": "<YOUR_FEE_IN_BPS>",
            "slippageBps": "<SLIPPAGE_TOLERANCE>",
            "estimatedTimeSeconds": "<ESTIMATED_TIME>",
            "expiresAt": "<EXPIRY_MS>"
          }
        ]
      }
    }
  }
}

​

Read the response

{
  "activity": {
    "result": {
      "createSwapQuoteResult": {
        "quotes": [
          {
            "provider": "relay",
            "quoteId": "sq_v1_d47bcb2192150649280454baa8a48f1cf4b1e5270997901436c2d907eecca6ac",
            "outputAmount": "6599005722903595711",
            "minOutputAmount": "6566010694289072050",
            "slippageBps": "50",
            "clientFeeBps": "1",
            "estimatedTimeSeconds": "2",
            "expiresAt": "1786453118047"
          }
        ]
      }
    }
  }
}

• quoteId — identifies this quote. Pass it to ACTIVITY_TYPE_EXECUTE_SWAP_V2 to execute against this quote’s pricing; execution is pinned to the quote it references.
• provider — the provider that produced the quote and will execute the swap.
• outputAmount — expected output in raw onchain units, net of all fees. This is what the recipient receives if the swap fills at the quoted price.
• minOutputAmount — the floor enforced at execution, derived from outputAmount and your slippage tolerance. If the swap cannot deliver at least this amount, it fails rather than filling worse.
• slippageBps — the slippage tolerance this quote was priced with, echoed from the request.
• clientFeeBps — your organization’s configured fee, for display or audit. Turnkey’s fee is baked into the quoted amounts and is not itemized. See Fees.
• estimatedTimeSeconds — estimated time to settlement.
• expiresAt — millisecond epoch after which the quote can no longer be executed.

​

Execution price semantics

• minOutputAmount is the enforced floor. If the swap cannot deliver at least this amount, it will fail — the user never receives less than the floor they signed.
• outputAmount is the expected fill, not a guarantee. The settled amount can be higher or lower than quoted, bounded on the low side by minOutputAmount. The actual amount is reported as outputAmount in swap status on COMPLETED.
• Quotes expire. A quote can only be executed before its expiresAt; after that, request a new quote. Quotes may still be technically valid while the route the quote describes is no longer available in the market due to price movements. In that situation, if the quote cannot be executed with the economic parameters, it will fail at execution time.

​

Slippage

• A tighter slippage tolerance reduces the risk of an unfavorable fill but increases the chance the swap fails if the market moves.
• A wider tolerance makes execution more likely but exposes the user to a worse price, down to the floor.
• A swap that fails on the floor still incurs gas for the reverted origin transaction. If the swap is sponsored, that cost falls on your organization, not the user — slippage-driven reverts are a gas cost to budget for in sponsored flows.

​

How fees are applied

​

Same-chain vs. cross-chain quotes

​

Next steps

• Execute a swap: the signing activity that runs the swap end-to-end.
• Track swap status: same-chain vs. cross-chain polling.