> For the complete documentation index, see [llms.txt](https://listed-exchange.gitbook.io/listed/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://listed-exchange.gitbook.io/listed/developers/quote.md).

# Get a quote

```
GET https://listed.exchange/api/v1/quote
```

Returns the best executable route for a pair and amount, priced across every venue and ranked by output **after gas**. Builds no transaction. Output values are already net of `totalFeeBps` (your `partnerFeeBps`; LISTED charges 0 bps).

## Request

Query parameters:

| Param                         | Required           | Description                                                                                                                                                                             |
| ----------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from`                        | yes                | Input token symbol (`[A-Za-z0-9._-]{1,24}`), e.g. `ETH`.                                                                                                                                |
| `to`                          | yes                | Output token symbol.                                                                                                                                                                    |
| `amount`                      | yes                | Amount of `from` to sell, in human units. Must be `> 0`.                                                                                                                                |
| `fromAddress`                 | for unknown tokens | `0x…` address of `from`, or `native`. Optional if the symbol is in LISTED's registry.                                                                                                   |
| `toAddress`                   | for unknown tokens | `0x…` address of `to`.                                                                                                                                                                  |
| `fromDecimals`                | for unknown tokens | Integer `0`–`36`.                                                                                                                                                                       |
| `toDecimals`                  | for unknown tokens | Integer `0`–`36`.                                                                                                                                                                       |
| `slippageBps`                 | no                 | Integer `0`–`5000`. Default `50` (0.5%).                                                                                                                                                |
| `sender`                      | no                 | The address that will swap. When given, LISTED can pre-simulate a native-input winner and drop it if it would revert.                                                                   |
| `partnerFeeBps`               | no                 | Your take, integer `0`–`50`. Default `0`. Requires `partnerFeeRecipient` when > 0.                                                                                                      |
| `partnerFeeRecipient`         | if fee > 0         | Wallet that should receive your share. Must be a `0x` address.                                                                                                                          |
| `preferEngine`                | no                 | Quote a specific venue only: `kyberswap` / `rialto` / `xpath` / `nordstern` / `de1` / `ekubo`. Returns `route: null` when that venue can't price the pair. (Also accepted as `engine`.) |
| `fromPriceUsd` / `toPriceUsd` | no                 | Live USD marks. Improve price-impact accuracy.                                                                                                                                          |

{% hint style="info" %}
For core tokens (`ETH`, `WETH`, `USDG`, and other registry tokens) the symbol alone is enough. For any other Robinhood Chain token, pass `fromAddress` + `fromDecimals` (and the `to` equivalents).
{% endhint %}

## Example

```bash
curl --get "https://listed.exchange/api/v1/quote" \
  -H "Authorization: Bearer $LISTED_API_KEY" \
  --data-urlencode "from=ETH" \
  --data-urlencode "to=USDG" \
  --data-urlencode "amount=1" \
  --data-urlencode "slippageBps=50" \
  --data-urlencode "partnerFeeBps=10" \
  --data-urlencode "partnerFeeRecipient=0xYourTreasury"
```

## Response

```json
{
  "route": {
    "engine": "nordstern",
    "venues": ["Nordstern"],
    "hops": [{ "from": "ETH", "to": "USDG", "dex": "nordstern", "dexName": "Nordstern", "share": 1 }],
    "amountIn": 1,
    "amountOut": 2461.1685,
    "minimumReceived": 2448.8627,
    "midRate": 2461.1685,
    "priceImpactBps": 6,
    "networkFeeEth": 0.0000193,
    "slippageBps": 50,
    "executable": true,
    "protocolFeeBps": 10,
    "quoteId": "46194168-1349-49de-85b1-bf948661c04c",
    "expiresAt": 1789062203817,
    "alternatives": [
      { "engine": "nordstern", "label": "Nordstern", "amountOut": 2461.1685, "netAmountOut": 2461.1208, "gasCostOut": 0.0476, "deltaBps": 0 }
    ]
  },
  "listedFeeBps": 0,
  "integratorFeeBps": 0,
  "partnerFeeBps": 10,
  "partnerFeeRecipient": "0xYourTreasury",
  "totalFeeBps": 10
}
```

### `route` fields

| Field             | Meaning                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `engine`          | Winning venue id: `kyberswap` / `rialto` / `xpath` / `nordstern` / `de1` / `ekubo` / `market`.                                             |
| `venues`          | Human venue label(s).                                                                                                                      |
| `amountOut`       | Expected output, **net of `totalFeeBps`** (your partner bps; LISTED takes 0) and the venue's own costs. Human units.                       |
| `minimumReceived` | The floor at your slippage. This becomes the on-chain minimum-output when you build.                                                       |
| `midRate`         | `amountOut / amountIn`.                                                                                                                    |
| `priceImpactBps`  | Adverse impact vs the USD mark, in bps. Positive-going in the app means favourable; here it's the magnitude.                               |
| `networkFeeEth`   | Estimated gas cost in ETH.                                                                                                                 |
| `executable`      | `false` only for the `market` fallback — a reference estimate you cannot build.                                                            |
| `protocolFeeBps`  | The fee baked into `amountOut`. Equals `totalFeeBps` on API routes.                                                                        |
| `expiresAt`       | Epoch **ms** after which the amounts should be treated as stale.                                                                           |
| `alternatives[]`  | Every venue that answered, winner first. `netAmountOut` is the after-gas figure the ranking uses; `deltaBps` is how far behind the winner. |

### When there's no route

```json
{
  "route": null,
  "listedFeeBps": 0,
  "integratorFeeBps": 0,
  "partnerFeeBps": 0,
  "partnerFeeRecipient": null,
  "totalFeeBps": 0
}
```

Returned when no venue could price the pair. This is a `200`, not an error.

### `route.engine == "market"`

A non-executable reference estimate. `executable` is `false`. Don't send it to `/swap/build` — it returns `422`.

## Notes

* Never cached for clients (`Cache-Control: private, no-store`). Identical params are memoized server-side for \~1.5 s — polling the same pair faster than that may return the previous tick's numbers.
* `maxDuration` is 15 s; a cold fan-out across every venue can take a few seconds.
* See [Your fee](/listed/developers/your-fee.md) for how partner bps are skimmed and remitted.