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

このページについて

Cognivo Developer API を使うと、アプリが答えているのと同じ問いを、あなた自身のコードから Cognivo に尋ねられます。すべてのエンドポイントは https://api.cognivolabs.io/v1/api の配下にあります。

Cognivo のチェックをアプリ以外の場所で実行したいときに使ってください：自分のボットの中、ダッシュボード、スプレッドシートのジョブ、トークンのリストを毎晩監視するスクリプトなどです。

インテリジェンス系のエンドポイントは JSON ボディを伴う POST です。これは意図的な設計です：リンクのプレビュー、クローラー、ブラウザのプリフェッチが、URL を読み込むだけで実行を引き起こすことは決してありません。GET は health、me、discover にのみ存在します。

アプリ内での場所

Cognivo アプリにサインインし、左サイドバーの アカウント の下にある Developers を開いて、エンドポイント タブを選びます。

Developers ページのエンドポイントタブ。各 Cognivo エンドポイントが、必要な権限とかかるコストとともに一覧表示されます。画像を拡大

このタブはリファレンスであって、実行環境ではありません。稼働中のすべてのエンドポイントを、コピーできるサンプル、キーに必要な権限、クレジットでの価格とともに一覧表示します。権限の説明 のカードは、それらの権限を 3 つに分類しています：Intelligence（なぜ下がっているのか、チームウォレット、リスク、ウォレットの損益、正確な資金の動き）、Security（トークンの承認）、Liquidity（流動性、ロックとバーン）。各キーには必要な権限だけを与えてください。

機械可読な版がお好みですか。完全な OpenAPI 仕様 が、このページの内容をすべてカバーしています。

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

すべてのエンドポイントは同じエンベロープで応答します。以下の例に出てくる ID とタイムスタンプはプレースホルダーの値です。成功時：

{
  "ok": true,
  "data": { "...": "the result" },
  "meta": {
    "chain": "base",
    "request_id": "capi_9f2c41d8a0b34e7c9d5a1f02",
    "credits_charged": 2,
    "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（Ethereum）、base（Base）、bsc（BNB Chain）のいずれかで、大文字小文字は区別されません。
• address、wallet、token は 40 文字の 16 進からなる 0x の EVM アドレスです。

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

各エンドポイントのコスト

ライブキーはセルフサービスの従量課金です。新しいライブキーはこれらのエンドポイントをすぐに実行でき、成功した 呼び出しごとにアカウント残高から Cognivo クレジットが課金されます。失敗した呼び出しには決して課金されず、成功した呼び出しはちょうど一度だけ課金されるため、同じ操作を繰り返し送信しても二重に課金されることはありません。

すべてのアカウントは 1 日あたり 5 クレジットの無料枠を受け取り、UTC の午前 0 時にリセットされます。残高が呼び出しをカバーできない場合は 402 payment_required が返り、何も課金されません。アカウントの課金ページでチャージしてから再試行してください。サンドボックス（cogv_test_）キーはライブのインテリジェンスを実行できません。課金とクレジット をご覧ください。

エンドポイント	成功 1 回あたりのクレジット
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
POST contract/analysis	無料
GET health、GET me	無料
GET discover	無料、ただし厳しいレート上限あり

サービス

GET /v1/api/health

Cognivo API が稼働しているかを確認します。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 とチャージの案内 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": "Manage credits from your Cognivo account billing page."
  },
  "meta": { "request_id": "capi_...", "credits_charged": 0, "generated_at": "…" }
}

制限事項：表示されるのはマスクされたキーだけで、キーの本体が返ることは決してありません。credits_balance が null で返ることがありますが、それはその時点で Cognivo が残高を読み取れなかったという意味であり、残高がゼロという意味ではありません。

残りのエンドポイントは、以下の例と同じ呼び出しの形に従います。パスとボディのフィールドを差し替えてください。

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

POST /v1/api/intel/why-down、権限は Intelligence（intel:read）

