クイックスタート
最初の Cognivo API 呼び出し
Cognivo Developer API を使うと、dApp や Cognivo チャット で尋ねられるのと同じオンチェーンの問いを、あなた自身のコードから投げられます。このページは、その最短経路をたどります：プロジェクトを作り、キーを作り、実際の呼び出しを 1 回実行し、返ってきた答えを読む、という流れです。
使うタイミング
トレーディングボット、社内ダッシュボード、アラート用ジョブ、バックエンドサービスなど、自分が作っているものの中でトークン・ウォレット・流動性のチェックを行いたいときに API を使ってください。毎回 dApp をクリックして回る必要がなくなります。手作業でチェックを実行したいだけなら、dApp と Chat がすでにその役割を果たしているので、キーは必要ありません。
場所
dApp にサインインし、サイドバーの アカウント を開いて Developers を選びます。サインアウト状態の訪問者には案内画面しか表示されないので、先にサインインしてください。このページの内容はすべて、その 1 つの画面で行います。
プロジェクトを作り、次にキーを作る
プロジェクトは API キーとその利用状況をまとめる単位なので、まずここから始めます。
- 新規プロジェクト を選択すると、プロジェクト選択の下に短いフォームが開きます。
- 後でプロジェクトを見分けられるように、プロジェクト名 に名前を入力します。
- 作成 を選択するとプロジェクトが追加され、キャンセル を選択すると保存せずにフォームを閉じます。
- ライブキーを作成 を選択してそのプロジェクトのキーを作り、自分のコードからのリクエストに添えて送ります。
プロジェクト名はあなた自身のためのラベルにすぎません。リクエストには現れませんし、ページに表示される上限の範囲内で複数作成できます。
ライブキーを作成 を選ぶと、Cognivo はコピーボタン付きのダイアログで完全なキーをちょうど一度だけ表示します。そのときにコピーして、安全な場所に保管してください。その後は、プレフィックスと末尾 4 文字だけのマスクされた形しか表示されません。Cognivo はキーを読み戻せない形で保存しているためです。キーを紛失した場合や漏洩が疑われる場合は、キーの行にある ローテート または 失効 を使ってください。古いキーはただちに使えなくなります。
各キーには 権限 も紐づいており、何を呼び出せるかを制御します：Intelligence、Security、Liquidity の 3 つです。キーには必要な権限だけを与えてください。以下の例には Liquidity が必要です。
同じカードにはさらに 2 つのボタンがあります。クレジットをチャージ は課金ページに移動します。エンタープライズアクセス はサポートのフローを開き、カスタム料金や上限引き上げのために申請が必要になる唯一の経路です。通常のライブキーには承認は不要で、作成した瞬間から動きます。
サンプル呼び出しを実行する
クイックスタート タブを開きます。ここには、自分で何も書かずにコピーして実行できる動作するサンプルが載っています。
テストキーとライブキーの違い のカードが両者の違いを説明します。テストキーは厳しい上限のもとで安全な呼び出しを行うので、配線を確かめるのに向いています。ライブキーは実際の呼び出しを行い、Cognivo のクレジット残高から課金されます。続く ライブエンドポイントをテストする のカードには、番号付きの 5 つの手順とコマンド本体が、コピーアイコン付きで載っています。
このコマンドは、実在する 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"}'
JavaScript または 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);
}
返ってくるもの
どのエンドポイントも同じエンベロープで応答します。クイックスタートタブの 想定されるレスポンス ブロックがそれを示しています：
{
"ok": true,
"data": { "identity": { "name": "...", "symbol": "..." }, "marketSnapshot": {} },
"meta": {
"chain": "base",
"request_id": "capi_...",
"credits_charged": 0,
"generated_at": "..."
}
}
data に結果が入ります。meta.request_id はログに残しておく価値があります。サポートがこの値から個別の呼び出しを特定できるからです。meta.credits_charged は、その呼び出しにかかったコストを正確に示します。
フィールドが空、不明、または利用不可として返ってくることがあります。それは、Cognivo が到達できるデータからは確認できなかったという意味であり、そこに何も存在しないという意味ではありません。「未確認」と読んでください。静かな結果を問題なしのサインとして扱わないでください。Cognivo は何をチェックし、何を見つけたかを報告するだけであり、レスポンスの中の何かがトークンを詐欺だと証明したり、安全だと証明したりすることはありません。
失敗した呼び出しは、ok が false になり、error コードと request_id が返されます。失敗した呼び出しには課金されません。
コスト、チェーン、上限
- 一部のエンドポイントは、有効なキーがあれば無料です。それ以外は、成功した呼び出しごとに Cognivo のクレジット残高から課金されます。エンドポイント タブに、各エンドポイントの Cognivo クレジットでの価格、または無料の場合は Free が記載されているので、エンドポイントに対して実装を始める前にそこで確認してください。
- 課金されるのは成功した呼び出しに対してのみで、金額は
meta.credits_chargedで確認できます。エラー、タイムアウト、ブロックされた呼び出しには一切費用がかかりません。 - すべてのアカウントは 1 日あたり 5 クレジットの無料枠を受け取ります。UTC の午前 0 時にリセットされ、有料クレジットより先に消費されます。
- 現時点で API が対応しているのは Ethereum、Base、BNB Chain です。エンドポイントによっては、対応チェーンがこれより少ないものもあります。
- テストキーは厳しく制限されており、無料の本番向けプランではありません。キー タブの各キーの行には、Cognivo がそのキーに現在適用している上限が表示されます。ティアの既定値より低いこともあります。
- 停止されたキー、または停止されたプロジェクト内のキーは何も実行できず、その理由がポータルに表示されます。
キーを安全に保つ
API はサーバーから呼び出してください。ブラウザやモバイルアプリのコードから呼び出してはいけません。キーは環境変数またはシークレットマネージャーに保管し、公開リポジトリ、チャットのメッセージ、スクリーンショットには決して置かないでください。キーが漏洩した可能性がある場合は、キー タブでローテートまたは失効させてください。
次のステップ
権限とキーの取り扱い全般については 認証と API キー を、各呼び出しが返す内容とコストについては エンドポイント を、リトライとエラーコードについては レート制限とエラー をお読みください。クレジット残高とチャージについては 課金とクレジット をご覧ください。