Aller au contenu principal

Démarrage rapide

Votre premier appel à l'API Cognivo​

La Cognivo Developer API permet à votre propre code de poser les mêmes questions on-chain que celles que vous pouvez poser dans la dApp et dans Cognivo Chat. Cette page suit le chemin le plus court : créer un projet, créer une clé, lancer un vrai appel, lire la réponse.

Quand l'utiliser​

Utilisez l'API lorsque vous voulez des vérifications de tokens, de wallets ou de liquidité à l'intérieur de ce que vous construisez, par exemple un bot de trading, un tableau de bord interne, une tâche d'alerte ou un service backend, plutôt que de passer par la dApp à chaque fois. Si vous voulez seulement lancer des vérifications à la main, la dApp et Chat le font déjà et vous n'avez pas besoin de clé.

Où la trouver​

Connectez-vous à la dApp, ouvrez Account dans la barre latérale, puis sélectionnez Developers. Les visiteurs non connectés ne voient qu'un écran de présentation, donc connectez-vous d'abord. Tout ce qui figure sur cette page se déroule sur cet unique écran.

Créez un projet, puis une clé​

Un projet regroupe vos clés d'API et leur usage, alors commencez par là.

  1. Sélectionnez Nouveau projet pour ouvrir le court formulaire sous le sélecteur de projet.
  2. Saisissez un nom dans Nom du projet pour pouvoir distinguer vos projets plus tard.
  3. Sélectionnez Créer pour ajouter le projet, ou Annuler pour fermer le formulaire sans enregistrer.
  4. Sélectionnez Créer une clé live pour générer une clé pour ce projet, puis envoyez-la avec vos requêtes depuis votre propre code.
Les commandes de projet sur la page Developers, où vous créez un projet avant de créer une clé.Agrandir l'image

Le nom du projet n'est qu'une étiquette pour vous. Il n'apparaît pas dans vos requêtes et vous pouvez créer plusieurs projets, jusqu'à la limite indiquée sur la page.

Lorsque vous sélectionnez Create live key, Cognivo affiche la clé complète une seule fois, dans une boîte de dialogue dotée d'un bouton de copie. Copiez-la à ce moment-là et conservez-la en lieu sûr. Ensuite, la page n'affiche plus qu'une version masquée, le préfixe et les quatre derniers caractères, car Cognivo stocke la clé sous une forme qu'il ne peut pas relire. Si vous perdez une clé, ou si vous pensez qu'elle a fuité, utilisez Rotate ou Revoke sur la ligne de la clé. L'ancienne clé cesse de fonctionner immédiatement.

Chaque clé porte également des Permissions, qui contrôlent ce qu'elle peut appeler : Intelligence, Security et Liquidity. N'accordez à une clé que les permissions dont elle a besoin. L'exemple ci-dessous nécessite Liquidity.

Deux autres boutons se trouvent sur la même carte. Top up credits vous emmène vers votre page de facturation. Enterprise access ouvre le parcours de support, et c'est le seul chemin qui implique une demande, pour des tarifs sur mesure ou des limites plus élevées. Une clé en direct normale ne nécessite aucune approbation et fonctionne dès sa création.

Lancez l'appel d'exemple​

Ouvrez l'onglet Quickstart. Il contient un exemple fonctionnel que vous pouvez copier et exécuter sans rien écrire vous-même.

L'onglet Démarrage rapide de la page Developers, où vous copiez un exemple d'appel qui fonctionne.Agrandir l'image

La carte Test keys vs live keys explique la différence. Une clé de test effectue des appels sans risque avec des limites strictes, ce qui convient bien à la mise en place. Une clé en direct effectue de vrais appels qui sont facturés sur votre solde de crédits Cognivo. La carte Test a live endpoint donne ensuite cinq étapes numérotées et la commande elle-même, avec une icône de copie.

La commande est une vraie vérification de liquidité sur un vrai contrat 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"}'

Le même appel depuis JavaScript ou 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);
}

Ce que vous recevez​

Chaque endpoint répond avec la même enveloppe, que montre le bloc Expected response de l'onglet Quickstart :

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

data contient le résultat. meta.request_id mérite d'être journalisé, car le support peut retrouver un appel précis grâce à lui. meta.credits_charged vous indique exactement ce que cet appel a coûté.

Un champ peut revenir vide, inconnu ou indisponible. Cela signifie que Cognivo n'a pas pu le vérifier à partir des données auxquelles il a accès, et non qu'il n'y a rien. Lisez cela comme « non confirmé », et ne considérez pas un résultat silencieux comme un feu vert. Cognivo rapporte ce qu'il a vérifié et ce qu'il a trouvé, et rien dans une réponse ne prouve qu'un token est une arnaque ni qu'il est sûr.

Un appel en échec répond avec ok à false, un code error et un request_id. Les appels en échec ne sont pas facturés.

Coût, chaînes et limites​

  • Certains endpoints sont gratuits avec n'importe quelle clé active. D'autres sont facturés par appel réussi sur votre solde de crédits Cognivo. L'onglet Endpoints liste chaque endpoint avec son prix en crédits Cognivo, ou Free lorsqu'il est gratuit, alors vérifiez-y avant de construire sur un endpoint.
  • Vous n'êtes facturé que pour un appel réussi, et meta.credits_charged confirme le montant. Les erreurs, les délais dépassés et les appels bloqués ne coûtent rien.
  • Chaque compte reçoit 5 crédits gratuits par jour. Ils sont réinitialisés à minuit UTC et sont utilisés avant tout crédit payant.
  • L'API couvre aujourd'hui Ethereum, Base et BNB Chain. Certains endpoints prennent en charge moins de chaînes que d'autres.
  • Les clés de test sont strictement plafonnées et ne constituent pas un palier de production gratuit. Chaque ligne de clé de l'onglet Keys affiche les limites que Cognivo applique à cette clé en ce moment, qui peuvent être inférieures à la valeur par défaut du palier.
  • Une clé suspendue, ou une clé dans un projet suspendu, ne peut rien exécuter, et le portail en affiche la raison.

Gardez votre clé en sécurité​

Appelez l'API depuis un serveur, jamais depuis du code de navigateur ou d'application mobile. Conservez la clé dans une variable d'environnement ou un gestionnaire de secrets, jamais dans un dépôt public, un message de chat ou une capture d'écran. Si une clé a pu fuiter, faites-la tourner ou révoquez-la dans l'onglet Keys.

Étapes suivantes​

Lisez Authentification et clés pour les permissions et la gestion des clés en détail, Endpoints pour savoir ce que renvoie chaque appel et ce qu'il coûte, et Limites de débit et erreurs pour les nouvelles tentatives et les codes d'erreur. Pour votre solde de crédits et les rechargements, voir Facturation et crédits.