Saltar al contenido principal

Autenticación y claves de API

Enviar tu clave​

El encabezado canónico es X-API-Key:

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":"eth","address":"0xTOKEN_CONTRACT"}'

Authorization: Bearer YOUR_API_KEY se acepta como alias para las bibliotecas cliente que lo prefieran.

Cómo se almacenan las claves​

Cognivo nunca almacena tu clave completa. Solo se guarda un hash unidireccional junto con el prefijo y los últimos cuatro caracteres, y por eso la clave completa puede mostrarse exactamente una vez al crearla. Trátala como una contraseña.

Claves sandbox vs claves live​

PrefijoPropósitoFacturaciónTope de tasa
cogv_test_Sandbox: solo demos limitadas y pruebas de integración, claramente etiquetadas como Sandbox; no pueden ejecutar inteligencia en vivonunca se cobratope fijo de 25 solicitudes/hora, 100/día y 1/segundo
cogv_live_producción; de autoservicio, funciona de inmediatopago por uso: créditos de Cognivo por cada llamada exitosa desde tu saldo de créditos; las llamadas fallidas nunca se cobrantu límite por modo de acceso, 1,000 solicitudes/hora para empezar

Si quieres, prototipa las formas de las solicitudes con una clave sandbox y luego publica con una clave live. Una clave live nueva no necesita aprobación ni trial: comienza a funcionar en el momento en que la creas, siempre que tu cuenta tenga créditos.

Modos de acceso, en claro​

  • Live (estándar) - autoservicio con pago por uso. Una clave live nueva funciona de inmediato, cobrada en créditos de Cognivo por cada llamada exitosa a los precios por endpoint publicados. 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.
  • Sandbox - claves cogv_test_; solo demos/pruebas limitadas, no pueden ejecutar inteligencia en vivo. Las llamadas en vivo responden 403 sandbox_limited.
  • Trial - una asignación de evaluación opcional otorgada por un administrador (limitada y con expiración). No se requiere para el uso de pago ordinario.
  • Partner - un acuerdo gestionado por un administrador.
  • Enterprise - la vía de solicitud de acceso: precios a medida, límites a medida y volumen. Solicítalo desde el portal de desarrolladores.
  • Suspendida - la clave no puede ejecutar nada; el portal muestra el motivo.
  • Claves heredadas solo de metadatos - un pequeño número de claves antiguas anteriores a la facturación de autoservicio solo pueden llamar a los endpoints de metadatos; las llamadas en vivo responden 403 access_required. Crea una clave live nueva para pasar al pago por uso.

GET /v1/api/me te dice en qué modo está tu clave (access_mode), además del credits_balance de tu cuenta y la guía top_up.

Scopes (permisos)​

Las claves son de denegación por defecto: una clave solo puede llamar a los grupos de endpoints que le otorgaste al crearla. Hay tres scopes, y cada uno simplemente desbloquea un conjunto de endpoints.

intel:read - inteligencia de tokens y billeteras​

El scope de uso diario. Permite que tu clave pregunte "¿qué está pasando con este token o billetera?": causas de caídas de precio, señales de riesgo, comportamiento de las billeteras del equipo, PnL realizado y movimientos exactos.

Desbloquea: POST /v1/api/intel/why-down, POST /v1/api/intel/team-wallets, POST /v1/api/intel/risk, POST /v1/api/wallet/pnl, POST /v1/api/wallet/exact-movements

security:read - escaneos de seguridad de billeteras​

Permite que tu clave verifique lo que una billetera ha aprobado: qué contratos pueden gastar sus tokens, señalando las autorizaciones ilimitadas. Solo lectura; una clave con este scope nunca puede mover fondos ni revocar nada.

Desbloquea: POST /v1/api/wallet/approvals

liquidity:read - lecturas de liquidez y LP​

Permite que tu clave verifique si la liquidez de un token es real y dónde están los tokens LP: contexto del pool, custodia del LP, contexto de locks y quemas.

Desbloquea: POST /v1/api/intel/liquidity

GET /v1/api/health no necesita ninguna clave, y GET /v1/api/me y GET /v1/api/discover funcionan con cualquier clave válida, sin importar sus scopes.

Puedes editar los scopes de una clave en cualquier momento en el portal. Si una llamada falla con 403 scope_denied, la clave simplemente no tiene el scope que ese endpoint necesita.

Rotación y revocación​

  • Revocar elimina una clave. Deja de autenticar en menos de un minuto.
  • Rotar crea una clave de reemplazo con el mismo nombre, scopes y nivel, la muestra una vez y revoca la clave antigua en el mismo paso. Úsala ante cualquier sospecha de filtración y de forma periódica.

Restricciones opcionales​

Por cada clave puedes además crear listas de permitidos:

  • Orígenes (orígenes exactos o subdominios con comodín como https://*.yourapp.com) - las solicitudes que presenten un Origin distinto son rechazadas.
  • IPs / rangos CIDR - las solicitudes desde otras direcciones son rechazadas.

Las listas vacías significan sin restricción.

De dónde vienen las claves​

Las claves se crean únicamente en el portal de desarrolladores de autoservicio usando tu cuenta existente de Cognivo. No hay emisión manual/heredada de claves para nuevas integraciones.