Referencia de endpoints

Qué es esta página

La Cognivo Developer API permite que tu propio código le haga a Cognivo las mismas preguntas que responde la app. Todos los endpoints viven bajo https://api.cognivolabs.io/v1/api.

Úsala cuando quieras que una verificación de Cognivo se ejecute en algún lugar que no sea la app: dentro de tu propio bot, un panel, un trabajo sobre una hoja de cálculo o un script nocturno que vigila una lista de tokens.

Los endpoints de inteligencia son POST con cuerpo JSON. Es algo deliberado: una vista previa de enlace, un rastreador o una precarga del navegador nunca pueden disparar una ejecución al cargar una URL. GET existe solo para health, me y discover.

Dónde encontrar esto en la app

Inicia sesión en la app de Cognivo, abre Developers en la barra lateral izquierda bajo Account y selecciona la pestaña Endpoints.

La pestaña Endpoints de la página Developers, donde se lista cada endpoint de Cognivo con el permiso que necesita y lo que cuesta.Ampliar imagen

La pestaña es una referencia, no un ejecutor. Lista cada endpoint activo con un ejemplo copiable, el permiso que necesita la clave y el precio en créditos. La tarjeta Permissions explained agrupa esos permisos en tres: Intelligence (por qué está cayendo, billeteras del equipo, riesgo, PnL de billetera, movimientos exactos), Security (aprobaciones de tokens) y Liquidity (liquidez, locks y quemas). Dale a cada clave solo los permisos que necesita.

¿Prefieres una versión legible por máquinas? La especificación OpenAPI completa cubre todo lo de esta página.

El envoltorio de respuesta

Cada endpoint responde con el mismo envoltorio. Los identificadores y marcas de tiempo de los ejemplos de abajo son valores de ejemplo. Éxito:

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

• data es el resultado en sí. Su forma varía según el endpoint.
• meta.request_id es un identificador único de esta llamada. Consérvalo, soporte puede rastrear una llamada a partir de él.
• meta.credits_charged es lo que costó la llamada: el precio del endpoint en una llamada de pago exitosa, y 0 para los endpoints gratis y para cualquier resultado fallido u honestamente vacío.
• meta.generated_at es cuándo se produjo el resultado.
• meta.chain aparece en las llamadas específicas de una cadena, y meta.sources aparece cuando el resultado cita fuentes.

Fallo:

{ "ok": false, "error": "invalid_chain", "message": "chain must be one of: eth, base, bsc", "request_id": "capi_..." }

error es un código estable legible por máquinas. message es una pista opcional para humanos. La lista completa está en Límites de tasa y errores.

Campos comunes del cuerpo

• chain es uno de eth (Ethereum), base (Base) o bsc (BNB Chain), y no distingue mayúsculas de minúsculas.
• address, wallet y token son direcciones EVM 0x de 40 caracteres hexadecimales.

Todos los ejemplos usan el marcador YOUR_API_KEY. En código real, carga la clave desde una variable de entorno o un gestor de secretos. Nunca la escribas directamente en el código.

Cuánto cuesta cada endpoint

Las claves live son de autoservicio y de pago por uso. Una clave live nueva ejecuta estos endpoints de inmediato, y cada llamada exitosa se cobra en créditos de Cognivo desde el saldo de tu cuenta. Las llamadas fallidas nunca se cobran, y una llamada exitosa se cobra exactamente una vez, así que un envío repetido de la misma operación no puede cobrarte dos veces.

Cada cuenta recibe 5 créditos gratis al día, y se reinician a medianoche UTC. Si tu saldo no puede cubrir una llamada, obtienes 402 payment_required y no se cobra nada. Recarga en la página de facturación de tu cuenta y reintenta. Las claves Sandbox (cogv_test_) no pueden ejecutar inteligencia en vivo. Consulta Facturación y créditos.

Endpoint	Créditos por llamada exitosa
POST intel/liquidity	2
POST intel/risk	2
POST wallet/approvals	2
POST intel/why-down	3
POST intel/team-wallets	5
POST wallet/exact-movements	5
POST wallet/pnl	10
POST contract/analysis	gratis
GET health, GET me	gratis
GET discover	gratis, con un tope de tasa estricto

Servicio

GET /v1/api/health

Comprueba que la API de Cognivo está en funcionamiento. No necesita clave de API.

curl 'https://api.cognivolabs.io/v1/api/health'

const res = await fetch("https://api.cognivolabs.io/v1/api/health");
const json = await res.json();

Respuesta, que no es el envoltorio estándar, por diseño:

{ "ok": true, "service": "cognivo-public-api", "version": "v1", "generated_at": "2026-07-09T00:00:00.000Z" }

Si la API pública está apagada, aquí también obtienes 404 public_api_disabled, así que este endpoint sirve además como comprobación de disponibilidad.

GET /v1/api/me

