> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotizave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversion route

> Compare executable USD/VES markets and rank results by output amount.

`GET /v1/fx/route` · **Escala** · One quota unit. Estimates which compatible market would return the most destination currency using its `mid` rate.

<span id="request" />

## Request

| Parameter | Rule |
| - | - |
| `from`, `to` | Required: USD ↔ VES. |
| `amount` | Required: finite number, greater than 0 and at most `1e12`. |
| `direction` | `send` (default) or `receive`; validated and echoed back. |
| `max_staleness` | Seconds, a non-negative integer. `0` (default) disables the filter. |
| `format` | Defaults to JSON; see [formats](/en/api/formats). |

Run these examples on your server. JavaScript and Python use the clients in the [quickstart](/en/api/quickstart#paso-2); configure `COTIZAVE_API_KEY` there.

<CodeGroup>
  ```bash curl theme={null}
  curl --fail-with-body --max-time 10 "https://api.cotizave.com/v1/fx/route?from=USD&to=VES&amount=1000&direction=send&max_staleness=1800" \
    -H "X-API-Key: $COTIZAVE_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { cotizave } from './cotizave.mjs';

  const data = await cotizave('/v1/fx/route?from=USD&to=VES&amount=1000&direction=send&max_staleness=1800');
  console.log(data);
  ```

  ```python Python theme={null}
  from cotizave import cotizave

  data = cotizave('/v1/fx/route?from=USD&to=VES&amount=1000&direction=send&max_staleness=1800')
  print(data)
  ```
</CodeGroup>

<span id="response" />

## Response

Illustrative response: figures and dates are not current quotes.

```json theme={null}
{
  "from": {
    "currency": "USD",
    "amount": 1000
  },
  "direction": "send",
  "best": {
    "market": "bybit",
    "type": "p2p",
    "rate": 638.5,
    "amount": 638500,
    "updated_at": "2026-10-19T17:29:00Z",
    "staleness_sec": 15
  },
  "alternatives": [
    {
      "market": "binance",
      "type": "p2p",
      "rate": 637.87,
      "amount": 637870,
      "updated_at": "2026-10-19T17:29:00Z",
      "staleness_sec": 15
    }
  ],
  "skipped": [
    {
      "market": "reference",
      "reason": "not_executable"
    },
    {
      "market": "parallel",
      "reason": "not_executable"
    },
    {
      "market": "eur_reference",
      "reason": "currency_mismatch"
    }
  ],
  "fetched_at": "2026-10-19T17:29:15Z"
}
```

`from` is the input amount. `best` and each item in `alternatives` contain `market`, `type`, `rate`, `amount` (in the `to` currency), `updated_at` and `staleness_sec`. `fetched_at` identifies the snapshot. Optional `skipped` entries explain exclusions.

Exclusion reasons: `currency_mismatch`, `not_executable`, `feature_not_in_plan`, `one_way_market`, `no_quote` and `stale`. BCV and parallel are excluded because they are reference rates, not executable markets. Remittances only participate in USD → VES.

<span id="direction" />

## What direction does

`from` and `to` determine the operation. **Both `direction` values rank output amounts from highest to lowest**. USD → VES favours a higher `mid`; VES → USD favours a lower one. Ties favour the more recent quote. Changing only `direction` does not reverse the conversion or ranking.

<span id="casos-uso" />

## Display options

Display `best` and alternatives with the destination currency and quote age. Set `max_staleness` for your use case. Do not silently reintroduce a stale, excluded quote as a valid option.

<span id="errores" />

## Errors

* `400`: invalid input or an unknown parameter.
* `402 feature_not_in_plan`: missing access to `route`; plan information is under `details`.
* `422 no_route` with `field: max_staleness`: the age filter left no eligible routes.
* `503 service_unavailable`: no route is available.

The [common errors](/en/api/errors) for authentication, quota and availability also apply. API error responses are JSON; branch on `code`, not on the text of `message`.

<span id="notas" />

## Scope of the estimate

The API does not execute trades, include fees or check liquidity, provider limits or user eligibility. The number of markets can vary. A representative quote is not a binding exchange offer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.