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

# Migrate Cotizave API V1 to V2

> Map Venezuela V1 routes, fields, and rate IDs to V2 while preserving existing application behavior during migration.

V1 is deprecated. V2 preserves V1 data in equivalent Venezuelan operations and adds global IDs and countries. You can keep your V1 integration active while adapting routes.

## Route changes

| V1 | V2 equivalent |
| - | - |
| `GET /v1/fx/rates` | `GET /v2/fx/ve/rates` |
| `GET /v1/fx/rates/{market}` | `GET /v2/fx/ve/rates/{id}`; also accepts the local market as an alias |
| `GET /v1/fx/rates/{market}/history` | `GET /v2/fx/ve/rates/{id}/history` |
| `GET /v1/fx/convert` | `GET /v2/fx/convert` |
| `POST /v1/fx/bulk/convert` | `POST /v2/fx/convert` |
| `GET /v1/fx/markets`, `/spread`, `/route` | `GET /v2/fx/ve/markets`, `/spread`, `/route` |
| `GET /v1/fx/bcv/banks` | `GET /v2/fx/ve/bank-rates` |
| `GET /v1/fx/index` | `index` inside `GET /v2/fx/ve/rates` |

The flat `/v1/fx/bcv/currencies` table has no identical V2 JSON response. Keep that V1 request if you depend on its exact shape. Review [all V2 endpoints](https://docs.cotizave.com/en/api/v2/endpoints.md) before changing a route.

## Reusable fields

| V1 | V2 | Use |
| - | - | - |
| `market` | `market` | Keeps the local identifier in VE (`binance`, `reference`, etc.). |
| — | `id` | Global ID for V2 routes (`ve-binance`, `ve-bcv`). Do not derive it from `market`. |
| `type` | `type` | Retains V1 types in VE, such as `p2p` and `reference`. |
| `updated_at` | `updated_at` | Same source instant in RFC 3339; `index.as_of` keeps its own name. |
| `effective_date` | `effective_date` | Value date, distinct from `updated_at`. |
| `base`, `mid`, `bid`, `ask`, `stale_after_sec` | Same | VE Free rates retain V1 values and omission rules. |
| Conversion `stale`, `staleness_sec` | Same | Still present in Free conversion. Route options also keep `staleness_sec` when the plan permits that operation. |

## Venezuelan market mapping

These pairs come from Venezuela's public snapshot rate registry. Use the API's returned value; do not construct `id` from `market`. Additional BCV references have their own IDs and do not replace V1 markets.

| V1 `market` | V2 `id` |
| - | - |
| `reference` | `ve-bcv` |
| `eur_reference` | `ve-euro` |
| `parallel` | `ve-paralelo` |
| `binance` | `ve-binance` |
| `bybit` | `ve-bybit` |
| `okx` | `ve-okx` |
| `bitget` | `ve-bitget` |
| `mexc` | `ve-mexc` |
| `bingx` | `ve-bingx` |
| `saldo` | `ve-saldo` |
| `syklo` | `ve-syklo` |
| `yadio` | `ve-yadio` |
| `zelle` | `ve-zelle` |
| `paypal` | `ve-paypal` |
| `western_union` | `ve-wu` |
| `zoom` | `ve-zoom` |
| `cash` | `ve-cash` |
| `cucuta` | `ve-cucuta` |

Example V1 rate:

```json theme={null}
{"market":"binance","type":"p2p","base":"USD","mid":290.85,"bid":290.4,"ask":291.3,"updated_at":"2026-10-22T12:58:40Z"}
```

The same rate in V2 Free adds `id`:

```json theme={null}
{"id":"ve-binance","market":"binance","type":"p2p","base":"USD","mid":290.85,"bid":290.4,"ask":291.3,"updated_at":"2026-10-22T12:58:40Z"}
```

Basic adds identity and freshness metadata to `/rates`; Growth adds descriptions and analysis; Pro retains those fields and enables more operations. See the [plan matrix](https://docs.cotizave.com/en/api/v2/plans.md). In V2, `category` remains a **query filter** (`?category=crypto_p2p`), but the rate JSON uses `type: "p2p"`. Do not substitute `effective_date` or `fetched_at` for `updated_at`.

The `/markets` catalogue differs: V2 `required_plan` is an internal plan ID, while V1 can use a display name or `null`. Adapt clients that consume this field. V2 rate JSON does not emit `category` or `as_of`: use `type` and `updated_at`. The `index.as_of` field belongs only to the index inherited from V1.


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