Muestra detalles sobre la clave que llama: su nivel, permisos y límite de tasa. Funciona con cualquier clave activa y es gratis. Para las claves live de autoservicio muestra además el credits_balance de la cuenta propietaria y orientación de top_up, junto con el access_mode de la clave.

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

const res = await fetch("https://api.cognivolabs.io/v1/api/me", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

{
  "ok": true,
  "data": {
    "key": "cogv_live_****abcd",
    "project_id": "…",
    "environment": "live",
    "tier": "basic",
    "access_mode": "live",
    "scopes": ["intel:read", "liquidity:read"],
    "rate_limit_per_hour": 1000,
    "credits_balance": 1250,
    "top_up": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitaciones: muestra solo la clave enmascarada, nunca el material completo de la clave. credits_balance puede volver como null, lo que significa que Cognivo no pudo leer el saldo en ese momento, no que el saldo sea cero.

Todos los demás endpoints siguen la misma forma de llamada que los ejemplos de abajo. Cambia la ruta y los campos del cuerpo.

Inteligencia de tokens

POST /v1/api/intel/why-down, permiso Intelligence (intel:read)

Una lectura en lenguaje claro de por qué el precio de un token está cayendo, construida a partir de la actividad on-chain reciente: ventas fuertes, retirada de liquidez, movimientos de billeteras del propietario o del equipo.

Precio de lista: 3 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/why-down", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

Respuesta: el envoltorio estándar. data contiene la causa dominante y las observaciones on-chain que la respaldan, con meta.chain establecido.

Limitaciones: la lectura necesita actividad reciente para decir algo útil, así que un token con muy poco historial de negociación da una respuesta escasa. Son señales, no asesoramiento financiero.

POST /v1/api/intel/team-wallets, permiso Intelligence (intel:read)

Saca a la luz las billeteras vinculadas al equipo o a la tesorería de un token: billeteras del deployer, del propietario y de control, además de lo que han estado haciendo recientemente.

Precio de lista: 5 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

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

Respuesta: el envoltorio estándar. data lista las billeteras identificadas y su comportamiento reciente, a menudo con meta.sources.

Limitaciones: las billeteras se identifican a partir de relaciones on-chain como el despliegue, la propiedad y el control. Cognivo no puede ver la estructura del equipo fuera de la cadena, así que una lista vacía significa que no se pudo vincular nada en la cadena, no que un token no tenga equipo.

POST /v1/api/intel/liquidity, permiso Liquidity (liquidity:read)

Verifica la liquidez, los locks y las quemas de un token con evidencia on-chain: contexto del pool, quién tiene los tokens LP, y contexto de lock o quema.

Precio de lista: 2 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

Los booleanos opcionales metadata, locks y full añaden metadatos del pool, prueba de lock con tiempos y la lectura más completa disponible.

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":"0xTOKEN_CONTRACT","locks":true}'

Respuesta: el envoltorio estándar. data contiene la identidad del token, una instantánea de mercado y la custodia de LP con contexto de lock o quema.

Limitaciones: la procedencia histórica profunda de las quemas no se expone en v1. El contexto de lock cubre patrones de locker reconocidos, así que un locker personalizado poco común puede leerse como simple custodia en lugar de como un lock. Léelo como "no verificado", no como "sin lock".

POST /v1/api/intel/risk, permiso Intelligence (intel:read)

Señales de riesgo de Cognivo para un contrato de token, conscientes de la cadena, con una lectura de banderas rojas como alternativa.

Precio de lista: 2 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

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

Respuesta: el envoltorio estándar. data contiene las señales y banderas encontradas para el token.

Limitaciones: un resultado limpio no significa que el token sea seguro. Significa que no se encontraron banderas rojas conocidas en el momento de la lectura.

POST /v1/api/contract/analysis, permiso Contract (contract:read)

Evidencia de contrato y control para una dirección de contrato: si existe, quién es su propietario, si se renunció a la propiedad, si es un proxy y quién lo administra, quién lo desplegó, qué billeteras pueden atribuirse como controladoras o de equipo, y si el código fuente está verificado.

Costo: 0 créditos. Este endpoint es gratis por decisión, en todos los planes. No se deduce nada.

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

Respuesta: el envoltorio estándar. data contiene contract, ownership, proxy, deployer, controllers, source_verification, limitations y unavailable.

Cada campo te dice de dónde salió. meta.provenance asigna a cada campo exactamente uno de estos valores:

Etiqueta	Qué significa
verified_onchain	Leído de un nodo de esa red en el momento de tu solicitud. Un hecho.
augmented	Cognivo Augmented Intelligence: proporcionado por una fuente externa, contrastado pero no probado por Cognivo.
interpretation	La lectura que Cognivo hace de los hechos. Un juicio, no un hecho.
unavailable	Cognivo no pudo obtenerlo. El motivo está en data.unavailable.

Nada se adivina, ni se rellena con valores por defecto, ni se devuelve como cero para tapar un hueco.

meta.chain_data_source.cognivo_grounded te dice si Cognivo opera la infraestructura de la que salió la lectura. Cognivo ejecuta su propio nodo de Ethereum, así que las lecturas de Ethereum son true. Las lecturas de Base y BNB Chain vienen de infraestructura RPC externa, así que son false. Esas lecturas son precisas, pero no se sirven desde hardware que Cognivo controla, y Cognivo lo dice en lugar de dejar que supongas lo contrario.

Limitaciones en Base, devueltas también en data.limitations:

• El grafo profundo de controladores es solo para Ethereum. En Base, la atribución de controladores y equipo viene de una lectura de roles de billetera más limitada.
• La evidencia del deployer en Base viene de una fuente externa, no de una lectura del archivo de Cognivo. Trátala como una pista sólida, no como un hecho probado.
• Los calendarios de lock de liquidez no se decodifican en Base. Usa POST /v1/api/intel/liquidity para la custodia de LP y la evidencia de quema, y no interpretes un lock ausente como que no hay lock.

Este endpoint informa únicamente de evidencia de control del contrato. No dice nada sobre la liquidez, y un resultado limpio nunca significa que el contrato sea seguro.

Solo lectura: no se firma nada, no se construye ninguna transacción, no se difunde nada y no se delega ninguna billetera.

Inteligencia de billeteras

POST /v1/api/wallet/pnl, permiso Intelligence (intel:read)

Ganancias y pérdidas de una billetera sobre un token, calculadas a partir de swaps on-chain fundamentados. Tanto wallet como token son obligatorios.

Precio de lista: 10 créditos por llamada exitosa. Las llamadas fallidas, y los resultados 422 sin datos, nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/pnl' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET","token":"0xTOKEN_CONTRACT"}'

Respuesta: el envoltorio estándar. data contiene la cifra realizada, y una cifra no realizada para la posición que aún se mantiene cuando existe una base de costo defendible.

Limitaciones: cuando no se puede establecer una base de costo defendible, la cifra no realizada vuelve como null en lugar de un número inventado. Cuando la billetera no tiene operaciones con precio en ese token en absoluto, la llamada devuelve 422 (por ejemplo insufficient_data), lo que significa que Cognivo no pudo calcular una cifra justa, no que la ganancia fuera cero. Un 422 nunca se cobra. Los swaps a los que Cognivo no pudo asignar precio se muestran como sin precio en lugar de descartarse.

POST /v1/api/wallet/approvals, permiso Security (security:read)

Lista las aprobaciones de gasto de tokens que ha concedido una billetera, y marca las autorizaciones ilimitadas.

Precio de lista: 2 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

Los parámetros opcionales limit y offset paginan conjuntos grandes de aprobaciones.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/approvals' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"eth","address":"0xWALLET"}'

Respuesta: el envoltorio estándar. data contiene la lista de aprobaciones con el gastador, el token y el contexto de la autorización.

Limitaciones: esto es de solo lectura. Cognivo nunca mueve fondos y no puede revocar una aprobación por ti. La revocación siempre se hace desde tu propia billetera. Una lista vacía es una respuesta exitosa válida, y no se cobra.

POST /v1/api/wallet/exact-movements, permiso Intelligence (intel:read)

Lista los movimientos exactos de tokens de una billetera: compras, ventas y transferencias. token es opcional y acota la lectura a un solo token.

Precio de lista: 5 créditos por llamada exitosa. Las llamadas fallidas nunca se cobran. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

curl -X POST 'https://api.cognivolabs.io/v1/api/wallet/exact-movements' \
  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"chain":"base","wallet":"0xWALLET"}'

Respuesta: el envoltorio estándar. data contiene la lista de movimientos con recuentos.

Limitaciones: la llamada devuelve los movimientos más recientes, hasta 25 por llamada. Una billetera sin movimientos coincidentes devuelve 422 en lugar de un historial inventado.

Discover

GET /v1/api/discover

El feed público de Discover: tarjetas recientes de inteligencia on-chain anonimizada, cada una con la identidad del token, un gancho y viñetas. Funciona con cualquier clave activa. Gratis, bajo un límite diario estricto.

Parámetros de consulta: limit (de 1 a 50, por defecto 20) y chain opcional (eth, base, bsc).

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitaciones: los valores de limit fuera del rango de 1 a 50 se ajustan al rango. El feed contiene únicamente la inteligencia que los usuarios eligieron publicar, así que es una muestra, no cobertura completa.

Aún no disponible

Esto se lista por transparencia y hoy no devuelve nada:

• Rastreo profundo de billeteras a través de la API (wallet/trace). El flujo de trabajos asíncronos está por ahora solo en el chat y la app.
• Obtención de informes por identificador (reports/:id).
• Webhooks.
• Endpoints de Solana.

Siguientes pasos

Haz tu primera llamada con el Inicio rápido, crea y acota una clave en Autenticación y claves, y lee Límites de tasa y errores antes de poner nada en un horario recurrente.