エンドポイントリファレンス

すべてのエンドポイントは https://api.cognivolabs.io/v1/api 配下にあります。インテリジェンスエンドポイントは JSON ボディ付きの POST です（これにより、リンクプレビュー、クローラー、プリフェッチャーが実行をトリガーしてしまうことを防ぎます）。GET は health、me、discover にのみ存在します。

機械可読な形式が必要ですか？完全な OpenAPI 仕様がこのページの内容をすべてカバーしています。

レスポンスエンベロープ

すべてのエンドポイントは同じエンベロープで応答します（このページの例に含まれる ID とタイムスタンプは例示用の値です）。成功時：

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

data - インテリジェンス結果そのもの。形はエンドポイントごとに異なります
meta.request_id - この呼び出しの一意な ID。保管しておけば、サポートがこれから呼び出しを追跡できます
meta.credits_charged - この呼び出しにかかったクレジット：成功した有料呼び出しではそのエンドポイントのクレジット価格。無料エンドポイント、トライアル枠での呼び出し、失敗した結果や正直な空の結果では 0
meta.generated_at - 結果が生成された時刻
meta.chain はチェーン固有の呼び出しで現れ、meta.sources（ソースラベルの配列）は結果がソースを引用する場合に現れます

失敗時：

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

error は安定した機械可読コードです（レート制限とエラーを参照）。message は人間向けの任意のヒントです。

共通のボディフィールド

chain - eth、base、bsc のいずれか（大文字小文字は区別しません）
address / wallet / token - 0x… の EVM アドレス（16 進数 40 文字）

以下のすべての例ではプレースホルダー YOUR_API_KEY を使っています。実際のコードでは環境変数またはシークレットマネージャーからキーを読み込み、決してハードコードしないでください。

料金

ライブキーはセルフサービスの従量課金です。新しいライブキーはこれらのエンドポイントをすぐに実行でき、成功した呼び出しごとにアカウントの残高から Cognivo クレジットが課金されます。失敗した呼び出しには決して課金されず、成功した呼び出しへの課金はちょうど 1 回だけです（同じ操作を重複して送信しても二重課金にはなりません）。残高が呼び出しをカバーできない場合は 402 payment_required が返り（課金なし）、Cognivo アカウントの課金ページでチャージして再試行してください。サンドボックス（cogv_test_）キーはライブインテリジェンスを実行できません。レート制限、エラー、課金を参照してください。エンドポイントごとの価格：

エンドポイント	成功した呼び出しごとのクレジット
`POST intel/liquidity`	2
`POST intel/risk`	2
`POST wallet/approvals`	2
`POST intel/why-down`	3
`POST intel/team-wallets`	5
`POST wallet/exact-movements`	5
`POST wallet/pnl`	10
`GET health`、`GET me`	無料
`GET discover`	無料（厳しめのレート上限つき）

サービス

GET /v1/api/health

死活監視プローブ。API キーは不要です。

curl 'https://api.cognivolabs.io/v1/api/health'

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

レスポンス（意図的に標準エンベロープではありません）：

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

制限事項：パブリック API がオフになっている場合、ここでも 404 public_api_disabled が返るため、このエンドポイントは可用性チェックも兼ねます。

GET /v1/api/me

呼び出し元のキーを内省します。スコープ：任意の有効なキー。無料。ライブのセルフサービスキーでは、オーナーアカウントの credits_balance（一時的に取得できない場合は null）と top_up ガイダンス、そしてキーの access_mode も表示されます。

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": "Top up Cognivo credits on your account billing page in the dApp."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

制限事項：表示されるのはマスクされたキーのみで、完全なキーの内容が返されることはありません。credits_balance はオーナーアカウントの Cognivo クレジット残高で、一時的に取得できない場合は null になることがあります。

トークンインテリジェンス

POST /v1/api/intel/why-down - スコープ `intel:read`

このトークンはなぜ下がっているのか：直近のオンチェーン活動を根拠に基づいて読み取り、支配的な要因（売り、LP の引き揚げ、オーナーの資金移動）を探します。

