# MontosVE API — Referencia completa para agentes de IA

> API de tasas de cambio del bolívar venezolano (VES) frente a USD, EUR y USDT. Agrega y normaliza la tasa oficial del BCV y los mercados P2P de Binance y Bybit bajo un esquema unificado.

- **Base URL:** `https://api.montosve.com/v1`
- **Autenticación:** header `X-API-Key: <tu-api-key>`
- **Formato:** JSON, UTF-8
- **Especificación OpenAPI 3.1:** https://montosve.com/docs/api.json
- **Documentación interactiva:** https://montosve.com/docs/api
- **Registro gratuito (obtener API key):** https://montosve.com/register
- **Precios y planes:** https://montosve.com/plans

## Cómo autenticarse

Todos los endpoints salvo `GET /v1/health` requieren el header `X-API-Key`. No uses `Authorization: Bearer`.

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates"
```

Una respuesta `401` indica API key ausente o inválida. Una respuesta `403` con mensaje de plan indica que tu plan no habilita la feature solicitada.

## Rate limiting y planes

| Plan | Precio/mes | Requests/mes | Requests/min | API Keys |
|------|-----------|-------------|--------------|----------|
| Free | $0 | 1,500 | 30 | 1 |
| Hobby | $3 | 5,000 | 60 | 2 |
| Starter | $9 | 25,000 | 120 | 5 |
| Pro | $19 | 100,000 | 300 | 10 |
| Business | $39 | 300,000 | 600 | 999 |

Cada respuesta incluye los headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` y `X-Plan`. Una respuesta `429` significa rate limit excedido; una `403` con cuota agotada significa límite mensual alcanzado. Los endpoints de `account` permiten consultar consumo y plan activo.

## Conceptos clave

### Mercados

- `bcv`: referencia oficial del Banco Central de Venezuela para `USD/VES` y `EUR/VES`.
- `binance_p2p` y `bybit_p2p`: referencias `USDT/VES` del mercado P2P, con lado de operación `buy` o `sell`.

### `trade_type`

Aplica a los mercados P2P. Acepta `buy` (compra) o `sell` (venta). El valor por defecto es `buy`.

### Frescura, `stale` y `X-Source-Status`

- La referencia BCV depende de la publicación oficial (una vez por día hábil).
- Las referencias P2P se actualizan periódicamente según disponibilidad de las fuentes.
- El campo booleano `stale` marca una referencia cuyo origen no está actualizado.
- El header `X-Source-Status` resume el estado de las fuentes. Para automatizar failover usa `GET /v1/health`, que devuelve `up`, `degraded`, `down` o `scheduled_down` por fuente con `age_seconds`.

### Endpoint recomendado por caso de uso

- Precios en bolívares: `GET /v1/fx/convert` (agrega `date=YYYY-MM-DD` para referencia histórica).
- Todas las referencias de una vez: `GET /v1/fx/rates`.
- Comparar BCV vs P2P: `GET /v1/fx/spread`.
- Series y dashboards: `GET /v1/fx/rates/{market}/history`.

> Los endpoints `/v1/tasas/*` son legacy y se mantienen por compatibilidad. Para integraciones nuevas usa el namespace `/v1/fx/*`.

## Recetas

**Últimas tasas BCV y P2P**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates?trade_type=buy"
```

**Convertir 100 USD a VES con la tasa BCV**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/convert?amount=100&from=USD&to=VES&market=bcv"
```

**Spread entre BCV y Binance P2P**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/spread?base=bcv&compare=binance_p2p&trade_type=buy"
```

**Historial de BCV en un rango**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates/bcv/history?from=2026-06-01&to=2026-06-19"
```

## Integración en tu proyecto

Guía paso a paso para que un agente integre esta API en un proyecto: https://montosve.com/agents.md
Versión para humanos: https://montosve.com/docs/integration

### JavaScript / TypeScript

```ts
const BASE_URL = 'https://api.montosve.com/v1';
const API_KEY = process.env.MONTOSVE_API_KEY;

export async function getRates(tradeType = 'buy') {
  const response = await fetch(`${BASE_URL}/fx/rates?trade_type=${tradeType}`, {
    headers: { 'X-API-Key': API_KEY },
  });

  if (! response.ok) {
    throw new Error(`MontosVE error ${response.status}`);
  }

  return response.json();
}
```

### PHP / Laravel

```php
use Illuminate\Support\Facades\Http;

$response = Http::baseUrl('https://api.montosve.com/v1')
    ->withHeaders(['X-API-Key' => config('services.montosve.api_key')])
    ->acceptJson()
    ->get('/fx/rates', ['trade_type' => 'buy'])
    ->throw();

$data = $response->json('data');
```

