---
title: "Get ranked routes for a swap, without building anything"
method: POST
path: "/quote"
---

# Get ranked routes for a swap, without building anything

`POST /quote`

## Request

- Base URL: `https://swap.vurto.cc/v1`
- URL: `https://swap.vurto.cc/v1/quote`
- Auth: none required

tokenIn/tokenOut accept a contract address or a symbol (case-insensitive). A symbol matching more than one token on that chain returns 409 ambiguous_token with every candidate — never guesses. Pass wallet to persist a buildable handoff; without wallet the quotes are indicative and can only be shown. A machine credential is optional and affects rate limiting, not whether a quote is executable.

## Request body

- object
  - `wallet` string: Optional EVM signing address. Makes quotes[].id buildable through POST /swap.
  - `chainId` integer, required
  - `tokenIn` string, required: Address or symbol.
  - `tokenOut` string, required: Address or symbol.
  - `amount` string: Human decimal amount, e.g. "1.5". Use this OR amountRaw, not both.
  - `amountRaw` string: Raw integer string in the input token's smallest unit.
  - `slippageBps` integer: Defaults to a sane per-pair value server-side when omitted.
  - `receiver` string: Optional address to deliver the output to, if different from the signing wallet. Only providers with `supportsReceiver: true` are returned when this is set — see NormalizedQuote. Building with it requires the paying wallet's signed authorization (POST /destination/challenge, then /destination/authorize) or an `invoiceId` whose recipient is this address; otherwise the build fails with 403 destination_not_authorized.
  - `invoiceId` string: Optional: the open invoice this swap pays (INV-XXXX-XXXX). Its recipient, on the same chain, is accepted as `receiver` without a destination signature.

## Response `200`

OK

- object
  - `requestId` string, uuid
  - `resolved` object
    - `tokenIn` TokenInfo
      - `address` string: Checksummed contract address, or 0xEeee…EEeE for the chain's native asset.
      - `symbol` string
      - `name` string
      - `decimals` integer
      - `verified` boolean: True for tokens in the curated seed list; false for on-chain-resolved tokens the caller pasted an address for.
    - `tokenOut` TokenInfo
      - `address` string: Checksummed contract address, or 0xEeee…EEeE for the chain's native asset.
      - `symbol` string
      - `name` string
      - `decimals` integer
      - `verified` boolean: True for tokens in the curated seed list; false for on-chain-resolved tokens the caller pasted an address for.
    - `amountRaw` string
  - `quotes` NormalizedQuote[]: Ranked best first by netValueUsd.
    - `id` string: Opaque quote id. Pass as `quoteId` to POST /swap or POST /orders.
    - `provider` 'velora' | 'kyberswap' | 'uniswap' | 'aerodrome' | 'sushi' | 'pancake' | 'quickswap' | 'composto' | '1inch' | 'cowswap': Full provider list varies by chain; see GET /chains and provider health.
    - `venues` object[]: The exchanges the route crosses, in order, present only when there is more than one. A `composto` quote carries two entries; a single-venue route omits the field entirely.
      - `provider` string
      - `tokenIn` string
      - `tokenOut` string
    - `providerLabel` string
    - `chainId` integer
    - `tokenIn` string
    - `tokenOut` string
    - `amountIn` string: Raw integer string, in the input token's smallest unit.
    - `amountOut` string: Raw integer string, the provider's expected output.
    - `minimumAmountOut` string: Raw integer string, the worst acceptable output after slippage. This is what the on-chain call enforces.
    - `amountOutUsd` number, nullable
    - `gasUsd` number, nullable
    - `netValueUsd` number, nullable: Output value minus estimated gas minus platform fee. This is the ranking key, not amountOut.
    - `priceImpact` number, nullable
    - `platformFeeBps` integer
    - `platformFeeAmount` string
    - `confidence` integer: 0-100, lower when the provider's own health has degraded recently.
    - `latencyMs` integer
    - `quotedAt` integer: Unix ms.
    - `expiresAt` integer: Unix ms. The provider's own quote TTL, informational — POST /swap always re-quotes fresh before building.
    - `quoteBlock` integer, nullable
    - `mevProtection` 'full' | 'partial' | 'public' | 'unknown'
    - `supportsReceiver` boolean: Whether this provider can deliver the output to a `receiver` different from the wallet that signs.
    - `receiver` string: Present only when the request set a `receiver` different from the signing wallet.
    - `approvalTarget` string, nullable: The spender the approve step of the build will grant the allowance to, so pre-approving this address is safe. It is the same address as `steps[].spender` and `approval.spender` for the same provider. Never absent when an allowance is needed. `null` when there is nothing to approve: native input token, or a CoW order selling the native asset. The Vurto router appears here only when it sits in the call path (a direct pool route where the Vurto fee is charged); on a direct pool route with no fee this is the DEX router itself. If the fee flips between quote and build the build refuses with `approval_target_changed` instead of approving another contract.
    - `route` RouteLeg[]
      - `exchange` string
      - `pool` string
      - `tokenIn` string
      - `tokenOut` string
      - `shareBps` integer: Share of the input routed through this leg, in basis points, for split routes.
    - `badges` string[]: Highlight codes, e.g. best_price, lowest_gas.
    - `warnings` QuoteNotice[]
      - `code` string: Stable code; translate client-side, don't display raw.
      - `vars` object
    - `executionKind` 'transaction' | 'order' | 'onchain_order': Only present on quotes returned from POST /quote. 'transaction': send `steps[].tx`. 'order': sign EIP-712 off-chain, no transaction. 'onchain_order': CoW ETH-flow, a real transaction that only registers the order.
    - `estimatedGas` integer: Gas in UNITS for this route, from our own model, present only when the USD figure also came from it. An integrator ranks in units against the gasPrice it read itself; without this it treats the route as if it cost no gas, which is an advantage by omission.
  - `bestQuoteId` string, nullable
  - `failures` object[]
    - `provider` string
    - `code` string
  - `indicative` boolean
  - `refreshedAt` integer

## Other responses

- `400`: invalid_chain_id | token_required | invalid_amount | amount_required | same_token
- `404`: unknown_symbol
- `409`: ambiguous_token — details.candidates has every match
- `502`: no_routes — no provider returned a safe route

---

[API](https://skmtc.dev/vurto/apis/vurto-swap-public-api.md) · [All operations](https://skmtc.dev/vurto/apis/vurto-swap-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vurto/apis/vurto-swap-public-api/revisions/423be3a193b5?raw)