> For the complete documentation index, see [llms.txt](https://titan-exchange.gitbook.io/titan/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://titan-exchange.gitbook.io/titan/developer-doc/developers-portal/reference/quote-swap.md). # Quote Swap Query parameters and response fields for GET /api/v1/quote/swap. Returns one or more executable swap routes for a token pair and amount. ``` GET https://portal.api.titan.exchange/api/v1/quote/swap ``` | Header | Value | | ----------- | -------------------------------------------------------------------------------------- | | `x-api-key` | Your API key. Required. | | `Accept` | `application/json` or `application/vnd.msgpack`. Defaults to MessagePack when omitted. | ## Query parameters Every parameter is a flat query-string value. Lists are comma-separated. Booleans are `true` or `false`. Public keys are base58 strings. Bounds marked as server-defined are returned by [`/api/v1/info`](/titan/developer-doc/developers-portal/reference/info-venues-providers.md#info). ### Required | Parameter | Type | Description | | --------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | | `inputMint` | pubkey | Mint address of the token being sold. | | `outputMint` | pubkey | Mint address of the token being bought. | | `amount` | u64 | Amount of `inputMint` in its smallest unit — lamports for SOL, micro-USDC (10⁻⁶) for USDC. Not scaled by decimals. | | `userPublicKey` | pubkey | Wallet that will sign and execute the swap. Instructions are built for this wallet's token accounts. | ### Routing | Parameter | Type | Default | Description | | ------------------ | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `slippageBps` | u16 | `100` | Maximum slippage in basis points. Bounds are server-defined. | | `numQuotes` | u8 | `1` | Maximum number of provider quotes to return. Maximum `10`. When more providers can quote, the worst are dropped. | | `providers` | list | all | Provider IDs to restrict quoting to. Valid IDs come from [`/api/v1/providers`](/titan/developer-doc/developers-portal/reference/info-venues-providers.md#providers). | | `dexes` | list | all | Venue labels to include. Valid labels come from [`/api/v1/venues`](/titan/developer-doc/developers-portal/reference/info-venues-providers.md#venues). | | `excludeDexes` | list | — | Venue labels to exclude. | | `venueAllowlist` | list of pubkey | — | Pool addresses to restrict routing to. Filters individual pools; `dexes` filters by label. | | `venueBanlist` | list of pubkey | — | Pool addresses to exclude. Overrides `venueAllowlist`. | | `noVoteAccounts` | bool | `false` | Excludes a server-curated set of market-maker venues. | | `onlyDirectRoutes` | bool | `false` | Returns only single-hop routes between the two mints. | {% hint style="warning" %} An unrecognized `dexes` label does not return an error. It restricts routing to a venue matching nothing and produces `404 -7`. Take valid labels from [`/api/v1/venues`](/titan/developer-doc/developers-portal/reference/info-venues-providers.md#venues). {% endhint %} ### Transaction sizing | Parameter | Type | Default | Description | | ----------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `addSizeConstraint` | bool | `true` | Returns only routes that fit within the transaction size limit. | | `sizeConstraint` | u32 | `1168` | Maximum transaction size in bytes. Clamped to the format limit: 1232 for V0, 4096 for V1. | | `accountsLimitTotal` | u16 | — | Maximum accounts a route may reference. Transaction V1 supports at most 64. | | `accountsLimitWritable` | u16 | `64` | Maximum writable accounts a route may reference. | | `transactionTemplate` | string | — | Reserves room for instructions and lookup tables added after quoting. MessagePack-encoded, then base64. Incompatible with the three parameters above. See [Transaction Template](/titan/developer-doc/swap-api/guides/transaction-template.md). | ### Transaction | Parameter | Type | Default | Description | | ----------------------------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `closeInputTokenAccount` | bool | `false` | Closes the input token account as part of the swap. | | `createOutputTokenAccount` | bool | `true` | Adds an idempotent create-ATA instruction for the output token. | | `outputAccount` | pubkey | user's ATA | Sends output to a specific token account. | | `outputWsol` | bool | `false` | Leaves output as wrapped SOL rather than unwrapping to native SOL. Applies only when `outputMint` is wSOL. Requires the V3 swap program (default). | | `payer` | pubkey | — | Separate wallet that pays network fees and rent. Must also sign the transaction. Requires the V3 swap program (default). | | `positiveSlippageFeeReceiver` | pubkey | — | Token account of `outputMint` that receives surplus when execution beats the quote, capped at 10 bps of `outAmount`. Requires the V3 swap program (default). | | `transactionFormat` | `0` \| `1` | `0` | `0` for a versioned V0 transaction. `1` selects Transaction V1, which requires cluster support and the V3 swap program (default). | | `titanSwapVersion` | `2` \| `3` | `3` | `2` selects the previous V2 swap program. See [Swap V2 vs Swap V3](/titan/developer-doc/swap-api/guides/swap-v2-vs-v3.md). | ### Performance | Parameter | Type | Default | Description | | ---------------------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `simulate` | bool | `true` | Simulates each route against current chain state before returning it, giving tighter realized slippage. `false` skips simulation and reduces latency at the cost of the pre-flight check. | | `maxPriceDeviationBps` | u16 | `1000` | Rejects quotes that deviate from the reference price by more than this many basis points. `10000` or higher disables the check. The check fails open when reference prices are unavailable. | ### Response options | Parameter | Type | Default | Description | | -------------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------- | | `includeAltContents` | bool | `false` | Includes the full contents of every address lookup table the routes use, in a top-level `alts` array. | ## Response | Field | Type | Description | | ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Identifier for this quote request. Include it when reporting an issue. | | `inputMint`, `outputMint` | pubkey | Echo of the request. | | `amount` | u64 | Echo of the request. | | `quotes` | map | One entry per provider that could quote, keyed by provider ID. Not an array. | | `metadata` | object | Recommendation and pricing context. | | `alts` | array | Lookup table contents. Present only when `includeAltContents=true`. Each entry is `{ "p": , "a": [] }`. | ### `metadata` | Field | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ExpectedWinner` | Provider ID of the route Titan recommends — the best slippage-adjusted route. Select this rather than sorting by `outAmount`. Also returned as `expectedWinner` with the same value. | | `inputPriceUSD`, `outputPriceUSD` | Reference USD prices for the two tokens at quote time. | | `inputMintDecimals`, `outputMintDecimals` | Decimal places of each mint, for formatting amounts without a separate token lookup. | ### Route Each value in `quotes`. | Field | Type | Description | | --------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inAmount` | u64 | Input tokens consumed, in smallest units. | | `outAmount` | u64 | Expected output tokens, in smallest units, before slippage. | | `slippageBps` | u16 | Slippage tolerance the route was built with. | | `steps` | array of Step | Hops in the route. Empty when the provider fills directly rather than routing through pools. | | `instructions` | array of Instruction | Instructions to execute. Some providers include a compute-budget instruction; check for the `ComputeBudget111111111111111111111111111111` program before adding one. | | `addressLookupTables` | array of pubkey | Lookup tables the instructions rely on. | | `contextSlot` | u64 | Slot the route was computed against. | | `computeUnits` | u64 | Compute units the route is expected to consume. | | `computeUnitsSafe` | u64 | Recommended compute unit limit for the transaction. Varies by provider. | | `expiresAtMs`, `expiresAfterSlot` | u64 | Hard expiry when the provider sets one. | | `referenceId` | string | Provider-specific reference for this quote. Include it in support requests. | | `timeTakenNs` | u64 | Route computation time in nanoseconds, reported by some providers. | ### Step Each entry in `steps`. | Field | Description | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ammKey` | Address of the pool or market used at this hop. | | `label` | Venue name, matching the labels from `/api/v1/venues`. | | `inputMint`, `outputMint` | Tokens in and out at this hop. | | `inAmount`, `outAmount` | Amounts at this hop. | | `allocPpb` | Share of the order through this hop, in parts per billion. `1000000000` is the full order. Split routes have several steps whose values sum to `1000000000`. | | `feeMint`, `feeAmount` | Venue fee, when reported. | | `contextSlot` | Slot the pool state was read at. | ### Instruction Instructions use short field names. ```json { "p": "T1TANpTeScyeqVzzgNViGDNrkQ6qHz9KrSBS4aNXvGT", "a": [ { "p": "8AdYBZcRixYVacvhGG2PBNruyoWfmagR6aiBUq6qE1nf", "s": true, "w": true } ], "d": "KgIAypo7AAAAADe2AQYAAAAAZAACAAAUBAAAAA0A" } ``` | Field | Description | | ----- | ------------------------------------------------------------------------------- | | `p` | Program ID. | | `a` | Accounts, in order. Each has `p` (address), `s` (is signer), `w` (is writable). | | `d` | Instruction data. base64 in JSON, raw bytes in MessagePack. | ## Example ```bash curl "https://portal.api.titan.exchange/api/v1/quote/swap?\ inputMint=So11111111111111111111111111111111111111112&\ outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&\ amount=1000000000&\ userPublicKey=8AdYBZcRixYVacvhGG2PBNruyoWfmagR6aiBUq6qE1nf&\ slippageBps=50&\ numQuotes=5&\ includeAltContents=true" \ -H "x-api-key: $TITAN_API_KEY" \ -H "Accept: application/json" ``` A complete response and the code to convert it into a signed transaction are in the [Quickstart](/titan/developer-doc/developers-portal/quickstart.md). ## Errors | Status | Body | Meaning | | ------ | -------------------------------------- | --------------------------------------------------------------------------------- | | `400` | Plain text naming the field | A parameter is missing or malformed. | | `400` | JSON with an engine `code` | A parameter is outside the bounds published by `/api/v1/info`. | | `401` | `{"error":{"code":"invalid_api_key"}}` | Missing, unknown or revoked key. | | `404` | JSON with `code: -7` | No provider could build a route. `metadata.errors` lists one reason per provider. | | `429` | `{"error":{"code":...}}` | Plan rate limit or credit allowance exceeded. | Full error reference: [Errors](/titan/developer-doc/developers-portal/errors.md).