Referencia de endpoints

Todos los endpoints viven bajo https://api.cognivolabs.io/v1/api. Los endpoints de inteligencia son POST con un cuerpo JSON (esto evita que las vistas previas de enlaces, los rastreadores y los prefetchers puedan disparar una ejecución). GET existe solo para health, me y discover.

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

El sobre de respuesta

Todos los endpoints responden con el mismo sobre (envelope); los ids y timestamps de los ejemplos de esta página son valores de ejemplo. Éxito:

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

data - el resultado de inteligencia en sí; su forma varía según el endpoint
meta.request_id - id único de esta llamada; consérvalo, soporte puede rastrear una llamada a partir de él
meta.credits_charged - los créditos que costó esta llamada: el precio en créditos del endpoint en una llamada de pago exitosa; 0 para endpoints gratuitos, llamadas con asignación trial y cualquier resultado fallido o vacío honesto
meta.generated_at - cuándo se produjo el resultado
meta.chain aparece en llamadas específicas de cadena, y meta.sources (un arreglo de etiquetas de fuentes) 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 (ver Límites de tasa y errores); message es una pista opcional para humanos.

Campos comunes del cuerpo

chain - uno de eth, base, bsc (sin distinguir mayúsculas)
address / wallet / token - una dirección EVM 0x… (40 caracteres hexadecimales)

Todos los ejemplos siguientes usan el marcador de posición YOUR_API_KEY; en código real carga la clave desde una variable de entorno o un gestor de secretos, nunca la codifiques directamente.

Precios

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 (los envíos duplicados de la misma operación no pueden cobrar dos veces). Si tu saldo no puede cubrir una llamada obtienes 402 payment_required (no se cobra nada): recarga en la página de facturación de tu cuenta de Cognivo y reintenta. Las claves Sandbox (cogv_test_) no pueden ejecutar inteligencia en vivo. Ver Límites de tasa, errores y facturación. Precios por endpoint:

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
`GET health`, `GET me`	gratis
`GET discover`	gratis, con un tope de tasa estricto

Servicio

GET /v1/api/health

Sonda de disponibilidad (liveness). No requiere 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 (no es el sobre estándar, por diseño):

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

Limitaciones: si la API pública está apagada, aquí también obtienes 404 public_api_disabled, así que este endpoint sirve también como verificación de disponibilidad.

GET /v1/api/me

Introspección de la clave que hace la llamada. Scope: cualquier clave válida. Gratis. Para las claves live de autoservicio también muestra el credits_balance de la cuenta propietaria (null si está temporalmente no disponible) y la guía top_up, además del 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();

Respuesta:

{
  "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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

Limitaciones: muestra solo la clave enmascarada, nunca el material completo de la clave. credits_balance es el saldo de créditos de Cognivo de la cuenta propietaria y puede ser null si está temporalmente no disponible.

Inteligencia de tokens

POST /v1/api/intel/why-down - scope `intel:read`

Por qué está cayendo este token: una lectura verificada de la actividad on-chain reciente en busca del factor dominante (ventas, retiros de LP, movimientos del propietario).

Costo: 3 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud:

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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 sobre estándar; data contiene el análisis de la caída (factor dominante, observaciones on-chain que lo respaldan) con meta.chain establecido.

Limitaciones: necesita actividad reciente para decir algo útil; para un token con muy poco historial de trading la lectura puede ser escasa. Señales, no asesoramiento financiero.

POST /v1/api/intel/team-wallets - scope `intel:read`

Escaneo de billeteras del equipo y de control para un token: billeteras del desplegador, propietario y controladores, más su comportamiento reciente.

Costo: 5 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud:

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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"}'

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

Respuesta: el sobre estándar; data lista las billeteras del equipo/control identificadas y su comportamiento reciente, a menudo con meta.sources.

Limitaciones: identifica billeteras a partir de relaciones on-chain (despliegue, propiedad, control); no puede ver la estructura del equipo fuera de la cadena.

POST /v1/api/intel/liquidity - scope `liquidity:read`

Estado del pool/LP de un token: contexto del pool, custodia del LP y contexto de locks/quemas.

Costo: 2 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud (los booleanos opcionales metadata, locks y full añaden metadatos verificados del pool, prueba de locks temporizados y la lectura más completa disponible):

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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}'

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

Respuesta: el sobre estándar; data contiene la identidad del token, una instantánea de mercado y la custodia del LP más el contexto de locks/quemas.

Limitaciones: la procedencia histórica profunda de las quemas no se expone en v1; el contexto de locks cubre patrones de lockers reconocidos, y un locker personalizado no reconocido puede leerse como custodia sin lock.