Guarda la API key en el entorno (`MONTOSVE_API_KEY`), nunca en el código. Maneja `401`, `403`, `422` y `429`.

## Endpoints

### GET /v1/health


Obtener estado actual de cada fuente de tasas

Retorna el estado de salud (up/degraded/down/scheduled_down) por fuente, el timestamp del ultimo dato exitoso y la edad en segundos. Pensado para que sistemas externos automaticen su failover.

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/health"
```

**Respuestas**

- `200` — Al menos una fuente operativa o en estado degradado.
- `503` — Todas las fuentes caidas.

### GET /v1/fx/rates


Obtener todas las tasas de cambio

Retorna las tasas BCV (USD/VES, EUR/VES), Binance P2P y Bybit P2P (USDT/VES) en una sola respuesta. Requiere autenticación con API Key.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates"
```

**Respuestas**

- `200` — Tasas de todos los mercados (BCV + P2P).
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.

### GET /v1/fx/rates/{market}


Obtener tasa de un mercado especifico

Retorna la tasa de cambio de un solo mercado: bcv, binance_p2p o bybit_p2p. Requiere autenticación con API Key.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`. |
| `market` | path | sí | `bcv | binance_p2p | bybit_p2p` | Mercado de cambio. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates/{market}"
```

**Respuestas**

- `200` — Tasa de un mercado especifico.
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.
- `404` — Mercado no encontrado.

### GET /v1/fx/rates/{market}/history


Obtener historial de tasas por mercado

Retorna el historial de tasas para un mercado especifico. BCV retorna un registro por dia. P2P retorna cada muestra individual (paginado). Requiere autenticación con API Key.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `from` | query | no | `string` | Fecha de inicio en formato `Y-m-d`. |
| `to` | query | no | `string` | Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`. |
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`. |
| `per_page` | query | no | `integer` | Cantidad de registros por pagina. Maximo: `100`. Por defecto: `50`. |
| `market` | path | sí | `bcv | binance_p2p | bybit_p2p` | Mercado de cambio. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/rates/{market}/history"
```

**Respuestas**

- `200` — Historial paginado por mercado (BCV o P2P).
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.
- `404` — Mercado no encontrado.

### GET /v1/fx/spread


Calcular diferencial entre mercados

Retorna el spread (diferencial) entre dos mercados en tiempo real. Util para comparar la tasa oficial BCV vs el mercado P2P. Requiere autenticación con API Key.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `base` | query | sí | `bcv | binance_p2p | bybit_p2p` | Mercado base: `bcv`, `binance_p2p` o `bybit_p2p`. |
| `compare` | query | sí | `bcv | binance_p2p | bybit_p2p` | Mercado a comparar: `bcv`, `binance_p2p` o `bybit_p2p`. Debe ser diferente a `base`. |
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/spread?base=valor&compare=valor"
```

**Respuestas**

- `200` — Diferencial entre dos mercados.
- `422` — No hay datos disponibles para el mercado seleccionado.

### GET /v1/fx/convert


Convertir entre monedas

