{ "openapi": "3.1.0", "info": { "title": "MontosVE API", "version": "1.0.0", "description": "API de tasas de cambio venezolanas con referencias BCV, Binance P2P y Bybit P2P bajo un schema unificado.\n\n## Namespace recomendado: `\/v1\/fx\/`\nLos endpoints bajo `\/v1\/fx\/` son los recomendados para nuevas integraciones.\nLos endpoints `\/v1\/tasas\/` siguen disponibles por compatibilidad, pero el namespace nuevo concentra tasas, conversiones, spread e historial.\n\n## Autenticacion\n**Todos** los endpoints requieren el header `X-API-Key` con un token valido.\nRegistrate gratis en [montosve.com\/register](\/register) para obtener tu API key.\n\n```bash\ncurl -H \"X-API-Key: TU_API_KEY\" \"\/v1\/fx\/rates\"\n```\n\n## Endpoints principales\n| Endpoint | Descripcion |\n|----------|------------|\n| `GET \/v1\/fx\/rates` | Todas las referencias disponibles en una sola llamada |\n| `GET \/v1\/fx\/rates\/{market}` | Tasa de un mercado especifico |\n| `GET \/v1\/fx\/rates\/{market}\/history` | Historial por mercado |\n| `GET \/v1\/fx\/spread` | Diferencial entre mercados |\n| `GET \/v1\/fx\/convert` | Conversion entre monedas |\n\n## Como interpretar los mercados\n- **BCV**: referencia oficial para USD\/VES y EUR\/VES.\n- **Binance P2P** y **Bybit P2P**: referencias USDT\/VES de mercado.\n- **`trade_type`**: indica el lado del mercado P2P documentado por el endpoint cuando aplica.\n- **`date` en `\/v1\/fx\/convert`**: acepta formato `Y-m-d` y, si no hay tasa ese dia, usa la ultima anterior disponible para ese mercado.\n- **`timestamp`** y **`updated_at`**: ayudan a saber cuando fue generada o actualizada la referencia que recibiste.\n\n## Frescura y degradacion controlada\n- La referencia **BCV** depende de la publicacion oficial del banco.\n- Las referencias **P2P** se actualizan periodicamente segun la disponibilidad de las fuentes de mercado.\n- Si una fuente no esta disponible temporalmente, otras fuentes pueden seguir apareciendo en respuestas agregadas.\n- Cuando consultas un mercado puntual y no hay referencia disponible en ese momento, la respuesta puede venir sin registros para ese mercado en lugar de inventar un valor.\n- La politica operativa y alcance de disponibilidad estan documentados en [Politica de Disponibilidad](\/legal\/sla).\n\n## Recipes rapidos\n- **Mostrar precios en bolivares**: usa `GET \/v1\/fx\/convert` y agrega `date=Y-m-d` cuando necesites una referencia historica.\n- **Guardar referencia oficial con trazabilidad**: usa `GET \/v1\/fx\/rates`.\n- **Comparar BCV vs P2P**: usa `GET \/v1\/fx\/spread`.\n- **Construir dashboards o series internas**: usa `GET \/v1\/fx\/rates\/{market}\/history`.\n\n## Planes\n| Plan | Requests\/mes | Rate\/min | API Keys | Precio |\n|------|-------------|----------|----------|--------|\n| Free | 1,500 | 30 | 1 | $0 |\n| Hobby | 5,000 | 60 | 2 | $3\/mes |\n| Starter | 25,000 | 120 | 5 | $9\/mes |\n| Pro | 100,000 | 300 | 10 | $19\/mes |\n| Business | 300,000 | 600 | Ilimitadas | $39\/mes |\n\n## Rate Limiting\nLas respuestas incluyen headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-Plan`.\nCada plan tiene un limite mensual de requests y un rate limit por minuto." }, "servers": [ { "url": "https:\/\/api.montosve.com\/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "\/account\/usage": { "get": { "operationId": "account.usage", "description": "Retorna el consumo de requests mensual y diario, junto con el l\u00edmite del plan y porcentaje de uso.", "summary": "Obtener uso de API del mes actual", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } } } } }, "\/account\/plan": { "get": { "operationId": "account.plan", "description": "Retorna los detalles del plan de suscripci\u00f3n activo del usuario.", "summary": "Obtener informaci\u00f3n del plan activo", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } } } } }, "\/account\/keys": { "get": { "operationId": "account.keys", "description": "Retorna todas las API keys del usuario con nombre, fecha de creaci\u00f3n y \u00faltimo uso.", "summary": "Listar API Keys del usuario", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } } } } }, "\/fx\/convert": { "get": { "operationId": "fxConvert", "description": "Convierte un monto entre monedas soportadas por el mercado seleccionado.\nRequiere autenticaci\u00f3n con API Key.", "summary": "Convertir entre monedas", "tags": [ "FxConvert" ], "parameters": [ { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0.01 } }, { "name": "from", "in": "query", "required": true, "description": "Moneda origen. Para `bcv`: USD, EUR, VES. Para `binance_p2p` y `bybit_p2p`: USDT, VES. Para `best`: USD, EUR, USDT, VES.", "schema": { "type": "string", "enum": [ "USD", "EUR", "USDT", "VES" ] }, "example": "USD" }, { "name": "to", "in": "query", "required": true, "description": "Moneda destino. Debe ser diferente a `from` y estar soportada por el mercado seleccionado.", "schema": { "type": "string", "enum": [ "USD", "EUR", "USDT", "VES" ] }, "example": "VES" }, { "name": "market", "in": "query", "description": "Mercado de referencia: `bcv`, `binance_p2p`, `bybit_p2p`, `best`. Por defecto: `bcv`.", "schema": { "type": "string", "enum": [ "bcv", "binance_p2p", "bybit_p2p", "best" ] }, "example": "bcv" }, { "name": "date", "in": "query", "description": "Fecha de referencia en formato `Y-m-d`. Si no existe tasa ese dia, usa la ultima anterior disponible en ese mercado.", "schema": { "type": "string" }, "example": "2026-06-19" } ], "responses": { "200": { "description": "Conversion entre monedas.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "amount": { "type": "number" }, "converted_amount": { "type": "number" }, "rate": { "type": "number" }, "market": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "from", "to", "amount", "converted_amount", "rate", "market", "timestamp" ] } } } }, "422": { "description": "No se encontr\u00f3 tasa para la conversi\u00f3n solicitada.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/fx\/rates\/{market}\/history": { "get": { "operationId": "fxHistory", "description": "Retorna el historial de tasas para un mercado especifico.\nBCV retorna un registro por dia. P2P retorna cada muestra individual (paginado).\nRequiere autenticaci\u00f3n con API Key.", "summary": "Obtener historial de tasas por mercado", "tags": [ "FxHistory" ], "parameters": [ { "name": "from", "in": "query", "description": "Fecha de inicio en formato `Y-m-d`.", "schema": { "type": "string" }, "example": "2026-06-01" }, { "name": "to", "in": "query", "description": "Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`.", "schema": { "type": "string" }, "example": "2026-06-19" }, { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" }, { "name": "per_page", "in": "query", "description": "Cantidad de registros por pagina. Maximo: `100`. Por defecto: `50`.", "schema": { "type": "integer" }, "example": 50 }, { "name": "market", "in": "path", "required": true, "description": "Mercado de cambio.", "schema": { "type": "string", "enum": [ "bcv", "binance_p2p", "bybit_p2p" ] } } ], "responses": { "200": { "description": "Historial paginado por mercado (BCV o P2P).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "usd_rate": { "type": "number" }, "eur_rate": { "type": "number" }, "rate": { "type": "number" }, "best_rate": { "type": "number" }, "currency_pair": { "type": "string" } }, "required": [ "date" ] } }, "meta": { "type": "object", "properties": { "market": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" } }, "required": [ "market", "total", "current_page", "last_page", "per_page" ] }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "last": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "first", "last" ] } }, "required": [ "data", "meta", "links" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "description": "Mercado no encontrado.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "available_markets": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "available_markets" ] } } } } } } }, "\/fx\/rates": { "get": { "operationId": "fxRates.index", "description": "Retorna las tasas BCV (USD\/VES, EUR\/VES), Binance P2P y Bybit P2P (USDT\/VES) en una sola respuesta.\nRequiere autenticaci\u00f3n con API Key.", "summary": "Obtener todas las tasas de cambio", "tags": [ "FxRates" ], "parameters": [ { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" } ], "responses": { "200": { "description": "Tasas de todos los mercados (BCV + P2P).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "type": { "type": "string" }, "currency_pair": { "type": "string" }, "rate": { "type": "number" }, "previous_rate": { "type": "number" }, "previous_date": { "type": "string" }, "change_percentage": { "type": "number" }, "date": { "type": "string" }, "best_rate": { "type": "number" }, "trade_type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "market", "type", "currency_pair", "rate", "updated_at" ] } }, "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "sources_count": { "type": "integer" } }, "required": [ "timestamp", "sources_count" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/fx\/rates\/{market}": { "get": { "operationId": "fxRates.show", "description": "Retorna la tasa de cambio de un solo mercado: bcv, binance_p2p o bybit_p2p.\nRequiere autenticaci\u00f3n con API Key.", "summary": "Obtener tasa de un mercado especifico", "tags": [ "FxRates" ], "parameters": [ { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" }, { "name": "market", "in": "path", "required": true, "description": "Mercado de cambio.", "schema": { "type": "string", "enum": [ "bcv", "binance_p2p", "bybit_p2p" ] } } ], "responses": { "200": { "description": "Tasa de un mercado especifico.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "type": { "type": "string" }, "currency_pair": { "type": "string" }, "rate": { "type": "number" }, "previous_rate": { "type": "number" }, "previous_date": { "type": "string" }, "change_percentage": { "type": "number" }, "date": { "type": "string" }, "best_rate": { "type": "number" }, "trade_type": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "market", "type", "currency_pair", "rate", "updated_at" ] } }, "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "sources_count": { "type": "integer" } }, "required": [ "timestamp", "sources_count" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "description": "Mercado no encontrado.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "available_markets": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "available_markets" ] } } } } } } }, "\/fx\/spread": { "get": { "operationId": "fxSpread", "description": "Retorna el spread (diferencial) entre dos mercados en tiempo real.\nUtil para comparar la tasa oficial BCV vs el mercado P2P.\nRequiere autenticaci\u00f3n con API Key.", "summary": "Calcular diferencial entre mercados", "tags": [ "FxSpread" ], "parameters": [ { "name": "base", "in": "query", "required": true, "description": "Mercado base: `bcv`, `binance_p2p` o `bybit_p2p`.", "schema": { "type": "string", "enum": [ "bcv", "binance_p2p", "bybit_p2p" ] }, "example": "bcv" }, { "name": "compare", "in": "query", "required": true, "description": "Mercado a comparar: `bcv`, `binance_p2p` o `bybit_p2p`. Debe ser diferente a `base`.", "schema": { "type": "string", "enum": [ "bcv", "binance_p2p", "bybit_p2p" ] }, "example": "binance_p2p" }, { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" } ], "responses": { "200": { "description": "Diferencial entre dos mercados.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "base": { "type": "object", "properties": { "market": { "type": "string" }, "rate": { "type": "number" }, "currency_pair": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "market", "rate", "currency_pair", "updated_at" ] }, "compare": { "type": "object", "properties": { "market": { "type": "string" }, "rate": { "type": "number" }, "currency_pair": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "market", "rate", "currency_pair", "updated_at" ] }, "spread": { "type": "object", "properties": { "absolute": { "type": "number" }, "percentage": { "type": "number" }, "direction": { "type": "string" } }, "required": [ "absolute", "percentage", "direction" ] }, "timestamp": { "type": "string" } }, "required": [ "base", "compare", "spread", "timestamp" ] } } } }, "422": { "description": "No hay datos disponibles para el mercado seleccionado.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "market": { "type": "string" } }, "required": [ "message", "market" ] } } } } } } }, "\/health": { "get": { "operationId": "health.check", "description": "Retorna el estado de salud (up\/degraded\/down\/scheduled_down) por fuente,\nel timestamp del ultimo dato exitoso y la edad en segundos. Pensado\npara que sistemas externos automaticen su failover.", "summary": "Obtener estado actual de cada fuente de tasas", "tags": [ "Health" ], "responses": { "200": { "description": "Al menos una fuente operativa o en estado degradado.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "checked_at": { "type": "string" }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "status": { "type": "string" }, "last_success_at": { "type": [ "string", "null" ] }, "age_seconds": { "type": [ "integer", "null" ] }, "note": { "type": [ "string", "null" ] } }, "required": [ "status", "last_success_at", "age_seconds", "note" ] } } }, "required": [ "status", "checked_at", "sources" ] } } } }, "503": { "description": "Todas las fuentes caidas.", "content": { "application\/json": { "schema": { "type": "string" } } } } } } }, "\/tasas\/actual": { "get": { "operationId": "tasa.index", "description": "Usa los endpoints \/v1\/fx\/rates y \/v1\/fx\/rates\/bcv\/history en su lugar.\n\nEndpoints legacy para consultar tasas de cambio del Banco Central de Venezuela (BCV).\nProporciona tasas actuales e hist\u00f3ricas de USD y EUR vs VES.\n\n", "summary": "Obtener tasa actual y anterior del BCV", "deprecated": true, "tags": [ "Tasa" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } } } } }, "\/tasas\/historial": { "get": { "operationId": "tasa.historial", "description": "Usa los endpoints \/v1\/fx\/rates y \/v1\/fx\/rates\/bcv\/history en su lugar.\n\nEndpoints legacy para consultar tasas de cambio del Banco Central de Venezuela (BCV).\nProporciona tasas actuales e hist\u00f3ricas de USD y EUR vs VES.\n\n", "summary": "Obtener historial de tasas BCV con filtros de fecha", "deprecated": true, "tags": [ "Tasa" ], "parameters": [ { "name": "from", "in": "query", "description": "Fecha de inicio en formato `Y-m-d`.", "schema": { "type": "string" }, "example": "2024-01-01" }, { "name": "to", "in": "query", "description": "Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`.", "schema": { "type": "string" }, "example": "2024-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/tasas\/usdt\/actual\/{tradeType}": { "get": { "operationId": "usdtTasa.actual", "description": "Usa los endpoints \/v1\/fx\/rates\/{market} y \/v1\/fx\/rates\/{market}\/history en su lugar.\n\nEndpoints legacy para consultar tasas USDT\/VES basadas en plataformas P2P.\nProporciona tasas actuales en tiempo real con m\u00e9tricas derivadas e hist\u00f3rico de operaciones de compra\/venta.\n\n", "summary": "Obtener tasa actual de USDT basada en plataformas P2P", "deprecated": true, "tags": [ "UsdtTasa" ], "parameters": [ { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`. Por defecto: `buy`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" }, { "name": "include_snapshot", "in": "query", "description": "Incluye el snapshot completo de datos crudos. Por defecto: `false`.", "schema": { "type": "boolean" }, "example": false }, { "name": "include_metrics", "in": "query", "description": "Incluye metricas derivadas del snapshot. Por defecto: `true`.", "schema": { "type": "boolean" }, "example": true }, { "name": "exchange", "in": "query", "description": "Exchange P2P a consultar. Acepta `binance` o `bybit`. Por defecto: `binance`.", "schema": { "type": "string", "enum": [ "binance", "bybit" ] }, "example": "binance" }, { "name": "tradeType", "in": "path", "required": true, "description": "Tipo de operacion P2P.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "x-optional": true } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/tasas\/usdt\/historial": { "get": { "operationId": "usdtTasa.historial", "description": "Usa los endpoints \/v1\/fx\/rates\/{market} y \/v1\/fx\/rates\/{market}\/history en su lugar.\n\nEndpoints legacy para consultar tasas USDT\/VES basadas en plataformas P2P.\nProporciona tasas actuales en tiempo real con m\u00e9tricas derivadas e hist\u00f3rico de operaciones de compra\/venta.\n\n", "summary": "Obtener historial de tasas USDT con filtros y paginaci\u00f3n", "deprecated": true, "tags": [ "UsdtTasa" ], "parameters": [ { "name": "trade_type", "in": "query", "description": "Tipo de operacion P2P. Acepta `buy` o `sell`.", "schema": { "type": "string", "enum": [ "buy", "sell" ] }, "example": "buy" }, { "name": "from", "in": "query", "description": "Fecha de inicio en formato `Y-m-d`.", "schema": { "type": "string" }, "example": "2024-01-01" }, { "name": "to", "in": "query", "description": "Fecha de fin en formato `Y-m-d`. Debe ser igual o posterior a `from`.", "schema": { "type": "string" }, "example": "2024-01-31" }, { "name": "page", "in": "query", "description": "Numero de pagina para paginacion. Por defecto: `1`.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Cantidad de registros por pagina. Maximo: `100`. Por defecto: `50`.", "schema": { "type": "integer" }, "example": 20 }, { "name": "include_snapshot", "in": "query", "description": "Incluye el snapshot completo de datos crudos. Por defecto: `false`.", "schema": { "type": "boolean" }, "example": false }, { "name": "exchange", "in": "query", "description": "Exchange P2P a consultar. Acepta `binance` o `bybit`.", "schema": { "type": "string", "enum": [ "binance", "bybit" ] }, "example": "binance" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }