# MontosVE API

> API REST 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 de la API: `https://api.montosve.com/v1`. Todas las respuestas son JSON UTF-8. Todos los endpoints salvo `/v1/health` requieren el header `X-API-Key`. Obtén una API key gratis en https://montosve.com/register.

- Referencia completa para agentes (un solo archivo): https://montosve.com/llms-full.txt
- Guía de integración para agentes (snippets JS/TS y PHP/Laravel): https://montosve.com/agents.md
- Especificación OpenAPI 3.1: https://montosve.com/docs/api.json
- Documentación interactiva: https://montosve.com/docs/api
- Guía de integración para humanos: https://montosve.com/docs/integration

## Endpoints recomendados

- [Todas las tasas](https://montosve.com/docs/api): `GET /v1/fx/rates` — BCV, Binance P2P y Bybit P2P en una sola llamada. Acepta `trade_type=buy|sell`.
- [Tasa por mercado](https://montosve.com/docs/api): `GET /v1/fx/rates/{market}` — un solo mercado: `bcv`, `binance_p2p` o `bybit_p2p`.
- [Historial por mercado](https://montosve.com/docs/api): `GET /v1/fx/rates/{market}/history` — serie histórica. Acepta `from`, `to`, `trade_type`, `per_page`.
- [Spread](https://montosve.com/docs/api): `GET /v1/fx/spread` — diferencial entre dos mercados. Requiere `base` y `compare`.
- [Conversión](https://montosve.com/docs/api): `GET /v1/fx/convert` — convierte un monto. Requiere `amount`, `from`, `to`; opcional `market`, `date`.

## Estado y cuenta

- [Health](https://montosve.com/docs/api): `GET /v1/health` — estado de cada fuente (`up`, `degraded`, `down`, `scheduled_down`), público y sin consumir cuota. Úsalo para failover.
- [Uso](https://montosve.com/docs/api): `GET /v1/account/usage` — consumo mensual y diario contra el límite del plan.
- [Plan](https://montosve.com/docs/api): `GET /v1/account/plan` — plan activo y features habilitadas.
- [API Keys](https://montosve.com/docs/api): `GET /v1/account/keys` — lista las API keys del usuario.

## Endpoints legacy

Los siguientes endpoints se mantienen por compatibilidad; para integraciones nuevas usa el namespace `/v1/fx/*`.

- [Tasas BCV actuales](https://montosve.com/docs/api): `GET /v1/tasas/actual`.
- [Historial BCV](https://montosve.com/docs/api): `GET /v1/tasas/historial` — acepta `from`, `to`.
- [USDT P2P actual](https://montosve.com/docs/api): `GET /v1/tasas/usdt/actual/{tradeType}` — acepta `trade_type`, `exchange`, `include_metrics`, `include_snapshot`.
- [Historial USDT P2P](https://montosve.com/docs/api): `GET /v1/tasas/usdt/historial` — acepta `trade_type`, `exchange`, `from`, `to`, `per_page`, `include_snapshot`.

## Integración

- Guía paso a paso para agentes con snippets listos para copiar: https://montosve.com/agents.md
- Versión humana de la guía: https://montosve.com/docs/integration
- Guarda la API key en una variable de entorno (`MONTOSVE_API_KEY`), nunca en el código.

## Autenticación

Todas las requests a `/v1/*` menos `/v1/health` requieren el header:

```
X-API-Key: tu-api-key
```

Regístrate gratis en https://montosve.com/register para obtener tu key.

## Rate limiting

- El RPM y la cuota mensual varían según el plan (Free a Business).
- Headers de respuesta: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Plan`.
- Códigos: `401` key inválida, `403` feature o cuota, `429` rate limit excedido.

## Conceptos

- Mercados: `bcv` (oficial BCV), `binance_p2p` y `bybit_p2p` (USDT/VES P2P).
- `trade_type`: `buy` o `sell` para mercados P2P; por defecto `buy`.
- `stale` y `X-Source-Status` indican frescura de las fuentes.

## Opcional

- [Registro](https://montosve.com/register)
- [Planes y precios](https://montosve.com/plans)
- [Calculadora pública](https://montosve.com#calculator)
- [Términos](https://montosve.com/legal/terminos)
- [Privacidad](https://montosve.com/legal/privacidad)
- [SLA y disponibilidad](https://montosve.com/legal/sla)