> For the complete documentation index, see [llms.txt](https://docs-swap.crypto-chief.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-swap.crypto-chief.com/api-reference/quote.md). # Quote ## Quote Prices a swap: the expected output, the guaranteed minimum, every fee, the route, and an execution-risk assessment. No wallet is needed — without `from_address` it is a pure estimate. A quote lives 30 seconds (`expires_at`). Pass its `quote_id` to [`POST /v1/build`](/api-reference/build.md) to keep its route and executor. #### **Quote** `POST` `https://swap-api.crypto-chief.com/YOUR_API_KEY/v1/quote` **Headers** | Name | Value | | ------------ | --------------------------------------------------------------------------------------------------------------- | | Content-Type | `application/json` | | X-Request-Id | Optional — your id for this call, echoed in the response ([Authentication](/getting-started/authentication.md)) | **Body** | Name | Type | Required | Description | | ------------------ | --------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `network` | string | true | Network code, case-insensitive — `ETH_MAINNET`, `TRON_MAINNET`, ... ([list](/getting-started/networks-and-tokens.md#network-codes)) | | `token_in` | string | true | What you give — address, configured symbol or `NATIVE`, [per family](/getting-started/networks-and-tokens.md#naming-a-token) | | `token_out` | string | true | What you get, same forms | | `amount_in` | string | one of two | Input amount in base units, decimal string | | `amount_in_human` | string | one of two | Input amount with a decimal point, e.g. `"1.5"` | | `from_address` | string | false | Your wallet. With it, its allowance, balance, trust lines and token accounts are part of the answer | | `slippage_bps` | integer | false | Slippage tolerance, 1 bps = 0.01 %. Default `50`, at most `5000` | | `max_hops` | integer | false | Pools in one route branch, `1`–`4`. Default `3`. TON routes use at most 2; a larger value adds a warning | | `max_splits` | integer | false | Parallel route branches, at most `7`. Default `4`. TON routes are not split; a larger value adds a warning | | `sources` | string\[] | false | Only these liquidity sources — `id` values from [`/v1/liquidity-sources`](/api-reference/liquidity-sources.md) | | `exclude_sources` | string\[] | false | Exclude these liquidity sources | | `executors` | string\[] | false | Only these executors — see [below](#the-executors-filter) | | `allow_non_atomic` | boolean | false | Allow routes of several swap transactions. Default `false` — [what that means](/getting-started/how-a-swap-works.md#non-atomic-routes) | | `alternatives` | integer | false | How many alternative routes to return in `alternatives[]`. Default `3`, at most `10` (`5` on TON). Solana returns none | | `fee_bps` | integer | false | [Partner fee](/getting-started/partner-fees.md) out of the output, at most `300`; TON caps it at `100`. `0`: no fee. Not available on EVM and TRON | | `fee_recipient` | string | with `fee_bps` | Receiver of the partner fee | {% hint style="warning" %} **Exactly one of `amount_in` and `amount_in_human`.** Both or neither is `400 AMOUNT_INVALID`. A field this request does not define is a `400 INVALID_REQUEST`; the `message` names it. {% endhint %} ```json { "network": "ETH_MAINNET", "token_in": "USDC", "token_out": "NATIVE", "amount_in": "1000000000", "from_address": "0x1F33F99676B65968885adDFaFda3a736424d93C9", "slippage_bps": 50 } ``` **Response** {% tabs %} {% tab title="200" %} ```json { "quote_id": "0b6f8c7e-6a43-4d0a-9d7e-3c2f5a1e9b10", "network": "ETH_MAINNET", "family": "EVM", "token_in": {"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6, "kind": "token", "flags": ["pausable", "blacklist"]}, "token_out": {"address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "symbol": "ETH", "decimals": 18, "kind": "native"}, "amount_in": "1000000000", "amount_in_human": "1000", "amount_out": "263157894736842105", "amount_out_human": "0.263157894736842105", "amount_out_min": "261842105263157894", "amount_out_min_human": "0.261842105263157894", "slippage_bps": 50, "net_amount_out": "261636578947368421", "price_impact_bps": 4, "fees": { "network": { "native_symbol": "ETH", "cost_native": "1495000000000000", "cost_native_human": "0.001495", "cost_in_token_out": "1495000000000000", "cost_usd": "5.68", "gas_limit": 180000, "unit_price": "12000000000", "effective_unit_price": "6500000000" }, "pools": [ {"source": "uniswap_v3", "pool": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", "fee_bps": 5.0, "fee_amount": "300000", "fee_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}, {"source": "sushi_v2", "pool": "0x397FF1542f962076d0BFE58eA045FfA2d347ACa0", "fee_bps": 30.0, "fee_amount": "1200000", "fee_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"} ], "service": {"bps": 0, "amount": "0"} }, "route": { "splits": [ { "share_bps": 6000, "amount_in": "600000000", "amount_out": "157894736842105263", "hops": [ {"source": "uniswap_v3", "pool": "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", "kind": "uni_v3", "token_in": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "fee_bps": 5.0, "amount_in": "600000000", "amount_out": "157894736842105263"} ] }, { "share_bps": 4000, "amount_in": "400000000", "amount_out": "105263157894736842", "hops": [ {"source": "sushi_v2", "pool": "0x397FF1542f962076d0BFE58eA045FfA2d347ACa0", "kind": "uni_v2", "token_in": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "token_out": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "fee_bps": 30.0, "amount_in": "400000000", "amount_out": "105263157894736842"} ] } ] }, "executor": {"id": "sushi_rp5", "address": "0xf2614A233c7C3e7f08b1F887Ba133a13f1eb2c55", "atomic": true, "third_party": true, "onchain_deadline": false, "transactions": 2}, "risk": { "level": "low", "score": 12, "penalty": "26315789473684", "factors": [ {"code": "third_party_router", "level": "low", "message": "executor contract is controlled by a third party", "cost": "26315789473684"}, {"code": "setup_required", "level": "low", "message": "approve USDC before the swap"} ] }, "setup_required": true, "state": {"reference": 23651200, "age_ms": 1800}, "expires_at": "2026-10-25T12:00:30Z", "search": {"engine": "native", "paths_considered": 18, "pools_considered": 42, "elapsed_ms": 21, "truncated": false} } ``` {% endtab %} {% tab title="400" %} ```json { "error": "AMOUNT_INVALID", "message": "set either amount_in or amount_in_human, not both" } ``` {% endtab %} {% tab title="422" %} ```json { "error": "NO_ROUTE", "message": "no route between USDC and XYZ" } ``` {% endtab %} {% tab title="503" %} ```json { "error": "NETWORK_UNAVAILABLE", "message": "network ETH_MAINNET is temporarily unavailable: it did not start" } ``` {% endtab %} {% endtabs %} **Fields** | Field | Description | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `quote_id` | Pass to [`POST /v1/build`](/api-reference/build.md) to build this route and executor — kept while they fit the build's constraints and stay best ([the exact rule](/getting-started/how-a-swap-works.md#quote-vs-build)) | | `network` / `family` | The resolved network and its family (`EVM`, `TRON`, `SOLANA`, `TON`, `XRP`) | | `token_in` / `token_out` | The resolved token: `address`, `symbol`, `decimals`, `kind` (`native` or `token`), `flags` when any ([flags](/getting-started/networks-and-tokens.md#token-flags); new values can appear) | | `amount_in` / `amount_in_human` | The input, in base units and with decimals applied | | `amount_out` / `amount_out_human` | The expected output | | `amount_out_min` / `amount_out_min_human` | The guaranteed minimum: `floor(amount_out × (10000 − slippage_bps) / 10000)`. Below it the swap does not execute | | `slippage_bps` | The tolerance in force | | `net_amount_out` | `amount_out` minus the network cost of all steps in the output token minus the risk penalty. **Routes are ranked by it** | | `price_impact_bps` | How much the trade moves the price | | `fees` | `network`, `pools`, `service`, `other` — below | | `route` | `splits[]`: the route's branches — below | | `executor` | The contract or program that executes the swap — below | | `risk` | Execution risk — below | | `setup_required` | An approval, trust line or token account is needed before the swap | | `state` | `reference` (block / slot / ledger / seqno) and `age_ms` — the network state the quote is computed on, and its age | | `expires_at` | The quote is valid until this time (30 seconds from the call) | | `alternatives` | Up to `alternatives` other routes, each in the same shape as the top level. Omitted when there are none (and from the examples on this page) | | `search` | `engine` (`native`: the API's own route search; `jupiter`: Solana's route source; `rippled_path_find` / `local_book_amm`: XRP Ledger), `paths_considered`, `pools_considered`, `elapsed_ms`, `truncated` | | `warnings` | Notes about this quote — see [below](#read-the-warnings) | **`fees.network`** — the network cost of all steps together: | Field | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `native_symbol` | The native coin the cost is paid in | | `cost_native` / `cost_native_human` | Total cost in the native coin | | `cost_in_token_out` | The same cost converted into the output token's base units — the number `net_amount_out` subtracts | | `cost_usd` | The same cost in USD | | `gas_limit` | Gas limit of the swap step (EVM). `cost_native` covers every step, approvals included | | `unit_price` | The most the transaction may pay per unit: wei per gas (EVM, the `maxFeePerGas`), sun per energy (TRON), micro-lamports per compute unit (Solana) | | `effective_unit_price` | The price per unit `cost_native` is computed with. EVM: base fee plus priority fee, or the legacy gas price | | `details` | Family-specific components: `l1_fee`, `energy`, `bandwidth`, `compute_units`, `forward_ton`, `reserve_xrp`, ... | **`fees.pools[]`** — the fee of every pool of the route: `source`, `pool`, `fee_bps` (a decimal number: pool fees can be fractional bps), `fee_amount`, `fee_token`. **`fees.service`** — the [partner fee](/getting-started/partner-fees.md): `{bps, amount, token}`, `amount` in the output token's base units. Without a fee: `{"bps": 0, "amount": "0"}`. With one, `amount_out`, `amount_out_min` and `net_amount_out` are after the fee; the amounts in `route` and `fees.pools` are before it. **`fees.other[]`** — other withholdings as `{code, description, amount, token}`: an XRP issuer's transfer fee (`issuer_transfer_fee`, `issuer_transfer_fee_output`, `issuer_transfer_fee_partner`), a token's transfer tax. **`route.splits[]`** — the branches the input is split across: `share_bps` (share of the input), `amount_in`, `amount_out`, and `hops[]` — the pools in order, each `{source, pool, kind, token_in, token_out, fee_bps, amount_in, amount_out}`. **`executor`**: | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | The executor id | | `address` | The contract or program that receives the swap call | | `atomic` | The whole swap settles in one transaction or reverts | | `third_party` | The executor is a contract a third party controls and can pause or replace | | `onchain_deadline` | The executor checks the transaction deadline on chain | | `transactions` | The swap transactions plus the approvals this quote knows of. Without `from_address` no approval is counted. The real count for your wallet is `steps.length` of a build | **`risk`**: | Field | Description | | ----------- | --------------------------------------------------------------- | | `level` | `low`, `medium`, `high` | | `score` | 0 (none) to 100 (do not execute) | | `penalty` | The ranking penalty in output-token base units | | `factors[]` | `{code, level, message, cost?}` — the codes are the table below | #### Risk factors | `code` | When | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `non_atomic` | The route is several swap transactions | | `async_settlement` | TON: the output arrives in later messages; a rejected swap returns the input | | `third_party_router` | The executor is a contract a third party can pause or replace | | `external_route_source` | The route was built by an external service | | `no_onchain_deadline` | The executor does not check the transaction's expiry on chain | | `price_impact` | High price impact | | `mev_exposure` | Sandwich risk in the public mempool | | `thin_liquidity` | A hop consumes a noticeable share of the pool's reserve | | `token_flags` | Transfer tax, rebasing, pausable/blacklist, an unlisted token, Token-2022 extensions, XRP freeze/clawback | | `stale_state` | The network state is older than its threshold | | `incomplete_state` | The route goes beyond the loaded range of a pool | | `setup_required` | An approval, trust line or token account is needed | | `simulation_not_run` | The build's simulation did not run or did not finish (a failed one is `422 SIMULATION_FAILED` without steps) | | `simulation_below_quote` | The build's simulation returned less than the local quote within the slippage tolerance; `amount_out` and `amount_out_min` were recomputed from the simulation | | `fee_limit_capped` | TRON: the swap may need more energy than the 100 TRX `fee_limit` cap buys; the transaction can fail with `OUT_OF_ENERGY` | | `partial_payment` | XRP Ledger: the payment may deliver less than `Amount` (never less than `DeliverMin`) | | `local_estimate` | XRP Ledger: the output is a local estimate, not a path-finding result | | `tx_size` | Solana: the transaction is close to the size limit | ### Example `swap()` is defined in [Authentication](/getting-started/authentication.md). {% tabs %} {% tab title="JavaScript" %} ```javascript const quote = await swap("quote", { network: "ETH_MAINNET", token_in: "USDC", token_out: "NATIVE", amount_in: "1000000000", from_address: "0x1F33F99676B65968885adDFaFda3a736424d93C9", slippage_bps: 50, }); console.log(quote.amount_out_human, "min", quote.amount_out_min_human); ``` {% endtab %} {% tab title="PHP" %} ```php $quote = swap('quote', [ 'network' => 'ETH_MAINNET', 'token_in' => 'USDC', 'token_out' => 'NATIVE', 'amount_in' => '1000000000', 'from_address' => '0x1F33F99676B65968885adDFaFda3a736424d93C9', 'slippage_bps' => 50, ]); echo $quote['amount_out_human'], ' min ', $quote['amount_out_min_human'], "\n"; ``` {% endtab %} {% tab title="GO" %} ```go quote, _, err := swap("quote", map[string]any{ "network": "ETH_MAINNET", "token_in": "USDC", "token_out": "NATIVE", "amount_in": "1000000000", "from_address": "0x1F33F99676B65968885adDFaFda3a736424d93C9", "slippage_bps": 50, }) if err != nil { log.Fatal(err) } fmt.Println(quote["amount_out_human"], "min", quote["amount_out_min_human"]) ``` {% endtab %} {% tab title="Python" %} ```python quote = swap("quote", { "network": "ETH_MAINNET", "token_in": "USDC", "token_out": "NATIVE", "amount_in": "1000000000", "from_address": "0x1F33F99676B65968885adDFaFda3a736424d93C9", "slippage_bps": 50, }) print(quote["amount_out_human"], "min", quote["amount_out_min_human"]) ``` {% endtab %} {% tab title="curl" %} ```bash curl -s -X POST "https://swap-api.crypto-chief.com/$CC_API_KEY/v1/quote" \ -H "Content-Type: application/json" \ -d '{"network":"ETH_MAINNET","token_in":"USDC","token_out":"NATIVE","amount_in":"1000000000","from_address":"0x1F33F99676B65968885adDFaFda3a736424d93C9","slippage_bps":50}' ``` {% endtab %} {% endtabs %} ### `from_address` changes the answer Without it, no wallet is read: allowances are not checked, balances are not known, `setup_required` stays `false` and `warnings` says so. With it, the quote knows an approval is missing before you build — and a wallet that cannot pay the input and the fees fails here or at build with `422 BALANCE_INSUFFICIENT` instead of on chain. ### Read the warnings `warnings` is where a quote says what it could not do: the network cost was converted through the input token's price and the route's rate; the network cost and the risk penalty exceed the output; some contracts' energy settings could not be read (TRON: the cost then assumes the caller pays all energy); the gas or energy price is unknown. Warnings are free text for logs, not codes to branch on; a quote with warnings is still valid. `search.truncated: true` means the search stopped on its time budget; the route returned is the best found so far. ### The `executors` filter The accepted values depend on the family: | Family | Values | Otherwise | | ---------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | EVM, TRON | `oneinch_v6`, `sushi_rp5`, `dex_router`, `sun_universal_router`, `cc_router` | A name that is no executor at all is `400 INVALID_REQUEST`. A known executor the network does not have, or one that is off, is `503 EXECUTOR_UNAVAILABLE` | | Solana | `jupiter` | Any other value is `422 NO_ROUTE` | | TON | `stonfi_v2`, `dedust` | An unknown value is `400 INVALID_REQUEST` | | XRP Ledger | `xrpl_payment`, `xrpl_batch` (`xrpl_batch` only together with `fee_bps`) | Any other value is `503 EXECUTOR_UNAVAILABLE` | `oneinch_v6` and `sushi_rp5` are the 1inch and Sushi aggregation routers. `dex_router` is a DEX's own router contract, for example the Uniswap V3 router; [`/v1/liquidity-sources`](/api-reference/liquidity-sources.md) lists one `dex_router` entry per DEX router. `sun_universal_router` is the SUN.io Universal Router on TRON. `cc_router` is listed as `disabled` on EVM networks and TRON; naming it answers `503 EXECUTOR_UNAVAILABLE`. Which executors are live on a network right now is what [`/v1/liquidity-sources`](/api-reference/liquidity-sources.md) shows. `executor.third_party: true` means the executing contract is controlled by a third party that can pause or replace it; the quote prices that risk into `net_amount_out` (factor `third_party_router`).