メインコンテンツまでスキップ

認証と API キー

API キーとは​

API キーは、リクエストがあなたのものだと Cognivo が判別できるように、コードが送る秘密の値です。Developer API のすべての呼び出しがこれを伴います。キーはプロジェクトの中に置かれ、プロジェクトはキーとその利用状況をまとめる単位です。

最初の呼び出しの前に、キーに何が許可されているかを知りたいときに、あるいはキーが漏洩した可能性があって無効にする必要があるときに、このページを読んでください。

場所​

Cognivo dApp にサインインし、左サイドバーの アカウント を開いて Developers を選びます。サインアウト状態では、案内画面のみが表示されます。

Developers ページには 4 つのタブがあります：キー、Usage、エンドポイント、クイックスタート。このページの内容はすべてキータブで行います。

ライブアクセスとクレジット残高​

ページ上部のバナーが、アクセスモデルをはっきりと示しています：一部のエンドポイントは有効なキーがあれば無料で、それ以外は成功した呼び出しごとに Cognivo のクレジット残高から課金されます。さらに下の ライブ API アクセス のカードは、ライブキーが作成した瞬間から動くことを確認しています。承認の手順も、順番待ちのリストもありません。

その隣には、現在のクレジット残高、クレジットをチャージ ボタン、エンタープライズアクセス ボタンが表示されます。エンタープライズは、カスタム料金や上限引き上げのために申請を経る唯一のアクセス経路です。それ以外はすべてセルフサービスです。

Developers ページの下の方にあるライブ API アクセスパネル。画像を拡大

すべての Cognivo アカウントは毎日 5 クレジットの無料枠も受け取り、UTC の午前 0 時にリセットされます。残高の仕組みについては 課金とクレジット を、エンドポイントごとの価格については レート制限、エラー、課金 をご覧ください。

キータブ​

プロジェクト のドロップダウンからプロジェクトを選ぶか、新規プロジェクト で作成します。キータブには、そのプロジェクトに属するすべてのキーが一覧表示されます。

Developers ページのキータブ。選択したプロジェクトに属するすべてのキーが一覧表示されます。画像を拡大

各キーの行には、あなたが付けた名前、テストキーかライブキーか、適用される 1 時間あたりの上限、持っている権限、作成日時と最終使用日時が表示されます。最終使用：なし は、そのキーで呼び出しが一度も行われていないことを意味します。

表示されるのはキーのプレフィックスと末尾 4 文字だけです。Cognivo は読み戻せる情報を他に一切保存していません。だからこそ、完全なキーはちょうど一度しか表示されないのです。

キーの作成​

+ 新規キー を選びます。フォームでは 3 つのことを尋ねられます：キーを区別するための任意の名前、テスト か ライブ かのモード、そして少なくとも 1 つの権限です。

Developers ページの新しいキーのフォーム。新しいキー ボタンから開きます。画像を拡大

ライブを選ぶと、モードのドロップダウンの下にクレジット残高が表示されます。ライブの呼び出しは実際の呼び出しであり、その残高から課金されることのリマインダーです。テストを選ぶと、決して課金されず上限の厳しいサンドボックスキーが作成されます。

キーを作成 を選ぶと、完全なキーがダイアログに一度だけ表示されます。

  1. 画面に表示されている間にコピーアイコンで完全なキーをコピーしてください。二度と表示されません。
  2. 後で見つけられる場所にキーを保存したら、完了 を選択します。
キータブのワンタイムキーダイアログ。新しいキーを作成した瞬間に表示されます。画像を拡大

キーを紛失した場合、それを復元することはできません。代わりにキーをローテートしてください。詳しくは後述します。

キーの送り方​

正式なヘッダーは X-API-Key です：

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":"eth","address":"0xTOKEN_CONTRACT"}'

Authorization: Bearer YOUR_API_KEY も、そちらを好むクライアントライブラリのためのエイリアスとして受け付けられます。キーはサーバー側に置いてください。ブラウザのコードには絶対に入れないでください。

現時点で API が対応しているのは Ethereum、Base、BNB Chain です。

権限​

キーはデフォルト拒否です。キーは、作成時に付与したエンドポイントグループしか呼び出せません。権限は 3 種類あり、それぞれが一連のエンドポイントを解放します。

Intelligence（intel:read）は日常的に使う権限です。「このトークンやウォレットに何が起きているのか」に答えます：価格下落の要因、リスクシグナル、チームウォレットの挙動、実現損益、正確な資金の動きなどです。POST /v1/api/intel/why-down、POST /v1/api/intel/team-wallets、POST /v1/api/intel/risk、POST /v1/api/wallet/pnl、POST /v1/api/wallet/exact-movements を解放します。

