Aller au contenu principal

Référence des endpoints

Ce qu'est cette page​

La Cognivo Developer API permet à votre propre code de poser à Cognivo les mêmes questions que celles auxquelles l'app répond. Tous les endpoints se trouvent sous https://api.cognivolabs.io/v1/api.

Utilisez-la quand vous voulez qu'une vérification Cognivo s'exécute ailleurs que dans l'app : dans votre propre bot, un tableau de bord, une tâche de tableur, ou un script nocturne qui surveille une liste de tokens.

Les endpoints d'intelligence sont en POST avec un corps JSON. C'est délibéré : un aperçu de lien, un crawler ou un préchargement de navigateur ne peut jamais déclencher une exécution en chargeant une URL. Le GET n'existe que pour health, me et discover.

Où trouver cela dans l'app​

Connectez-vous à l'app Cognivo, ouvrez Developers dans la barre latérale gauche sous Account, puis sélectionnez l'onglet Endpoints.

L'onglet Endpoints de la page Developers, où chaque endpoint Cognivo est listé avec la permission dont il a besoin et ce qu'il coûte.Agrandir l'image

Cet onglet est une référence, pas un exécuteur. Il liste tous les endpoints en direct avec un exemple copiable, la permission dont la clé a besoin, et le prix en crédits. La carte Permissions explained regroupe ces permissions en trois : Intelligence (pourquoi ça baisse, wallets d'équipe, risque, PnL de wallet, mouvements exacts), Security (approbations de tokens) et Liquidity (liquidité, verrouillages et burns). N'accordez à chaque clé que les permissions dont elle a besoin.

Vous préférez une version lisible par machine ? La spécification OpenAPI complète couvre tout ce qui figure sur cette page.

L'enveloppe de réponse​

Chaque endpoint répond avec la même enveloppe. Les identifiants et horodatages des exemples ci-dessous sont des valeurs fictives. Succès :

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 2,
    "generated_at": "2026-07-09T00:00:00.000Z"
  }
}
  • data est le résultat lui-même. Sa forme varie selon l'endpoint.
  • meta.request_id est un identifiant unique pour cet appel. Conservez-le, le support peut retracer un appel à partir de lui.
  • meta.credits_charged est ce que l'appel a coûté : le prix de l'endpoint pour un appel payant réussi, et 0 pour les endpoints gratuits ainsi que pour tout résultat en échec ou honnêtement vide.
  • meta.generated_at indique quand le résultat a été produit.
  • meta.chain apparaît sur les appels spécifiques à une chaîne, et meta.sources apparaît quand le résultat cite des sources.

Échec :

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

error est un code stable lisible par machine. message est une indication facultative destinée aux humains. La liste complète se trouve sur Limites de débit et erreurs.

Champs de corps courants​

  • chain vaut eth (Ethereum), base (Base) ou bsc (BNB Chain), et n'est pas sensible à la casse.
  • address, wallet et token sont des adresses EVM 0x de 40 caractères hexadécimaux.

Chaque exemple utilise l'espace réservé YOUR_API_KEY. Dans du vrai code, chargez la clé depuis une variable d'environnement ou un gestionnaire de secrets. Ne la codez jamais en dur.

Ce que coûte chaque endpoint​

Les clés en direct sont en libre-service et fonctionnent au paiement à l'usage. Une nouvelle clé en direct exécute ces endpoints immédiatement, et chaque appel réussi est facturé en crédits Cognivo sur le solde de votre compte. Les appels en échec ne sont jamais facturés, et un appel réussi est facturé exactement une fois, si bien qu'un envoi répété de la même opération ne peut pas vous facturer deux fois.

Chaque compte reçoit 5 crédits gratuits par jour, réinitialisés à minuit UTC. Si votre solde ne peut pas couvrir un appel, vous obtenez 402 payment_required et rien n'est facturé. Rechargez sur la page de facturation de votre compte et réessayez. Les clés sandbox (cogv_test_) ne peuvent pas exécuter d'intelligence en direct. Voir Facturation et crédits.

EndpointCrédits par appel réussi
POST intel/liquidity2
POST intel/risk2
POST wallet/approvals2
POST intel/why-down3
POST intel/team-wallets5
POST wallet/exact-movements5
POST wallet/pnl10
POST contract/analysisgratuit
GET health, GET megratuit
GET discovergratuit, avec un plafond de débit strict

Service​

GET /v1/api/health​

Vérifie que l'API Cognivo est en ligne. Aucune clé d'API nécessaire.

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

Réponse, qui n'est pas l'enveloppe standard, par conception :

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

Si l'API publique est désactivée, vous obtenez 404 public_api_disabled ici aussi, si bien que cet endpoint sert également de vérification de disponibilité.