費用：成功した呼び出しごとに 3 クレジット。このスコープを持つライブキーならセルフサービスで実行できます。失敗した呼び出しには決して課金されません。

リクエストボディ：

{ "chain": "base", "address": "0xTOKEN_CONTRACT" }

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

レスポンス：標準エンベロープ。data に下落分析（支配的な要因と、それを裏付けるオンチェーン観測）が入り、meta.chain がセットされます。

制限事項：有用なことを言うには直近の活動が必要です。取引履歴がほとんどないトークンでは、読み取りが薄くなることがあります。シグナルであり、投資助言ではありません。

POST /v1/api/intel/team-wallets - スコープ `intel:read`

トークンのチーム・コントローラーウォレットスキャン：デプロイヤー、オーナー、コントローラーのウォレットと、その直近の挙動。

費用：成功した呼び出しごとに 5 クレジット。このスコープを持つライブキーならセルフサービスで実行できます。失敗した呼び出しには決して課金されません。

リクエストボディ：

{ "chain": "eth", "address": "0xTOKEN_CONTRACT" }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/team-wallets", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data に特定されたチーム/コントローラーウォレットとその直近の挙動が一覧され、多くの場合 meta.sources が付きます。

制限事項：ウォレットの特定はオンチェーンの関係性（デプロイ、所有、コントロール）に基づきます。オフチェーンのチーム構成は見えません。

POST /v1/api/intel/liquidity - スコープ `liquidity:read`

トークンのプール/LP ステータス：プールの状況、LP のカストディ、ロック/バーンの状況。

費用：成功した呼び出しごとに 2 クレジット。このスコープを持つライブキーならセルフサービスで実行できます。失敗した呼び出しには決して課金されません。

リクエストボディ（任意のブール値 metadata、locks、full により、根拠のあるプールメタデータ、時限ロックの証明、利用可能な最大限の読み取りが追加されます）：

{ "chain": "base", "address": "0xTOKEN_CONTRACT", "locks": true }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/liquidity", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0xTOKEN_CONTRACT", locks: true }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data にトークンの識別情報、マーケットスナップショット、LP カストディとロック/バーンの状況が入ります。

制限事項：深い過去のバーン来歴は v1 では公開されません。ロックの状況は既知のロッカーパターンをカバーしており、未知のカスタムロッカーはロックされていないカストディとして読み取られる場合があります。

POST /v1/api/intel/risk - スコープ `intel:read`

トークンに対するチェーン対応の Cognivo リスクシグナル（フォールバックとしてレッドフラグの読み取り）。

リクエストボディ：

{ "chain": "bsc", "address": "0xTOKEN_CONTRACT" }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/intel/risk", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "bsc", address: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data にそのトークンについて見つかったリスクシグナルとフラグが入ります。

制限事項：クリーンな結果は決して「安全」を意味しません。読み取り時点で既知のレッドフラグが見つからなかった、という意味です。

ウォレットインテリジェンス

POST /v1/api/wallet/pnl - スコープ `intel:read`

あるウォレットの 1 トークンにおける実現損益を、根拠のあるウォレット活動から算出します。wallet と token の両方が必須です。

費用：成功した呼び出しごとに 10 クレジット。このスコープを持つライブキーならセルフサービスで実行できます。失敗した呼び出しと、データなしの 422 結果には決して課金されません。

リクエストボディ：

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/pnl", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET", token: "0xTOKEN_CONTRACT" }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data にそのウォレット/トークンの組み合わせに対する実現損益の計算結果が入ります。

制限事項：ウォレットにそのトークンでの価格付き取引がなく、公正な数字が算出できない場合は 422（例：insufficient_data）を返します。Cognivo が数字をでっち上げることは決してなく、422 に課金されることもありません。実現損益のみが対象で、未実現（保有中）ポジションはここでは評価されません。

POST /v1/api/wallet/approvals - スコープ `security:read`