トークンの価格が下がっている理由を、直近のオンチェーン活動から組み立てて平易な言葉で読み解きます：大量の売り、流動性の引き上げ、オーナーやチームのウォレットの動きなどです。

表示価格：成功 1 回あたり 3 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

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、権限は Intelligence（intel:read）

トークンのチームやトレジャリーに紐づくウォレットを浮かび上がらせます：デプロイヤー、オーナー、コントローラーのウォレットと、それらが最近何をしていたかです。

表示価格：成功 1 回あたり 5 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

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

レスポンス：標準のエンベロープです。data には特定されたウォレットと直近の挙動が並び、多くの場合 meta.sources を伴います。

制限事項：ウォレットは、デプロイ、所有権、支配関係といったオンチェーンの関係から特定されます。Cognivo はオフチェーンのチーム構成を見ることができないため、リストが空でも、それはオンチェーンで紐づけられるものがなかったという意味であり、そのトークンにチームがいないという意味ではありません。

POST /v1/api/intel/liquidity、権限は Liquidity（liquidity:read）

トークンの流動性、ロック、バーンをオンチェーンの証拠とともに確認します：プールの文脈、LP トークンの保有者、ロックやバーンの文脈です。

表示価格：成功 1 回あたり 2 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

任意の真偽値 metadata、locks、full を指定すると、プールのメタデータ、時刻付きのロック証拠、利用可能な最大限の読み取りが追加されます。

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

レスポンス：標準のエンベロープです。data にはトークンの識別情報、マーケットのスナップショット、ロックやバーンの文脈を伴う LP のカストディが入ります。

制限事項：過去に遡った深いバーンの来歴は v1 では公開されていません。ロックの文脈は既知のロッカーのパターンを対象とするため、変わったカスタムロッカーはロックではなく単なるカストディとして読まれることがあります。それは「ロックされていない」ではなく「未検証」と読んでください。

POST /v1/api/intel/risk、権限は Intelligence（intel:read）

トークンコントラクトに対する Cognivo のリスクシグナルを、チェーンを踏まえて返します。フォールバックとしてレッドフラグの読み取りも行います。

表示価格：成功 1 回あたり 2 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

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

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

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

POST /v1/api/contract/analysis、権限は Contract（contract:read）

コントラクトアドレスについての、コントラクトと支配権の証拠：存在するか、誰が所有しているか、所有権は放棄されたか、プロキシかつ誰が管理しているか、誰がデプロイしたか、どのウォレットをコントローラーやチームとして帰属できるか、ソースは検証済みかを返します。

コスト：0 クレジット。このエンドポイントは方針としてすべてのプランで無料です。何も差し引かれません。

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

レスポンス：標準のエンベロープです。data には contract、ownership、proxy、deployer、controllers、source_verification、limitations、unavailable が入ります。

すべてのフィールドは、それがどこから来たのかを示します。meta.provenance は各フィールドを、次のいずれか 1 つに正確に対応づけます：

ラベル	意味
verified_onchain	リクエスト時点で、そのネットワークのノードから読み取った値。事実です。
augmented	Cognivo Augmented Intelligence：外部のソースから提供され、クロスチェックはされているが Cognivo が証明したものではありません。
interpretation	事実に対する Cognivo の読み解き。判断であって、事実ではありません。
unavailable	Cognivo はこれを取得できませんでした。理由は data.unavailable にあります。

穴を埋めるために推測したり、既定値を入れたり、ゼロを返したりすることはありません。

meta.chain_data_source.cognivo_grounded は、その読み取り元のインフラを Cognivo 自身が運用しているかどうかを示します。Cognivo は自前の Ethereum ノードを運用しているため、Ethereum の読み取りは true です。Base と BNB Chain の読み取りは外部の RPC インフラから得られるため false です。それらの読み取りは正確ですが、Cognivo が管理するハードウェアから提供されているわけではありません。Cognivo は、あなたに誤解させたままにするのではなく、そのことを明示します。