GET /v1/api/me​

Affiche des détails sur la clé appelante : son palier, ses permissions et sa limite de débit. Fonctionne avec toute clé active, et est gratuit. Pour les clés en direct en libre-service, il affiche aussi le credits_balance du compte propriétaire et des conseils top_up, ainsi que l'access_mode de la clé.

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": "…" }
}

Limites : il n'affiche que la clé masquée, jamais le matériel complet de la clé. credits_balance peut revenir à null, ce qui signifie que Cognivo n'a pas pu lire le solde à cet instant, et non que le solde est nul.

Les endpoints restants suivent tous la même forme d'appel que les exemples ci-dessous. Remplacez le chemin et les champs du corps.

Intelligence sur les tokens​

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

Une lecture en langage clair des raisons pour lesquelles le prix d'un token baisse, construite à partir de l'activité on-chain récente : ventes massives, liquidité retirée, mouvements des wallets du propriétaire ou de l'équipe.

Prix affiché : 3 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

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();

Réponse : l'enveloppe standard. data contient le facteur dominant et les observations on-chain qui le sous-tendent, avec meta.chain renseigné.

Limites : cette lecture a besoin d'activité récente pour dire quoi que ce soit d'utile, donc un token avec très peu d'historique de trading donne une réponse maigre. Ce sont des signaux, pas des conseils financiers.

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

Fait ressortir les wallets liés à l'équipe ou à la trésorerie d'un token : wallets de déploiement, de propriétaire et de contrôleur, ainsi que ce qu'ils ont fait récemment.

Prix affiché : 5 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

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

Réponse : l'enveloppe standard. data liste les wallets identifiés et leur comportement récent, souvent avec meta.sources.

Limites : les wallets sont identifiés à partir de relations on-chain telles que le déploiement, la propriété et le contrôle. Cognivo ne peut pas voir la structure d'équipe hors chaîne, donc une liste vide signifie que rien n'était rattachable on-chain, et non qu'un token n'a pas d'équipe.

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

Vérifie la liquidité, les verrouillages et les burns d'un token avec des preuves on-chain : contexte des pools, qui détient les tokens LP, et contexte de verrouillage ou de burn.

Prix affiché : 2 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

Les booléens facultatifs metadata, locks et full ajoutent les métadonnées de pool, la preuve de verrouillage horodatée, et la lecture la plus complète 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}'

Réponse : l'enveloppe standard. data contient l'identité du token, un instantané de marché, et la garde des LP avec le contexte de verrouillage ou de burn.

Limites : la provenance historique détaillée des burns n'est pas exposée en v1. Le contexte de verrouillage couvre les schémas de locker reconnus, si bien qu'un locker personnalisé inhabituel peut se lire comme une simple garde plutôt qu'un verrouillage. Lisez cela comme « non vérifié », et non comme « non verrouillé ».

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

Les Cognivo Risk Signals pour un contrat de token, adaptés à la chaîne, avec une lecture des drapeaux rouges en solution de repli.

Prix affiché : 2 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

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

Réponse : l'enveloppe standard. data contient les signaux et les drapeaux trouvés pour le token.

Limites : un résultat propre ne signifie pas que le token est sûr. Il signifie qu'aucun drapeau rouge connu n'a été trouvé au moment de la lecture.

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

Preuves de contrat et de contrôle pour une adresse de contrat : existe-t-il, qui le possède, la propriété a-t-elle été renoncée, est-ce un proxy et qui l'administre, qui l'a déployé, quels wallets peuvent être attribués comme contrôleurs ou équipe, et le code source est-il vérifié.

Coût : 0 crédit. Cet endpoint est gratuit par décision, sur toutes les formules. Rien n'est déduit.

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

Réponse : l'enveloppe standard. data contient contract, ownership, proxy, deployer, controllers, source_verification, limitations et unavailable.

Chaque champ vous indique d'où il vient. meta.provenance associe chaque champ à exactement l'une de ces valeurs :

ÉtiquetteCe que cela signifie
verified_onchainLu depuis un nœud de ce réseau au moment de votre requête. Un fait.
augmentedCognivo Augmented Intelligence : fourni par une source extérieure, recoupé mais non prouvé par Cognivo.
interpretationLa lecture des faits par Cognivo. Un jugement, pas un fait.
unavailableCognivo n'a pas pu l'obtenir. La raison figure dans data.unavailable.

Rien n'est deviné, mis par défaut ni renvoyé à zéro pour combler un vide.

