Conversion route

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

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.

Run these examples on your server. JavaScript and Python use the clients in the quickstart; configure COTIZAVE_API_KEY there.

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"

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);

from cotizave import cotizave

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

Response

Illustrative response: figures and dates are not current quotes.

{
  "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.

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.

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.

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 for authentication, quota and availability also apply. API error responses are JSON; branch on code, not on the text of message.

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.

Documentation

Get started

API

Venezuela: endpoints

Indices

Guides

Request

Response

What direction does

Display options

Errors

Scope of the estimate

​Request

​Response

​What direction does

​Display options

​Errors

​Scope of the estimate

Request

Response

What direction does

Display options

Errors

Scope of the estimate