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

# Bulk USD/VES conversion

> Convert 1–50 amounts using a single rate. Available on Escala.

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

<span id="request" />

## 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](/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/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"}'
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

<span id="response" />

## Response

Illustrative response: figures and dates are not current quotes.

```json theme={null}
{
  "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.

<span id="casos-uso" />

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

<span id="errores" />

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

```json theme={null}
{"code":"invalid_format","message":"Max 50 amounts per request.","field":"amounts","details":{"max":50,"got":73}}
```

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

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

## Notes

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


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