meta.chain_data_source.cognivo_grounded vous indique si Cognivo exploite l'infrastructure d'où provient la lecture. Cognivo fait tourner son propre nœud Ethereum, donc les lectures Ethereum sont true. Les lectures Base et BNB Chain proviennent d'une infrastructure RPC externe, elles sont donc false. Ces lectures sont exactes, mais elles ne sont pas servies depuis du matériel contrôlé par Cognivo, et Cognivo le dit plutôt que de vous laisser supposer le contraire.

Limites sur Base, également renvoyées dans data.limitations :

  • Le graphe de contrôleurs approfondi est réservé à Ethereum. Sur Base, l'attribution des contrôleurs et de l'équipe provient d'une lecture plus restreinte des rôles de wallets.
  • Les preuves de déploiement sur Base proviennent d'une source extérieure, et non d'une lecture d'archive Cognivo. Traitez-les comme une piste solide, pas comme un fait prouvé.
  • Les calendriers de verrouillage de liquidité ne sont pas décodés sur Base. Utilisez POST /v1/api/intel/liquidity pour la garde des LP et les preuves de burn, et n'interprétez pas un verrouillage manquant comme un verrouillage absent.

Cet endpoint ne rapporte que des preuves de contrôle du contrat. Il ne dit rien de la liquidité, et un résultat propre ne signifie jamais que le contrat est sûr.

En lecture seule : rien n'est signé, aucune transaction n'est construite, rien n'est diffusé, et aucun wallet n'est délégué.

Intelligence sur les wallets​

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

Les profits et pertes d'un wallet sur un token, calculés à partir de swaps on-chain fondés. wallet et token sont tous deux obligatoires.

Prix affiché : 10 crédits par appel réussi. Les appels en échec, et les résultats 422 sans données, ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

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

Réponse : l'enveloppe standard. data contient le chiffre réalisé, et un chiffre latent pour la position encore détenue lorsqu'un prix de revient défendable existe.

Limites : lorsqu'aucun prix de revient défendable ne peut être établi, le chiffre latent revient à null plutôt qu'en un nombre inventé. Lorsque le wallet n'a aucune transaction valorisée dans ce token, l'appel renvoie 422 (par exemple insufficient_data), ce qui signifie que Cognivo n'a pas pu calculer un chiffre honnête, et non que le profit était nul. Un 422 n'est jamais facturé. Les swaps que Cognivo n'a pas pu valoriser sont affichés comme non valorisés plutôt qu'écartés.

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

Liste les approbations de dépense de tokens qu'un wallet a accordées, et signale les autorisations illimitées.

Prix affiché : 2 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

Les paramètres facultatifs limit et offset permettent de paginer de grands ensembles d'approbations.

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

Réponse : l'enveloppe standard. data contient la liste des approbations avec le dépensier, le token et le contexte d'autorisation.

Limites : c'est en lecture seule. Cognivo ne déplace jamais de fonds et ne peut pas révoquer une approbation à votre place. La révocation se fait toujours depuis votre propre wallet. Une liste vide est une réponse réussie valide, et elle n'est pas facturée.

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

Liste les mouvements de tokens exacts d'un wallet : achats, ventes et transferts. token est facultatif et restreint la lecture à un seul token.

Prix affiché : 5 crédits par appel réussi. Les appels en échec ne sont jamais facturés. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

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

Réponse : l'enveloppe standard. data contient la liste des mouvements avec les décomptes.

Limites : l'appel renvoie les mouvements les plus récents, jusqu'à 25 par appel. Un wallet sans mouvement correspondant renvoie 422 plutôt qu'un historique inventé.

Discover​

GET /v1/api/discover​

Le flux Discover public : des cartes d'intelligence on-chain récentes et anonymisées, chacune avec l'identité du token, une accroche et des points clés. Fonctionne avec toute clé active. Gratuit, sous une limite quotidienne stricte.

Paramètres de requête : limit (1 à 50, 20 par défaut) et chain facultatif (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": "…" }
}

Limites : les valeurs de limit en dehors de 1 à 50 sont ramenées dans l'intervalle. Le flux ne contient que l'intelligence que les utilisateurs ont choisi de publier, c'est donc un échantillon et non une couverture complète.

Pas encore disponible​

Ces éléments sont listés par transparence et ne renvoient rien aujourd'hui :

  • Le traçage approfondi de wallet via l'API (wallet/trace). Le flux de tâches asynchrone est réservé au chat et à l'app pour l'instant.
  • La récupération de rapport par identifiant (reports/:id).
  • Les webhooks.
  • Les endpoints Solana.

Étapes suivantes​

Effectuez votre premier appel avec le Démarrage rapide, créez et cadrez une clé avec Authentification et clés, et lisez Limites de débit et erreurs avant de planifier quoi que ce soit.