ウォレットに対して保持されているトークン承認を返し、無制限の許可（allowance）にフラグを立てます。読み取り専用です。Cognivo が資金を動かすことは決してなく、代わりに取り消すこともできません。

リクエストボディ（limit と offset で大きな承認セットを任意でページングできます）：

{ "chain": "eth", "address": "0xWALLET" }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/approvals", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "eth", address: "0xWALLET" }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data にスペンダー、トークン、許可の状況を含む承認リストが入ります。

制限事項：空の結果（承認が見つからない）は有効かつ成功の応答であり、課金されません。

POST /v1/api/wallet/exact-movements - スコープ `intel:read`

ウォレットの直近の正確な資金移動（オーナー/デプロイヤー向けの読み取り）。token は任意で、指定すると 1 つのトークンに絞り込めます。

リクエストボディ：

{ "chain": "base", "wallet": "0xWALLET", "token": "0xTOKEN_CONTRACT" }

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

const res = await fetch("https://api.cognivolabs.io/v1/api/wallet/exact-movements", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", wallet: "0xWALLET" }),
});
const json = await res.json();

レスポンス：標準エンベロープ。data に件数付きの資金移動リストが入ります。

制限事項：返されるのは最新の資金移動（1 回の呼び出しにつき最大 25 件）です。該当する動きがないウォレットには、でっち上げの履歴ではなく 422 が返ります。

Discover

GET /v1/api/discover

公開 Discover フィード：直近の高品質な公開インテリジェンスカード（トークンの識別情報、フック、箇条書き）。スコープ：任意の有効なキー。無料（厳しめのレート上限つき）。

クエリパラメータ：limit（1-50、デフォルト 20）と任意の chain（eth、base、bsc）。

curl 'https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base' \
  -H 'X-API-Key: YOUR_API_KEY'

const res = await fetch("https://api.cognivolabs.io/v1/api/discover?limit=10&chain=base", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const json = await res.json();

レスポンス：

{
  "ok": true,
  "data": { "cards": [ { "...": "public intelligence card" } ], "total": 10 },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

制限事項：1-50 の範囲外の limit 値は範囲内に丸められます。フィードにはユーザーが公開を選択したインテリジェンスだけが含まれるため、サンプルであって全体をカバーするものではありません。

計画中（まだ利用できません）

以下はロードマップの透明性のために記載しており、現時点では何も返しません：

API 経由のディープウォレットトレース（wallet/trace） - 非同期ジョブフローは当面 Chat/dApp 専用です
ID によるレポート取得（reports/:id）
Webhook
Solana エンドポイント

レスポンスエンベロープ​

共通のボディフィールド​

料金​

サービス​

GET /v1/api/health​

GET /v1/api/me​

トークンインテリジェンス​

POST /v1/api/intel/why-down - スコープ intel:read​

POST /v1/api/intel/team-wallets - スコープ intel:read​

POST /v1/api/intel/liquidity - スコープ liquidity:read​

POST /v1/api/intel/risk - スコープ intel:read​

ウォレットインテリジェンス​

POST /v1/api/wallet/pnl - スコープ intel:read​

POST /v1/api/wallet/approvals - スコープ security:read​

POST /v1/api/wallet/exact-movements - スコープ intel:read​

Discover​

GET /v1/api/discover​

計画中（まだ利用できません）​

レスポンスエンベロープ

共通のボディフィールド

料金

サービス

GET /v1/api/health

GET /v1/api/me

トークンインテリジェンス

POST /v1/api/intel/why-down - スコープ `intel:read`

POST /v1/api/intel/team-wallets - スコープ `intel:read`

POST /v1/api/intel/liquidity - スコープ `liquidity:read`

POST /v1/api/intel/risk - スコープ `intel:read`

ウォレットインテリジェンス

POST /v1/api/wallet/pnl - スコープ `intel:read`

POST /v1/api/wallet/approvals - スコープ `security:read`

POST /v1/api/wallet/exact-movements - スコープ `intel:read`

Discover

GET /v1/api/discover

計画中（まだ利用できません）