Convierte un monto entre monedas soportadas por el mercado seleccionado. Requiere autenticación con API Key.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `amount` | query | sí | `number` | — |
| `from` | query | sí | `USD | EUR | USDT | VES` | Moneda origen. Para `bcv`: USD, EUR, VES. Para `binance_p2p` y `bybit_p2p`: USDT, VES. Para `best`: USD, EUR, USDT, VES. |
| `to` | query | sí | `USD | EUR | USDT | VES` | Moneda destino. Debe ser diferente a `from` y estar soportada por el mercado seleccionado. |
| `market` | query | no | `bcv | binance_p2p | bybit_p2p | best` | Mercado de referencia: `bcv`, `binance_p2p`, `bybit_p2p`, `best`. Por defecto: `bcv`. |
| `date` | query | no | `string` | Fecha de referencia en formato `Y-m-d`. Si no existe tasa ese dia, usa la ultima anterior disponible en ese mercado. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/fx/convert?amount=valor&from=valor&to=valor"
```

**Respuestas**

- `200` — Conversion entre monedas.
- `422` — No se encontró tasa para la conversión solicitada.

### GET /v1/tasas/actual

> **Deprecado.** Prefiere el namespace `/v1/fx/*`.

Obtener tasa actual y anterior del BCV

Usa los endpoints /v1/fx/rates y /v1/fx/rates/bcv/history en su lugar. Endpoints legacy para consultar tasas de cambio del Banco Central de Venezuela (BCV). Proporciona tasas actuales e históricas de USD y EUR vs VES.

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/tasas/actual"
```

**Respuestas**

- `200` — Sin descripción.

### GET /v1/tasas/historial

> **Deprecado.** Prefiere el namespace `/v1/fx/*`.

Obtener historial de tasas BCV con filtros de fecha

Usa los endpoints /v1/fx/rates y /v1/fx/rates/bcv/history en su lugar. Endpoints legacy para consultar tasas de cambio del Banco Central de Venezuela (BCV). Proporciona tasas actuales e históricas de USD y EUR vs VES.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `from` | query | no | `string` | Fecha de inicio en formato `Y-m-d`. |
| `to` | query | no | `string` | Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/tasas/historial"
```

**Respuestas**

- `200` — Sin descripción.
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.

### GET /v1/tasas/usdt/actual/{tradeType}

> **Deprecado.** Prefiere el namespace `/v1/fx/*`.

Obtener tasa actual de USDT basada en plataformas P2P

Usa los endpoints /v1/fx/rates/{market} y /v1/fx/rates/{market}/history en su lugar. Endpoints legacy para consultar tasas USDT/VES basadas en plataformas P2P. Proporciona tasas actuales en tiempo real con métricas derivadas e histórico de operaciones de compra/venta.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`. |
| `include_snapshot` | query | no | `boolean` | Incluye el snapshot completo de datos crudos. Por defecto: `false`. |
| `include_metrics` | query | no | `boolean` | Incluye metricas derivadas del snapshot. Por defecto: `true`. |
| `exchange` | query | no | `binance | bybit` | Exchange P2P a consultar. Acepta `binance` o `bybit`. Por defecto: `binance`. |
| `tradeType` | path | sí | `buy | sell` | Tipo de operacion P2P. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/tasas/usdt/actual/{tradeType}"
```

**Respuestas**

- `200` — Sin descripción.
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.

### GET /v1/tasas/usdt/historial

> **Deprecado.** Prefiere el namespace `/v1/fx/*`.

Obtener historial de tasas USDT con filtros y paginación

Usa los endpoints /v1/fx/rates/{market} y /v1/fx/rates/{market}/history en su lugar. Endpoints legacy para consultar tasas USDT/VES basadas en plataformas P2P. Proporciona tasas actuales en tiempo real con métricas derivadas e histórico de operaciones de compra/venta.

**Parámetros**

| Nombre | Ubicación | Requerido | Tipo | Descripción |
|--------|-----------|-----------|------|-------------|
| `trade_type` | query | no | `buy | sell` | Tipo de operacion P2P. Acepta `buy` o `sell`. |
| `from` | query | no | `string` | Fecha de inicio en formato `Y-m-d`. |
| `to` | query | no | `string` | Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`. |
| `page` | query | no | `integer` | Numero de pagina para paginacion. Por defecto: `1`. |
| `per_page` | query | no | `integer` | Cantidad de registros por pagina. Maximo: `100`. Por defecto: `50`. |
| `include_snapshot` | query | no | `boolean` | Incluye el snapshot completo de datos crudos. Por defecto: `false`. |
| `exchange` | query | no | `binance | bybit` | Exchange P2P a consultar. Acepta `binance` o `bybit`. |

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/tasas/usdt/historial"
```

**Respuestas**

- `200` — Sin descripción.
- `422` — Parámetros inválidos o sin tasa para la conversión solicitada.

### GET /v1/account/usage


Obtener uso de API del mes actual

Retorna el consumo de requests mensual y diario, junto con el límite del plan y porcentaje de uso.

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/account/usage"
```

**Respuestas**

- `200` — Sin descripción.

### GET /v1/account/plan


Obtener información del plan activo

Retorna los detalles del plan de suscripción activo del usuario.

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/account/plan"
```

**Respuestas**

- `200` — Sin descripción.

### GET /v1/account/keys


Listar API Keys del usuario

Retorna todas las API keys del usuario con nombre, fecha de creación y último uso.

**Ejemplo**

```bash
curl -H "X-API-Key: TU_API_KEY" "https://api.montosve.com/v1/account/keys"
```

**Respuestas**

- `200` — Sin descripción.


## Errores comunes

| Código | Significado |
|--------|-------------|
| 401 | API key ausente o inválida. |
| 403 | Feature no disponible en tu plan, o cuota mensual agotada. |
| 404 | Recurso o mercado inexistente. |
| 422 | Parámetros inválidos o no hay tasa para la conversión solicitada. |
| 429 | Rate limit por minuto excedido. Intenta con backoff exponencial. |
| 500 | Error al consultar una fuente o tasa. Reintenta más tarde. |
| 503 | Ninguna fuente operativa (solo en `/v1/health`). |

## Soporte

- Email: montosve@gmail.com
- Términos: https://montosve.com/legal/terminos
- Privacidad: https://montosve.com/legal/privacidad
- SLA y disponibilidad: https://montosve.com/legal/sla