Getting a Quote

Fetch a fee-aware indicative quote for a token pair. Displays expected output and the minimum output the caller should accept.

• The parent organization has configured swaps with a valid feeReceiverWalletAddress and feeBps. Quote requests against orgs with no swap configuration set are rejected.

Call get_swap_quote

get_swap_quote is a query, not an activity — it returns synchronously and is not stamped into an activity envelope. Send the request fields at the top level (there is no parameters object, type, or timestampMs).

organizationId · string · required

Unique identifier of the sub-organization requesting the quote. The parent organization’s active FEATURE_NAME_SWAP_CONFIG is applied server-side.

inputToken · string · required

CAIP-19 identifier for the token being sold. Example: eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913 (USDC on Base). The origin chain is derived from this identifier.

outputToken · string · required

CAIP-19 identifier for the token being bought. Example: eip155:8453/erc20:0x4200000000000000000000000000000000000006 (WETH on Base). Same-chain if the CAIP-2 prefix matches inputToken. Otherwise a cross-chain route.

inputAmount · string · required

Amount of the input token, in raw on-chain units. For example, "1000000" for 1 USDC at 6 decimals.

walletAccount · string · required

The address of the wallet account that will perform the swap. Used to compute an accurate quote (balances and allowances) (To Confirm — exact format: on-chain address vs. wallet-account identifier).

slippage · string

Optional. Slippage tolerance in basis points, expressed as a stringified integer. For example, "50" = 0.5%. Applied to minOutputAmount computation (To Confirm — server default when omitted).

cURL

curl --request POST \
  --url https://api.turnkey.com/public/v1/query/get_swap_quote \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-Stamp: <string> (see Stamps)" \
  --data '{
    "organizationId": "<SUB_ORGANIZATION_ID>",
    "inputToken": "eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913",
    "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
    "inputAmount": "1000000",
    "walletAccount": "<WALLET_ACCOUNT_ADDRESS>",
    "slippage": "50"
  }'

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,
  }),
);

// Queries return the response body directly — there is no `activity` wrapper.
const { quotes } = await client.request("/public/v1/query/get_swap_quote", {
  organizationId: "<SUB_ORGANIZATION_ID>",
  inputToken: "eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913",
  outputToken: "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
  inputAmount: "1000000",
  walletAccount: "<WALLET_ACCOUNT_ADDRESS>",
  slippage: "50",
});

const bestQuote = quotes[0];

Response:

{
  "inputToken": "eip155:8453/erc20:0x833589fCD6EDB6E08f4c7C32D4f71b54bdA02913",
  "outputToken": "eip155:8453/erc20:0x4200000000000000000000000000000000000006",
  "inputAmount": "1000000",
  "quotes": [
    {
      "quoteId": "<QUOTE_ID>",
      "provider": "0x",
      "outputAmount": "<EXPECTED_OUTPUT>",
      "minOutputAmount": "<MINIMUM_OUTPUT>"
    }
  ]
}

Response fields

The top-level inputToken, outputToken, and inputAmount are echoed from the request. Quotes are returned in a quotes array — in V1 this contains a single option; multiple options are on the roadmap.

Each entry in quotes contains:

• quoteId: opaque identifier for the quote. Informational only — execute_swap does not accept a quoteId, so it cannot be replayed. Useful for logging and correlation.
• provider: the DEX aggregator that produced this quote (0x in V1).
• outputAmount: expected output amount, fee-adjusted, in raw on-chain units.
• minOutputAmount: minimum output the caller should accept at execute time, given the requested slippage. Derived from outputAmount and the caller’s slippage tolerance.

Quotes are indicative

Quote outputs may differ from execution outputs. When you call execute_swap, Turnkey fetches fresh executable transaction data from the provider (not the quote’s payload) and settles at market rates within the caller’s slippage tolerance. Two implications:

• Quote outputAmount is a hint. Actual receive amount at execute time can be higher or lower, bounded on the low side by the slippage-derived floor.
• Quotes are not persisted. Turnkey does not maintain a mapping from quoteId to executable data. The quoteId is opaque and cannot be replayed.

If you display quote amounts to end users, refresh the quote near the moment of execution to keep the displayed value close to the settled value.

How fees are applied

Each quote’s outputAmount already reflects your organization’s feeBps from FEATURE_NAME_SWAP_CONFIG. There is no separate fee amount to add or subtract on the client. The end user’s displayed receive amount is a quote’s outputAmount (or the actual settled amount at execute time).

Fee configuration is snapshotted server-side per activity. If your fee configuration changes between quote and execute, the execute settles at the fee configuration active when it runs, not when the quote was fetched.

Same-chain vs. cross-chain quotes

Quote shape is identical for same-chain and cross-chain routes. The provider selects the route based on the inputToken and outputToken CAIP-19 identifiers.

Cross-chain quotes are subject to the same freshness and slippage semantics as same-chain quotes, but cross-chain execution has a longer post-broadcast lifecycle. See Track swap status for the two lifecycle models.

Next steps

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