Base における制限事項。これらは data.limitations にも返されます：

• 深いコントローラーのグラフは Ethereum 限定です。Base では、コントローラーとチームの帰属は、より狭いウォレットの役割の読み取りから得られます。
• Base のデプロイヤーの証拠は、Cognivo のアーカイブ読み取りではなく外部のソースから得られます。有力な手がかりとして扱い、証明された事実として扱わないでください。
• Base では流動性のロックスケジュールはデコードされません。LP のカストディとバーンの証拠には POST /v1/api/intel/liquidity を使い、ロックがないことをロックが存在しない証拠と読まないでください。

このエンドポイントが報告するのは、コントラクトの支配権に関する証拠だけです。流動性については何も語りませんし、クリーンな結果がコントラクトの安全性を意味することは決してありません。

読み取り専用です：署名も、トランザクションの組み立ても、ブロードキャストも行わず、ウォレットの権限委譲もありません。

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

POST /v1/api/wallet/pnl、権限は Intelligence（intel:read）

1 つのウォレットの 1 つのトークンについての損益を、根拠のあるオンチェーンのスワップから算出します。wallet と token の両方が必須です。

表示価格：成功 1 回あたり 10 クレジット。失敗した呼び出しと、データなしの 422 結果には決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

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

レスポンス：標準のエンベロープです。data には実現損益の数値と、擁護できる取得原価が存在する場合には保有中ポジションの含み損益が入ります。

制限事項：擁護できる取得原価を確立できない場合、含み損益はでっち上げの数字ではなく null で返ります。そのトークンで価格付けされた取引がウォレットにまったくない場合、この呼び出しは 422（例えば insufficient_data）を返します。これは Cognivo が公正な数字を算出できなかったという意味であり、利益がゼロだったという意味ではありません。422 には決して課金されません。Cognivo が価格を付けられなかったスワップは、削除されるのではなく価格未付与として表示されます。

POST /v1/api/wallet/approvals、権限は Security（security:read）

ウォレットが与えたトークンの支出承認を一覧表示し、無制限の承認にフラグを立てます。

表示価格：成功 1 回あたり 2 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

任意の limit と offset で、大量の承認をページ送りできます。

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

レスポンス：標準のエンベロープです。data には、スペンダー、トークン、承認額の文脈を伴う承認の一覧が入ります。

制限事項：これは読み取り専用です。Cognivo が資金を動かすことは決してなく、あなたに代わって承認を取り消すこともできません。取り消しは常にあなた自身のウォレットから行います。空のリストは有効な成功の答えであり、課金されません。

POST /v1/api/wallet/exact-movements、権限は Intelligence（intel:read）

ウォレットの正確なトークンの動きを一覧表示します：購入、売却、送金です。token は任意で、読み取りを 1 つのトークンに絞り込みます。

表示価格：成功 1 回あたり 5 クレジット。失敗した呼び出しには決して課金されません。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

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

レスポンス：標準のエンベロープです。data には件数を伴う動きの一覧が入ります。

制限事項：この呼び出しが返すのは直近の動きで、1 回あたり最大 25 件です。該当する動きがないウォレットには、作り話の履歴ではなく 422 が返ります。

Discover

GET /v1/api/discover

公開の Discover フィードです：最近の匿名化されたオンチェーンインテリジェンスカードが並び、それぞれにトークンの識別情報、フック、箇条書きが付きます。有効なキーであれば動作します。無料ですが、厳しい 1 日あたりの上限があります。

クエリパラメーター：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'

{
  "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 とアプリ限定です。
• ID によるレポート取得（reports/:id）。
• Webhook。
• Solana のエンドポイント。

次のステップ

クイックスタート で最初の呼び出しを行い、認証と API キー でキーを作成して権限を絞り込み、何かをスケジュール実行に乗せる前に レート制限とエラー を読んでください。