API para desarrolladores

Con el plan Pro puedes crear tus propias claves y consultar el mercado desde tus programas: un bot de Telegram, una hoja de cálculo, un script que te avise o lo que quieras construir.

Lo que devuelve la API es lo mismo que ves en la tarjeta Mejores Oportunidades del panel principal: las ofertas abiertas donde mejor te sale comprar QUSD y donde mejor te sale venderlo.

Esta página es una referencia técnica. Por eso, a diferencia del resto de la documentación, usa los nombres exactos de los campos: son los que tu programa va a leer.

Crear una clave

Entra en Ajustes y baja hasta API Keys.
Pulsa Nueva API key, ponle un nombre que te diga para qué es («Bot de avisos», «Hoja de precios») y confirma.
Copia la clave en ese momento. Solo se muestra una vez: QvaMark no la guarda, así que no puede volver a enseñártela. Si la pierdes, revócala y crea otra.

Puedes tener hasta 5 claves activas y crear hasta 10 al día.

Guárdala como una contraseña

Quien tenga tu clave puede consultar la API en tu nombre y gastar tu cupo.

No la pongas en código que se ejecute en un navegador ni en un repositorio público.
Usa una clave distinta para cada programa: si una se filtra, revocas solo esa.
Si sospechas que alguien la tiene, revócala desde Ajustes. Deja de funcionar al instante.

Si cambias de plan

Las claves dejan de funcionar mientras tu cuenta no tenga el plan Pro, y vuelven a funcionar solas si lo recuperas. Mientras tanto siguen apareciendo en Ajustes, así que puedes revocarlas cuando quieras.

Autenticación

Envía la clave en la cabecera Authorization:

curl -H "Authorization: Bearer qm_tu_clave" \
  "https://qvamark.com/api/v2/offers/best?tick=BANK_CUP&limit=5"

También se acepta en la cabecera X-Api-Key: qm_tu_clave. La clave nunca va en la URL: las URLs acaban guardadas en historiales y registros.

Mejores ofertas

GET /api/v2/offers/best

Parámetro	Obligatorio	Descripción
`tick`	Sí	La moneda, tal como aparece en QvaMark: `BANK_CUP`, `ETECSA`, `CLASICA`… Da igual si va en mayúsculas o minúsculas.
`limit`	No	Cuántas ofertas por lado, de 1 a 10. Por defecto, 5.

Respuesta

{
  "data": {
    "coinTick": "BANK_CUP",
    "toBuyFrom": [
      {
        "uuid": "9f1c…",
        "ratio": 980,
        "amount": 40.6,
        "receive": 39788,
        "publisher": {
          "username": "goliatgallardo8",
          "name": "Goliat",
          "avatarUrl": "https://media.qvapay.com/…",
          "kyc": true,
          "vip": false,
          "goldenCheck": false,
          "ratingAvg": 4.9,
          "ratingCount": 312
        },
        "requirements": { "onlyKyc": false, "onlyVip": false },
        "url": "https://qvapay.com/p2p/9f1c…",
        "publishedAt": "2026-09-24T13:58:10.000Z",
        "lastSeenAt": "2026-09-24T14:02:31.000Z"
      }
    ],
    "toSellTo": []
  },
  "meta": {
    "apiVersion": "2",
    "limit": 5,
    "generatedAt": "2026-09-24T14:02:40.000Z"
  }
}

toBuyFrom — donde compras QUSD («Comprar QUSD» en el panel). Son ofertas de venta: el otro vende QUSD y tú pagas en la moneda. La más barata va primero.
toSellTo — donde vendes QUSD («Vender QUSD» en el panel). Son ofertas de compra: el otro compra QUSD y tú recibes la moneda. La que más paga va primero.

Cada oferta trae:

Campo	Qué es
`ratio`	Unidades de la moneda por cada QUSD. Es el precio.
`amount`	Los QUSD de la oferta.
`receive`	Lo que se paga o se recibe en la moneda.
`publisher`	Quién la publicó y su reputación en QvaPay.
`requirements`	Si la oferta solo admite usuarios con KYC o VIP.
`url`	La oferta en QvaPay, para aplicar a ella.
`publishedAt`	Cuándo se publicó en QvaPay. Puede ser `null`.
`lastSeenAt`	La última vez que QvaMark la vio abierta.

Qué ofertas entran

Solo ofertas abiertas y vistas hace poco. Una oferta que QvaMark no ha vuelto a ver no se recomienda. Por eso las listas pueden salir vacías en una moneda con poco movimiento.
Se descartan los precios absurdos, por ejemplo una venta a una décima parte del precio de mercado, que casi siempre es un error al publicar o un cebo.
No aparecen las ofertas privadas ni el mensaje que el vendedor escribe en la oferta.

Límites de uso

Límite	Cuánto
Por clave	60 peticiones por minuto
Por cuenta, sumando todas tus claves	10.000 peticiones al día

Los precios se actualizan a medida que QvaMark repasa el mercado, así que consultar más de una vez por segundo no te dará datos más nuevos. Una vez cada pocos segundos es más que suficiente para un bot.

Cada respuesta te dice cuánto te queda:

Cabecera	Qué es
`X-RateLimit-Limit`	Tu límite en la ventana actual.
`X-RateLimit-Remaining`	Cuántas peticiones te quedan.
`X-RateLimit-Reset`	Cuándo se reinicia, en segundos Unix.
`Retry-After`	Solo si te has pasado: cuántos segundos esperar.

Errores

Todos los errores tienen la misma forma:

{ "error": { "code": "rate_limited", "message": "Límite de 60 peticiones por minuto y key superado." } }

Programa contra code, no contra message: el texto puede cambiar, el código no.

HTTP	`code`	Qué pasa
400	`invalid_request`	Falta `tick` o algún parámetro no es válido.
401	`missing_api_key`	La petición no lleva clave.
401	`invalid_api_key`	La clave no existe, está revocada o ha caducado.
403	`insufficient_scope`	La clave no tiene permiso para esta consulta.
403	`plan_required`	Tu cuenta no tiene el plan Pro.
403	`account_disabled`	La cuenta dueña de la clave está desactivada.
404	`not_found`	QvaMark no conoce esa moneda.
429	`rate_limited`	Te has pasado del límite. Espera lo que diga `Retry-After`.
500	`internal_error`	Algo falló de nuestro lado. Reintenta en unos segundos.

Si repites muchas peticiones con claves inválidas, la API deja de responderte durante un minuto (429).

Ver también

Panel principal — la tarjeta Mejores Oportunidades
Configuración de cuenta
Planes y precios