> ## 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.

# Ruta de conversión

> Compara mercados ejecutables USD/VES y ordena los resultados por monto recibido.

`GET /v1/fx/route` · **Escala** · Una consulta de cuota. Estima qué mercado compatible daría más moneda destino, usando su tasa `mid`.

<span id="request" />

## Consulta

| Parámetro | Regla |
| - | - |
| `from`, `to` | Obligatorios: USD ↔ VES. |
| `amount` | Obligatorio: número finito, mayor que 0 y como máximo `1e12`. |
| `direction` | `send` (por defecto) o `receive`; se valida y devuelve como eco. |
| `max_staleness` | Segundos, entero no negativo. `0` (por defecto) desactiva el filtro. |
| `format` | JSON por defecto; consulta [formatos](/api/formats). |

Los ejemplos se ejecutan en el servidor. JavaScript y Python usan los clientes del [inicio rápido](/api/quickstart#paso-2); configura allí `COTIZAVE_API_KEY`.

<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" />

## Respuesta

Respuesta ilustrativa: las cifras y fechas no son cotizaciones actuales.

```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` es el importe de entrada. `best` y cada elemento de `alternatives` incluyen `market`, `type`, `rate`, `amount` (en la moneda `to`), `updated_at` y `staleness_sec`. `fetched_at` identifica el snapshot. `skipped` es opcional y explica los descartes.

Motivos de descarte: `currency_mismatch`, `not_executable`, `feature_not_in_plan`, `one_way_market`, `no_quote` y `stale`. BCV y paralelo se excluyen porque son referencias, no mercados ejecutables. Las remesas solo compiten en USD → VES.

<span id="direction" />

## Qué hace direction

`from` y `to` determinan la operación. **Ambos valores de `direction` ordenan por monto recibido, de mayor a menor**. USD → VES favorece un `mid` mayor; VES → USD, uno menor. En empate se prioriza la cotización más reciente. Cambiar únicamente `direction` no invierte la conversión ni el orden.

<span id="casos-uso" />

## Mostrar opciones

Muestra `best` y las alternativas con la moneda destino y su antigüedad. Define `max_staleness` según tu caso de uso. Si una cotización queda fuera por antigüedad, no la reincorpores silenciosamente como alternativa válida.

<span id="errores" />

## Errores

* `400`: entrada inválida o parámetro desconocido.
* `402 feature_not_in_plan`: falta acceso a `route`; los datos del plan están en `details`.
* `422 no_route` con `field: max_staleness`: el filtro de antigüedad dejó sin rutas elegibles.
* `503 service_unavailable`: no hay una ruta disponible.

Además pueden producirse los [errores comunes](/api/errors) de autenticación, cuota o disponibilidad. Las respuestas de error de la API son JSON; decide por `code`, no por el texto de `message`.

<span id="notas" />

## Alcance de la estimación

La API no ejecuta operaciones, no incluye comisiones y no comprueba liquidez, límites del proveedor ni elegibilidad del usuario. El número de mercados puede variar. Una tasa representativa no es una oferta vinculante de cambio.


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