クイックスタート

最初の呼び出しまで 30 秒：プロジェクトを作成し、ライブキーを作成し、残高を確認し、コマンドを 1 つ貼り付けるだけ。ライブキーはセルフサービスで、すぐに動きます。例の呼び出しが成功すると 2 クレジットが課金され、失敗した呼び出しに課金されることは決してありません。

1. プロジェクトとライブキーを作成する

Developer ポータルを開き、Cognivo アカウントでサインインします。
プロジェクトを作成します（例：「My trading bot」）。
ライブ API キーを作成します。必要な権限（スコープ）を選択してください。このクイックスタートでは、Token and wallet intelligence（intel:read）と Liquidity reads（liquidity:read）を付与します。
キーは今すぐコピーしてください。 表示されるのは一度だけで、以降はマスクされた形（cogv_live_****abcd）しか見られません。紛失した場合はキーをローテーションしてください。

キーには 2 つの環境があります：

cogv_live_... - 標準のキー。セルフサービスですぐに動き、成功した呼び出しごとにアカウントのクレジット残高から Cognivo クレジットで従量課金されます。トライアルも承認も不要です。
cogv_test_... - サンドボックスキー。Sandbox と明確にラベル付けされ、限定的なデモとインテグレーションテスト専用です。ライブインテリジェンスは実行できず、厳しい上限（25 リクエスト/時、100/日、1/秒）があります。

2. キーと残高を確認する

curl 'https://api.cognivolabs.io/v1/api/me' \
  -H 'X-API-Key: YOUR_API_KEY'

マスクされたキー、プロジェクト、環境、スコープ、1 時間あたりのレート制限に加えて、access_mode、アカウントの credits_balance（次の呼び出しの支払い可否を確認できます）、top_up ガイダンスが返ってきます。この呼び出しは常に無料です。

3. 最初のライブ呼び出しを実行する（curl）

インテリジェンスエンドポイントは JSON ボディ付きの POST を使います。次のコマンドは、実在する Base 上のトークン（RWA Inc、デモに使っている公開コントラクト）に対して、本物の流動性チェックを実行します。作成したばかりのライブキーで、そのまますぐに実行できます：

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

"ok": true とともに、data にトークンの識別情報（名前/シンボル）、マーケットスナップショット、LP/ロックの状況が表示されるはずです。成功時にはそのエンドポイントの価格（流動性は 2 クレジット）が課金され、meta.credits_charged がそれを確認できます。代わりにコード payment_required の 402 エラーが返った場合は、Cognivo クレジット残高が呼び出しをカバーできていません。何も課金されていないので、Cognivo アカウントの課金ページでチャージして、同じコマンドをもう一度実行してください。失敗した呼び出しに課金されることは決してありません。準備ができたら、address を eth、base、bsc 上の任意のトークンコントラクトに差し替えてください。

キーは秘密にしてください

本物の API キーを公開リポジトリ、チャット、クライアントサイドのコードに貼り付けてはいけません。キーは作成時に一度しか表示されません。漏洩した場合は、ポータルでローテーションしてください。

4. 同じ呼び出しを 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, // never hardcode keys
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();
if (json.ok) {
  console.log(json.data);        // the intelligence result
  console.log(json.meta.request_id); // keep for support/debugging
} else {
  console.error(json.error);     // e.g. "payment_required": top up, then retry
}

5. レスポンスの形

すべてのエンドポイントは同じエンベロープで応答します（以下の ID とタイムスタンプは例示用の値です）：

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_...",
    "credits_charged": 2,
    "generated_at": "2026-07-08T00:00:00.000Z"
  }
}

失敗時（課金されません）：

{ "ok": false, "error": "payment_required", "request_id": "capi_..." }

課金とチャージ

成功した呼び出しごとの従量課金。 成功した呼び出しごとに、そのエンドポイントの公開クレジット価格が、プロジェクトオーナーの Cognivo クレジット残高（Chat や dApp で使っているのと同じクレジット）から差し引かれます。サブスクリプションも最低利用額もありません。
チャージする場所。 dApp の Cognivo アカウントの課金ページです。GET /v1/api/me が現在の credits_balance と top_up ガイダンスを表示します。
失敗した呼び出しには決して課金されません。 エラー、タイムアウト、拒否された呼び出しは無料です。402 payment_required 自体も無料です。チャージして再試行してください。
正直な空の結果は無料です。 wallet/pnl は、そのトークンでの価格付き取引がないウォレットには 422 を返し、空の wallet/approvals リストも有効な答えです。どちらにも課金されません。
再試行は安全です。 成功した呼び出しへの課金はちょうど 1 回だけです。同じ操作を重複して送信しても二重課金にはなりません。5xx や 429 にはバックオフつきで再試行し、402 にはまずチャージしてください。
停止。 停止されたキー（または無効化されたプロジェクト）は何も実行できず、課金されることもありません。理由はポータルに表示されます。

キーを安全に保つ

API は必ずサーバーから呼び出し、ブラウザやモバイルのクライアントコードからは決して呼び出さないでください。
キーは環境変数またはシークレットマネージャーに保存してください。
キーが漏洩した可能性がある場合は、ポータルで失効（revoke）またはローテーションしてください。古いキーは 1 分以内に無効になります。

1. プロジェクトとライブキーを作成する​

2. キーと残高を確認する​

3. 最初のライブ呼び出しを実行する（curl）​

4. 同じ呼び出しを JavaScript / TypeScript で​

5. レスポンスの形​

課金とチャージ​

キーを安全に保つ​