Saltar al contenido principal

Inicio rápido

Tu primera llamada en 30 segundos: crea un proyecto, crea una clave live, verifica tu saldo, pega un comando. Las claves live son de autoservicio y funcionan de inmediato; se te cobran 2 créditos cuando la llamada de ejemplo tiene éxito, y nunca se te cobra por una llamada fallida.

1. Crea un proyecto y una clave live​

  1. Abre el portal de desarrolladores e inicia sesión con tu cuenta de Cognivo.
  2. Crea un proyecto (por ejemplo "Mi bot de trading").
  3. Crea una clave de API live. Elige los permisos (scopes) que necesita - para este inicio rápido, otorga Inteligencia de tokens y billeteras (intel:read) y Lecturas de liquidez (liquidity:read).
  4. Copia la clave ahora. Se muestra exactamente una vez; después solo es visible una versión enmascarada (cogv_live_****abcd). Si la pierdes, rota la clave.

Las claves vienen en dos entornos:

  • cogv_live_... - la clave estándar. De autoservicio: funciona de inmediato, facturada por uso en créditos de Cognivo por cada llamada exitosa desde el saldo de créditos de tu cuenta. No se necesita trial ni aprobación.
  • cogv_test_... - claves Sandbox, claramente etiquetadas como Sandbox, solo para demos limitadas y pruebas de integración. No pueden ejecutar inteligencia en vivo y tienen topes estrictos (25 solicitudes/hora, 100/día, 1/segundo).

2. Verifica tu clave y tu saldo​

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'

Recibes de vuelta tu clave enmascarada, proyecto, entorno, scopes y límite de tasa por hora, además de access_mode, el credits_balance de tu cuenta (para que puedas ver si puedes costear la siguiente llamada) y la guía top_up. Esta llamada siempre es gratis.

3. Ejecuta tu primera llamada en vivo (curl)​

Los endpoints de inteligencia usan POST con un cuerpo JSON. Este comando exacto ejecuta una verificación real de liquidez sobre un token real de Base (RWA Inc, un contrato público que usamos en demos). Se ejecuta de inmediato con tu nueva clave live:

curl -X POST 'https://api.cognivolabs.io/v1/api/intel/liquidity' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chain":"base","address":"0xe2b1dc2d4a3b4e59fdf0c47b71a7a86391a8b35a"}'

Deberías ver "ok": true con la identidad del token (nombre/símbolo), una instantánea de mercado y contexto de LP/lock en data. En caso de éxito se te cobra el precio del endpoint - 2 créditos para liquidez - y meta.credits_charged lo confirma. Si en cambio obtienes un error 402 con código payment_required, tu saldo de créditos de Cognivo no puede cubrir la llamada: no se cobró nada, así que recarga en la página de facturación de tu cuenta de Cognivo y ejecuta el mismo comando otra vez. Las llamadas fallidas nunca se cobran. Cambia la address por cualquier contrato de token en eth, base o bsc cuando estés listo.

Mantén tu clave en secreto

Nunca pegues una clave de API real en un repositorio público, un chat o código del lado del cliente. La clave se muestra solo una vez al crearla; si se filtra, rótala en el portal.

4. La misma llamada en JavaScript / TypeScript​

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY, // never hardcode keys
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);        // the intelligence result
  console.log(json.meta.request_id); // keep for support/debugging
} else {
  console.error(json.error);     // e.g. "payment_required": top up, then retry
}

5. Forma de la respuesta​

Todos los endpoints responden con el mismo sobre (envelope); los ids y timestamps de abajo son valores de ejemplo:

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 2,
    "generated_at": "2026-07-08T00:00:00.000Z"
  }
}

En caso de fallo (nunca se cobra):

{ "ok": false, "error": "payment_required", "request_id": "capi_..." }

Facturación y recargas​

  • Pago por uso, por llamada exitosa. Cada llamada exitosa deduce el precio en créditos publicado del endpoint del saldo de créditos de Cognivo del propietario del proyecto (los mismos créditos que usas en Chat y la dApp). No hay suscripción ni mínimo.
  • Dónde recargar. En la página de facturación de tu cuenta de Cognivo en la dApp. GET /v1/api/me muestra tu credits_balance actual y la guía top_up.
  • Las llamadas fallidas nunca se cobran. Los errores, timeouts y llamadas denegadas no cuestan nada. El propio 402 payment_required es gratis: recarga y reintenta.
  • Los resultados vacíos honestos son gratis. wallet/pnl devuelve 422 cuando una billetera no tiene operaciones con precio en ese token, y una lista vacía de wallet/approvals es una respuesta válida; ninguna de las dos se cobra.
  • Reintentar es seguro. Una llamada exitosa se cobra exactamente una vez; los envíos duplicados de la misma operación no pueden cobrarte dos veces. Ante un 5xx o 429, reintenta con backoff; ante un 402, recarga primero.
  • Suspensión. Una clave suspendida (o un proyecto deshabilitado) no puede ejecutar nada y nunca se cobra; el portal muestra el motivo.

Mantén tu clave a salvo​

  • Llama a la API desde un servidor, nunca desde código de navegador o de cliente móvil.
  • Guarda la clave en una variable de entorno o en un gestor de secretos.
  • Si una clave pudo haberse filtrado, revócala o rótala en el portal - la clave antigua deja de funcionar en menos de un minuto.