Security（security:read）は、ウォレットが承認した内容、つまりどのコントラクトがそのトークンを使えるか、どの承認が無制限かをキーが確認できるようにします。読み取り専用です。この権限を持つキーが資金を動かしたり承認を取り消したりすることは決してありません。POST /v1/api/wallet/approvals を解放します。

Liquidity（liquidity:read）は、プールの文脈、LP のカストディ、ロックとバーンの文脈をキーが読めるようにします。POST /v1/api/intel/liquidity を解放します。

GET /v1/api/health はキーが一切不要です。GET /v1/api/me と GET /v1/api/discover は、権限にかかわらず有効なキーがあれば動きます。

権限はキーの作成時に固定されます。変更するには、必要な権限を持つ新しいキーを作成し、古いキーを失効させてください。呼び出しが 403 scope_denied で失敗した場合は、そのエンドポイントが必要とする権限をキーが持っていないという意味です。

テストキーとライブキー​

プレフィックス用途課金レート上限
cogv_test_API を試すため。ポータルでは Test および Sandbox と表示されます。ライブのインテリジェンスは実行できません。決して課金されない1 時間あたり 25 リクエスト、1 日あたり 100、1 秒あたり 1
cogv_live_実トラフィック用。セルフサービスで、すぐに動きます。成功した 呼び出しごとに Cognivo クレジット。失敗した呼び出しには決して課金されません。まず 1 時間あたり 1,000 リクエスト。レート制限 を参照

テストキーは無料の本番用キーではありません。テストキーで行ったライブ呼び出しには 403 sandbox_limited が返ります。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。

ポータルは各キーのアクセスモードも表示します。Paid は通常の従量課金です。Trial は終了日のある一時的な評価枠です。Partner と Enterprise は Cognivo との取り決めによるものです。Suspended はキーが何も実行できない状態で、その理由はポータルに表示されます。ごく一部の古いキーはセルフサービス課金より前のもので、メタデータのエンドポイントしか呼び出せないため、ライブ呼び出しには 403 access_required が返ります。新しいライブキーを作成して、従量課金に移行してください。

GET /v1/api/me は、キーのアクセスモード、権限、credits_balance、チャージの案内を返します。残高が呼び出しをカバーできない場合は 402 payment_required が返り、何も課金されません。チャージしてから再試行してください。

ローテートと失効​

どちらのコントロールも、各キーの行の右側にあります。

  1. 名前の横のテストとサンドボックスのバッジで、このキーがどの種類かを確認します。その横には 1 時間あたりの上限も表示されます。
  2. ローテーション を選択すると、このキーが新しいキーに置き換わります。新しいキーは一度だけ表示され、古いキーはすぐに使えなくなります。
  3. 失効 を選択すると、キーを完全に無効にします。もう使わない場合や、他人に見られた可能性がある場合に使います。
Developers ページのキータブに並ぶキーの行。画像を拡大

ローテートは先に確認を求め、ダイアログには何が起こるかが正確に書かれています。

キータブのローテーション確認。キーの ローテーション を選択すると表示されます。画像を拡大

ローテートされたキーは、名前、権限、ティア、ネットワーク制限、有効期限、残っている利用枠をすべて引き継ぐため、ローテートは安全であり、キーの権限が知らないうちに広がることはありません。差し替え後のキーは、新規キーと同じダイアログで一度だけ表示されます。失効は取り消せず、そのキーはすべてのエンドポイントでただちに使えなくなります。

漏洩が疑われるときは必ずローテートし、加えて定期的にもローテートしてください。

Cognivo がキーに適用できる制限​

これらはポータルのフォームではなくキーのレコード側に設定され、すべてのリクエストで適用されます。自分のキーに何が適用されているかは GET /v1/api/me で確認できます。

  • ネットワーク制限。 キーを特定のネットワークに限定できます。別のネットワークを指定したリクエストは 403 chain_denied で拒否されます。拒否は Cognivo が上流を呼び出す前、かつ利用枠が消費される前に行われるため、キーに許可されていない呼び出しで費用が発生することはありません。allowed_chains として報告され、null は制限なしを意味します。
  • 有効期限。 キーに終了日を設定できます。それを過ぎると、キーは GET /v1/api/me を含むあらゆる場所で動作しなくなり、403 key_expired を返します。expires_at として報告され、null は期限なしを意味します。トライアル枠にも終了日がある場合は、先に来るほうが適用されます。
  • Origin と IP の許可リスト。 キーを特定の Origin（https://*.yourapp.com のようなワイルドカードサブドメインを含む）や、特定の IP アドレスと CIDR レンジに限定できます。それ以外からのリクエストは 403 origin_denied で拒否されます。リストが空の場合は制限なしを意味します。

次のステップ​

キーが手に入ったら、クイックスタート で最初の呼び出しを行い、次に エンドポイントリファレンス で各エンドポイントが返す内容とコストを確認してください。見覚えのないエラーコードが返ってきた場合は、レート制限、エラー、課金 にすべて掲載されています。