POST /v1/api/intel/risk - scope `intel:read`

Señales de riesgo de Cognivo conscientes de la cadena para un token (lectura de banderas rojas como respaldo).

Costo: 2 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud:

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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"}'

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

Respuesta: el sobre estándar; data contiene las señales de riesgo y las banderas encontradas para el token.

Limitaciones: un resultado limpio nunca significa "seguro"; significa que no se encontraron banderas rojas conocidas en el momento de la lectura.

Inteligencia de billeteras

POST /v1/api/wallet/pnl - scope `intel:read`

PnL realizado de una billetera en un token, a partir de actividad de billetera verificada. Tanto wallet como token son obligatorios.

Costo: 10 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas y los resultados 422 sin datos nunca se cobran.

Cuerpo de la solicitud:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

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

Respuesta: el sobre estándar; data contiene el cálculo de PnL realizado para ese par billetera/token.

Limitaciones: devuelve 422 (por ejemplo insufficient_data) cuando la billetera no tiene operaciones con precio en ese token, de modo que no se puede calcular una cifra justa. Cognivo nunca inventa una cifra, y un 422 nunca se cobra. Solo PnL realizado; las posiciones no realizadas (aún en cartera) no se valoran aquí.

POST /v1/api/wallet/approvals - scope `security:read`

Aprobaciones de tokens vigentes contra una billetera, señalando las autorizaciones ilimitadas. Solo lectura: Cognivo nunca mueve fondos y no puede revocar por ti.

Costo: 2 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud (limit y offset permiten opcionalmente paginar conjuntos grandes de aprobaciones):

{ "chain": "eth", "address": "0xWALLET" }

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"}'

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

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

Limitaciones: un resultado vacío (sin aprobaciones encontradas) es una respuesta válida y exitosa, y no se cobra.

POST /v1/api/wallet/exact-movements - scope `intel:read`

Movimientos recientes exactos de una billetera (lectura estilo propietario/desplegador). token es opcional y acota la lectura a un solo token.

Costo: 5 créditos por llamada exitosa, de autoservicio en cualquier clave live con este scope; las llamadas fallidas nunca se cobran.

Cuerpo de la solicitud:

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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"}'

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

Respuesta: el sobre estándar; data contiene la lista de movimientos con conteos.

Limitaciones: 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 Discover: tarjetas de inteligencia pública recientes y de alta calidad (identidad del token, gancho, viñetas). Scope: cualquier clave válida. Gratis, con un tope de tasa estricto.

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

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

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

Respuesta:

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

Limitaciones: los valores de limit fuera de 1-50 se ajustan al rango; el feed contiene solo la inteligencia que los usuarios decidieron publicar, así que es una muestra, no una cobertura completa.

Planificado (aún no disponible)

Esto se documenta por transparencia de la hoja de ruta y hoy no devuelve nada:

Rastreo profundo de billeteras a través de la API (wallet/trace) - el flujo de trabajos asíncronos es por ahora solo para chat/dApp
Consulta de reportes por id (reports/:id)
Webhooks
Endpoints de Solana

El sobre de respuesta​

Campos comunes del cuerpo​

Precios​

Servicio​

GET /v1/api/health​

GET /v1/api/me​

Inteligencia de tokens​

POST /v1/api/intel/why-down - scope intel:read​

POST /v1/api/intel/team-wallets - scope intel:read​

POST /v1/api/intel/liquidity - scope liquidity:read​

POST /v1/api/intel/risk - scope intel:read​

Inteligencia de billeteras​

POST /v1/api/wallet/pnl - scope intel:read​

POST /v1/api/wallet/approvals - scope security:read​

POST /v1/api/wallet/exact-movements - scope intel:read​

Discover​

GET /v1/api/discover​

Planificado (aún no disponible)​

El sobre de respuesta

Campos comunes del cuerpo

Precios

Servicio

GET /v1/api/health

GET /v1/api/me

Inteligencia de tokens

POST /v1/api/intel/why-down - scope `intel:read`

POST /v1/api/intel/team-wallets - scope `intel:read`

POST /v1/api/intel/liquidity - scope `liquidity:read`

POST /v1/api/intel/risk - scope `intel:read`

Inteligencia de billeteras

POST /v1/api/wallet/pnl - scope `intel:read`

POST /v1/api/wallet/approvals - scope `security:read`

POST /v1/api/wallet/exact-movements - scope `intel:read`

Discover

GET /v1/api/discover

Planificado (aún no disponible)