Bulk USD/VES conversion

POST /v1/fx/bulk/convert · Escala · One quota unit per batch. Additional limit: 300 calls per hour per account, shared across its keys.

Request

JSON field	Rule
`from`, `to`	`USD` → `VES` or `VES` → `USD`. EUR is unsupported.
`amounts`	Array of 1–50 finite numbers, greater than 0 and at most `1e12`.
`market`	Optional; defaults to `reference`. Must quote in USD and be included in your plan.

Send amounts and market. items and via are not fields of this endpoint. Unknown body fields may be ignored: via does not select a market. Remittance markets only support USD → VES; eur_reference is invalid here. 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/bulk/convert" \
  -H "X-API-Key: $COTIZAVE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"from":"USD","to":"VES","amounts":[100,250,500,1000],"market":"parallel"}'

import { cotizave } from './cotizave.mjs';

const data = await cotizave('/v1/fx/bulk/convert', {
  method: 'POST',
  body: {"from": "USD", "to": "VES", "amounts": [100, 250, 500, 1000], "market": "parallel"}
});
console.log(data);

from cotizave import cotizave

data = cotizave('/v1/fx/bulk/convert', method='POST', body={'from': 'USD', 'to': 'VES', 'amounts': [100, 250, 500, 1000], 'market': 'parallel'})
print(data)

Response

Illustrative response: figures and dates are not current quotes.

{
  "rate": 638.87,
  "market": "parallel",
  "type": "parallel",
  "updated_at": "2026-10-19T17:25:00Z",
  "results": [
    {
      "amount": 100,
      "result": 63887.0
    },
    {
      "amount": 250,
      "result": 159717.5
    },
    {
      "amount": 500,
      "result": 319435.0
    },
    {
      "amount": 1000,
      "result": 638870.0
    }
  ],
  "total_in": 1850,
  "total_out": 1181909.5
}

rate, market, type and updated_at describe the shared rate. results preserves the order of amounts; each item contains the input amount and its result, rounded to two decimal places. total_in sums inputs and total_out sums results. This endpoint does not return effective_date or stale. Headers: X-RateLimit-Cost: 1, X-Bulk-Operations with the number of amounts, and X-Bulk-RateLimit-Limit / X-Bulk-RateLimit-Remaining for the hourly limit.

Price lists and reports

Group up to 50 amounts with the same currency, market and valuation date. Match each result to its input by position. Do not recalculate past invoices using the current rate; retain the rate used when issuing them. For a large catalogue, you can also fetch one snapshot and calculate locally with an explicit rounding policy.

Errors

An invalid body, incompatible currency or more than 50 amounts returns 400. An empty array returns missing_field. An insufficient plan returns 402 feature_not_in_plan. The hourly limit returns 429 rate_limit_exceeded with Retry-After; do not assume every 429 includes X-RateLimit-Scope.

{"code":"invalid_format","message":"Max 50 amounts per request.","field":"amounts","details":{"max":50,"got":73}}

{"code":"feature_not_in_plan","message":"This feature ('bulk_convert') requires a plan upgrade.","details":{"feature":"bulk_convert","current_plan":"indie"}}

The common errors for authentication, quota and availability also apply. API error responses are JSON; branch on code, not on the text of message.

Notes

Each batch uses one rate; it does not mix markets. Conversion is an informational calculation: Cotizave does not execute payments or currency exchanges.

Documentation

Get started

API

Venezuela: endpoints

Indices

Guides

Bulk USD/VES conversion

Request

Response

Price lists and reports

Errors

Notes

​Request

​Response

​Price lists and reports

​Errors

​Notes

Request

Response

Price lists and reports

Errors

Notes