GET /v1/fx/rates/:market

Devuelve la cotización actualizada de un market específico. Útil cuando solo necesitas una tasa puntual y no quieres traer todas.

Request

GET /v1/fx/rates/:market HTTP/1.1
Host: api.cotizave.com
X-API-Key: nd-tu-api-key-aqui

Path parameters

Parámetro	Tipo	Requerido	Valores aceptados
`market`	string	Sí	`reference`, `parallel`, `binance`, `bybit`, `okx`, `bitget`, `mexc`, `kucoin`, `bingx`, `coinex`, `saldo`

Query parameters

Parámetro	Tipo	Requerido	Default	Descripción
`base`	string	No	`USD`	Moneda base. Valores: `USD`, `EUR`

Ejemplos de request

BCV oficial:

curl https://api.cotizave.com/v1/fx/rates/reference \
  -H "X-API-Key: nd-tu-api-key-aqui"

Binance P2P:

curl https://api.cotizave.com/v1/fx/rates/binance \
  -H "X-API-Key: nd-tu-api-key-aqui"

Tasa paralela contra EUR:

curl "https://api.cotizave.com/v1/fx/rates/parallel?base=EUR" \
  -H "X-API-Key: nd-tu-api-key-aqui"

Response

200 OK (ejemplo con BCV)

{
  "country": "VE",
  "currency": "VES",
  "base": "USD",
  "market": "reference",
  "type": "reference",
  "mid": 475.0083,
  "updated_at": "2026-04-08T14:00:00Z",
  "fetched_at": "2026-04-08T17:29:15Z"
}

200 OK (ejemplo con Binance P2P)

{
  "country": "VE",
  "currency": "VES",
  "base": "USD",
  "market": "binance",
  "type": "p2p",
  "ask": 639.24,
  "bid": 636.50,
  "mid": 637.87,
  "updated_at": "2026-04-08T17:29:00Z",
  "fetched_at": "2026-04-08T17:29:15Z"
}

Schema de respuesta

Campo	Tipo	Descripción
`country`	string	Siempre `"VE"`
`currency`	string	Siempre `"VES"`
`base`	string	Moneda base (`USD` o `EUR`)
`market`	string	Identificador del mercado consultado
`type`	string	Tipo: `reference`, `parallel` o `p2p`
`ask`	number \| null	Precio de venta. Presente solo en `parallel` y `p2p`.
`bid`	number \| null	Precio de compra. Presente solo en `parallel` y `p2p`.
`mid`	number	Precio promedio. Siempre presente.
`updated_at`	string (ISO 8601)	Cuándo se actualizó esta cotización
`fetched_at`	string (ISO 8601)	Cuándo se ensambló esta respuesta

Cuándo usar este endpoint vs `/v1/fx/rates`

Usa /v1/fx/rates/:market cuando:

Solo necesitas una tasa específica y no quieres payload adicional
Tu app muestra solo una cotización (ej: “Tasa BCV: Bs. 475”)
Estás construyendo un endpoint interno que consulta una tasa puntual
Necesitas el mínimo payload posible para eficiencia de red

Usa /v1/fx/rates cuando:

Necesitas varias tasas al mismo tiempo (ej: mostrar un dashboard comparativo)
Quieres una sola llamada que traiga todo (más eficiente que N llamadas individuales)

Regla práctica: si vas a mostrar más de 2 tasas, usa /v1/fx/rates. Si vas a mostrar 1 o 2 específicas, usa los endpoints individuales.

Errores posibles

Código	`error.code`	Causa
`400`	`invalid_base`	El parámetro `base` no es `USD` ni `EUR`
`401`	`unauthorized`	API Key inválida o faltante
`404`	`market_not_found`	El `market` solicitado no existe
`429`	`rate_limit_exceeded`	Cuota mensual agotada
`502`	`upstream_error`	La fuente upstream de este market está caída
`503`	`market_temporarily_unavailable`	El market existe pero está temporalmente deshabilitado

Ejemplo: market inexistente

curl https://api.cotizave.com/v1/fx/rates/coinbase \
  -H "X-API-Key: nd-tu-api-key-aqui"

{
  "code": "market_not_found",
  "message": "Market 'coinbase' not found. Available markets: reference, parallel, binance, bybit, okx, bitget, mexc, kucoin, bingx, coinex, saldo."
}

Ejemplo: fuente upstream caída

Si solicitas Binance pero Binance está caído:

{
  "code": "upstream_error",
  "message": "Upstream source 'binance' is currently unavailable. Last successful fetch: 2026-04-08T16:45:00Z."
}

En este caso, tu código debería tener un fallback a otro market (ej: bybit) o usar /v1/fx/rates y elegir de las disponibles.