Saltar al contenido principal

Inicio rápido

Tu primera llamada a la API de Cognivo​

La Cognivo Developer API permite que tu propio código haga las mismas preguntas on-chain que puedes hacer en la dApp y en Cognivo Chat. Esta página recorre el camino más corto: crea un proyecto, crea una clave, ejecuta una llamada real y lee la respuesta.

Cuándo usarla​

Usa la API cuando quieras verificaciones de tokens, billeteras o liquidez dentro de algo que estés construyendo, como un bot de trading, un panel interno, un trabajo de alertas o un servicio backend, en lugar de pasar por la dApp cada vez. Si solo quieres ejecutar verificaciones a mano, la dApp y Chat ya hacen eso y no necesitas una clave.

Dónde encontrarlo​

Inicia sesión en la dApp, abre Account en la barra lateral y selecciona Developers. Los visitantes que no han iniciado sesión ven solo una pantalla de orientación, así que inicia sesión primero. Todo lo de esta página ocurre en esa única pantalla.

Crea un proyecto y luego una clave​

Un proyecto agrupa tus claves de API y su uso, así que empieza por ahí.

  1. Selecciona New project para abrir el formulario corto que aparece debajo del selector de proyecto.
  2. Escribe un nombre en Project name para poder distinguir tus proyectos más adelante.
  3. Selecciona Create para añadir el proyecto, o Cancel para cerrar el formulario sin guardar.
  4. Selecciona Create live key para crear una clave para el proyecto y luego envíala con tus solicitudes desde tu propio código.
Los controles de proyecto en la página Developers, donde configuras un proyecto antes de crear una clave.Ampliar imagen

El nombre del proyecto es solo una etiqueta para ti. No aparece en tus solicitudes y puedes crear más de un proyecto, hasta el límite que muestra la página.

Cuando seleccionas Create live key, Cognivo muestra la clave completa exactamente una vez, en un diálogo con un botón de copiar. Cópiala en ese momento y guárdala en un lugar seguro. Después, la página muestra solo una versión enmascarada, el prefijo y los últimos cuatro caracteres, porque Cognivo guarda la clave en una forma que no puede volver a leer. Si pierdes una clave, o crees que se ha filtrado, usa Rotate o Revoke en la fila de la clave. La clave antigua deja de funcionar de inmediato.

Cada clave también lleva Permissions, que controlan a qué puede llamar: Intelligence, Security y Liquidity. Dale a una clave solo los permisos que necesita. El ejemplo de abajo necesita Liquidity.

En la misma tarjeta hay dos botones más. Top up credits te lleva a tu página de facturación. Enterprise access abre el flujo de soporte, y es la única vía que implica una solicitud, para precios a medida o límites más altos. Una clave live normal no necesita aprobación y funciona desde el momento en que la creas.

Ejecuta la llamada de ejemplo​

Abre la pestaña Quickstart. Lleva un ejemplo funcional que puedes copiar y ejecutar sin escribir nada tú mismo.

La pestaña Quickstart en la página Developers, donde copias una llamada de ejemplo que ya funciona.Ampliar imagen

La tarjeta Test keys vs live keys explica la diferencia. Una clave de prueba hace llamadas seguras con límites estrictos, lo cual es útil para dejar todo conectado. Una clave live hace llamadas reales que se cobran de tu saldo de créditos de Cognivo. La tarjeta Test a live endpoint ofrece luego cinco pasos numerados y el comando en sí, con un icono de copiar.

El comando es una verificación de liquidez real sobre un contrato real de Base:

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

La misma llamada desde JavaScript o TypeScript:

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.COGNIVO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);
  console.log(json.meta.request_id);
} else {
  console.error(json.error);
}

Qué devuelve​

Cada endpoint responde con el mismo envoltorio, que el bloque Expected response de la pestaña Quickstart muestra:

{
  "ok": true,
  "data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 0,
    "generated_at": "..."
  }
}

data contiene el resultado. Vale la pena registrar meta.request_id, porque soporte puede localizar una llamada concreta con él. meta.credits_charged te dice exactamente cuánto costó esa llamada.

Un campo puede volver vacío, desconocido o no disponible. Eso significa que Cognivo no pudo verificarlo con los datos a su alcance, no que no haya nada ahí. Léelo como "no confirmado" y no tomes un resultado silencioso como una señal de que todo está bien. Cognivo informa lo que verificó y lo que encontró, y nada en una respuesta demuestra que un token sea una estafa ni demuestra que sea seguro.

Una llamada fallida responde con ok en false, un código error y un request_id. Las llamadas fallidas no se cobran.

Costo, cadenas y límites​

  • Algunos endpoints son gratis con cualquier clave activa. Otros se cobran por llamada exitosa desde tu saldo de créditos de Cognivo. La pestaña Endpoints lista cada endpoint con su precio en créditos de Cognivo, o Free cuando es gratis, así que revísalo ahí antes de construir sobre un endpoint.
  • Solo se te cobra por una llamada exitosa, y meta.credits_charged confirma el importe. Los errores, los tiempos de espera agotados y las llamadas bloqueadas no cuestan nada.
  • Cada cuenta recibe 5 créditos gratis al día. Se reinician a medianoche UTC y se usan antes que cualquier crédito de pago.
  • Hoy la API cubre Ethereum, Base y BNB Chain. Algunos endpoints admiten menos cadenas que otros.
  • Las claves de prueba tienen topes estrictos y no son un nivel de producción gratuito. Cada fila de clave en la pestaña Keys muestra los límites que Cognivo está aplicando a esa clave en este momento, que pueden ser más bajos que el valor por defecto del nivel.
  • Una clave suspendida, o una clave en un proyecto suspendido, no puede ejecutar nada, y el portal muestra el motivo.

Mantén tu clave a salvo​

Llama a la API desde un servidor, nunca desde el código de un navegador o de una app móvil. Guarda la clave en una variable de entorno o en un gestor de secretos, nunca en un repositorio público, un mensaje de chat o una captura de pantalla. Si una clave pudo haberse filtrado, rótala o revócala en la pestaña Keys.

Siguientes pasos​

Lee Autenticación y claves para ver los permisos y el manejo de claves al completo, Endpoints para saber qué devuelve cada llamada y cuánto cuesta, y Límites de tasa y errores para reintentos y códigos de error. Para tu saldo de créditos y las recargas, consulta Facturación y créditos.