# 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
- Servidor MCP (solo lectura, beta): https://montosve.com/mcp

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

## MCP (beta, solo lectura)

Servidor MCP para que tu agente consulte las tasas en vivo, sin escribir código:

- Página con guía y configuración por cliente: https://montosve.com/mcp
- Endpoint: `https://api.montosve.com/mcp`
- Autenticación: usa tu API key como header `Authorization: Bearer <api-key>` o `X-API-Key: <api-key>`
- Tools: `get-fx-rates`, `get-market-rate`, `get-spread`, `convert-currency`, `get-rate-history`, `get-source-health`
- Resources: `montosve://rates/current` (tasas actuales en JSON) y `montosve://docs/llms-full` (documentación completa en Markdown)
- Prompts: `convert-prices-to-ves` (convierte una lista de precios a VES con la tasa BCV)
- opencode usa `"type": "remote"` + `"enabled"`; Cursor, Claude Code y VS Code usan `"mcpServers"`. Ejemplos por cliente: https://montosve.com/mcp
- El acceso está limitado a usuarios beta; el uso cuenta contra tu cuota mensual solo en llamadas a tools (`tools/call`).

## Webhooks (Pro y Business)

Avisos push firmados, sin polling. Se configuran en https://montosve.com/developer/webhooks.

- Eventos: `rate.bcv.updated`, `rate.p2p.updated` (con umbral), `source.status_changed`, `api.quota.warning`, `api.quota.exceeded`, `api.key.expiring`.
- Firma: HMAC SHA-256 sobre `"{timestamp}.{body}"` en el header `X-MontosVE-Signature` (junto a `X-MontosVE-Event` y `X-MontosVE-Timestamp`).
- Reintentos automaticos (4 intentos, backoff 10/60/300s) e historial de entregas.
- Pagina del producto: https://montosve.com/webhooks
- Guia con payload y verificacion de firma: https://montosve.com/agents.md

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