coinank-openapi

概要

CoinAnk OpenAPI は、K 線、ETF、未決済建玉、ロング／ショート比率、資金調達率、清算、注文フロー、クジラの動向、および関連する分析情報など、暗号資産デリバティブ市場データへのアクセスを提供します。利用可能な場合は API キーによる直接認証を使用してください。CoinAnk が支払いチャレンジを返した場合は、最新の OKX 支払いスキルを通じて Agent Payments Protocol／x402 の従量課金アクセスを使用してください。

事前確認

このスキルを使用する前に、次の点を確認してください。

1. ユーザーが求めている市場データのタスクを確認し、エンドポイントの詳細が必要な場合は、references/ にある該当する OpenAPI 参照ファイルを選択します。
2. COINANK_API_KEY が利用可能な場合は、API キーモードを使用し、apikey リクエストヘッダーにのみ送信します。
3. API キーが利用できない場合は、まず元のリクエストを送信し、実際の HTTP 402 Payment Required チャレンジ、または OKX 支払いスキルの charge 要件が発生した場合にのみ、Agent Payments Protocol／x402 の支払い処理を開始します。
4. 有料チャレンジでは、okx-agent-payments-protocol を使用してください。このスキル内でウォレット署名を手動で実装しないでください。
5. 金額が 0 より大きい支払いは、実行前にユーザーの確認を得てください。金額 0 のチャレンジも有効であり、正確に 0 のままにする必要があります。

コマンド

これはスキルのみのプラグインです。以下のコマンド名はエージェントのワークフローを示すものであり、提供されるローカルバイナリではありません。

coinank-openapi quickstart

ユーザーがこのプラグインを初めて使う場合、またはアクセス方法を選択していない場合に使用します。API キーによるアクセス、Agent Payments Protocol／x402 の従量課金アクセス、および OKX 支払いスキルで必要な場合の OKX charge 支払い方法を説明します。

出力：推奨するアクセス方法、必要な前提条件、および最も安全な次のリクエスト。

例：最初の CoinAnk データリクエストの前に、エージェントに coinank-openapi quickstart のフローを実行するよう依頼します。

coinank-openapi query-market-data

K 線、資金調達率、清算、未決済建玉、ロング／ショート比率、注文フロー、ETF データ、クジラの動向、またはトレンドのシンボルなど、CoinAnk の市場データをユーザーが求めている場合に使用します。

出力：選択した CoinAnk エンドポイントに基づく簡潔な回答。使用した主なパラメーターと、発生したアクセス要件または支払い要件も含めます。

例：BTC の資金調達率、ETH の清算ヒートマップデータ、または Binance BTCUSDT の未決済建玉を依頼します。

coinank-openapi use-api-key

COINANK_API_KEY が利用可能な場合、またはユーザーが直接の会員アクセスを希望する場合に使用します。apikey ヘッダーを付けてリクエストを送信し、ユーザーが明示的に希望しない限り、従量課金フローを開始しないでください。

出力：API レスポンスの最終的な要約、または認証／API レベルの明確なエラー。

例：ユーザーの CoinAnk API キーを使用して /api/fundingRate/current を照会します。

coinank-openapi pay-per-call

CoinAnk が実際の HTTP 402 Payment Required チャレンジを返した場合、または OKX 支払いスキルが必要な支払いフローを示した場合にのみ使用します。x402 プルーフの生成や、必要に応じて新しい charge メソッドを含む支払いの実行は、okx-agent-payments-protocol に委任します。

出力：ユーザー向けの支払い概要、金額が 0 より大きい場合の確認依頼、および支払い成功後に再送した API レスポンス。

例：0 を 0.000001 に置き換えずに金額 0 の支払いチャレンジを完了し、生成した支払いデータを使って同じリクエストを再送します。

アクセス方法

このスキルは、次の 2 つのアクセス方法に対応しています。

1. 直接モード -- apikey リクエストヘッダーで COINANK_API_KEY を使用します。
2. 従量課金モード -- CoinAnk が HTTP 402 Payment Required チャレンジを返した場合、Agent Payments Protocol または x402 で支払い、その後同じリクエストを再送します。

COINANK_API_KEY は任意です。存在しない場合でも、このスキルは引き続きアクセス方法の確認を試み、利用可能であれば Agent Payments Protocol または x402 を使用する必要があります。

初回ユーザーへの案内

新しいユーザーがこのスキルを使い始めるときは、利用できるアクセス方法を明確に伝えてください。

• すでに CoinAnk API のメンバーシップを持っている場合は、COINANK_API_KEY を提供するよう伝えてください。
• CoinAnk API のメンバーシップを持っていない場合でも、CoinAnk が支払いチャレンジを返したときに、Agent Payments Protocol または x402 の従量課金アクセスを試せることを伝えてください。
• API のメンバーシップだけがこのスキルの利用方法であるかのように案内しないでください。

Agent Payments Protocol / x402 の依存関係

Agent Payments Protocol / x402 の従量課金モードは、OKX Onchain OS の決済スタックに依存します。

• okx-agent-payments-protocol
• okx-agentic-wallet

最新の okx-agent-payments-protocol スキルを使用してください。このスキルは、Agent Payments Protocol / x402 のチャレンジに対する支払い証明の生成と、新しい charge 支払い方式の両方に対応しています。古い x402 専用のフローをハードコードしないでください。支払いの実行は okx-agent-payments-protocol に委任し、このスキルが返す、または必要とする支払い方式に従ってください。

Agent Payments Protocol、x402、または charge の支払いフローが必要で、それらのスキルを利用できない場合は、まず okx/onchainos-skills をインストールまたは更新するようユーザーに案内してください。

金額ゼロの支払いチャレンジ

金額が 0 の Agent Payments Protocol / x402 チャレンジは有効であり、対応する必要があります。金額ゼロのチャレンジを、不正、未払い、または未対応として扱わないでください。

チャレンジの金額が 0 の場合：

• リクエストには支払い証明が必要ですが、請求額はゼロであることをユーザーにはっきり伝えてください。
• okx-agent-payments-protocol を通じて、元のゼロ金額を使った必要な証明または認証を生成してください。
• 生成した支払いヘッダーを付けて、まったく同じリクエストを再送してください。
• 0 を、0.000001 USDC/USDT のような代替額、最低額、ダスト額、または微小額に置き換えないでください。
• 金額がゼロであることだけを理由に、有料呼び出しの確認を求めないでください。ただし、証明への署名や認証に必要なウォレットまたはプロトコルの確認には従ってください。

Agent Payments Protocol / x402 の署名方式に関する制約

支払いチャレンジに署名する場合、署名方式は署名者の種類と一致させる必要があります。

• EOA の秘密鍵 → exact 方式を使用します。
• OKX コントラクトウォレット / OKX ウォレットセッションの署名 → aggr_deferred 方式を使用します。

次の経路を混在させないでください。

• EOA の秘密鍵による署名に aggr_deferred を使用しないでください。
• OKX コントラクトウォレットによる署名に exact を使用しないでください。

動作モード

このスキルはオンデマンド読み込みモードで動作する必要があります。デフォルトですべての OpenAPI ファイルを読み込まないでください。ユーザーのリクエストに必要なスキーマだけを読み込んでください。

必須のワークフロー

ユーザーのリクエストを処理する際は、必ず次の手順に従ってください。

1. プロジェクトの README を読む
   リクエストを行う前に README.md を読み、文書化されている規約、アクセスモード、エッジケースに従ってください。

2. 該当する API カテゴリを特定する
   {baseDir}/references/ 内のファイル名を確認し、ユーザーのリクエストに一致する OpenAPI ファイルを特定してください。

3. 必要なスキーマだけを読む
   選択した .json ファイルだけを開き、その paths、パラメーター、レスポンスの形式、エンドポイント固有の制約を確認してください。paths オブジェクトでは、各キーが API パスです。

4. リクエストのパラメーターを検証する
   必須パラメーター、サポートされる列挙値、エンドポイントが endTime、size、interval、exchanges などの任意フィールドを受け付けるかどうかを確認してください。

5. アクセス方法を選択する

   • COINANK_API_KEY がある場合は、まず直接モードを優先してください。
   • COINANK_API_KEY がない場合は、探索モードを使用してください。API キーを付けずに元のリクエストを送信し、ルートが公開されているか、Agent Payments Protocol または x402 で支払い可能か、あるいはメンバーシップなしでは引き続き利用できないかをサーバーに判断させてください。

6. 元のリクエストを構築する ユーザーが依頼した内容を正確に反映したリクエストを構築します。

   • ベース URL：スキーマで別のサーバーが指定されていない限り、https://open-api.coinank.com を使用します。
   • 認証：
     • 直接モード：apikey: $COINANK_API_KEY を送信します。
     • ディスカバリーモード：apikey を送信せず、実際に 402 を受け取る前に支払いヘッダーを捏造しません。
   • タイムスタンプ：エンドポイントが endTime を受け付ける場合、ユーザーが別の時刻を明示的に指定していない限り、現在のミリ秒単位のタイムスタンプを優先します。
   • 例：OpenAPI の例フィールドに示されたタイムスタンプは過去の例にすぎず、そのまま再利用してはいけません。

7. 最初に元のリクエストを送信する ウォレットへのログイン、支払い署名、支払いヘッダーの構築を試みる前に、必ず元のリクエストを送信します。

8. レスポンスを解釈する

   • HTTP 2xx ＋業務コード "1"：結果を返します。
   • HTTP 402：このルートは支払いが必要です。Agent Payments Protocol / x402 の支払いフローに切り替えます。
   • HTTP 2xx ＋業務コード "-3"：
     • API キーが指定されている場合、無効または権限が不十分なものとして扱い、CoinAnk へのアクセスを修正するようユーザーに伝えます。
     • API キーが指定されておらず、HTTP 402 チャレンジも返されていない場合、リクエストが Agent Payments Protocol / x402 の支払いフローに入っておらず、有効なアクセス権がないため完了できないことを説明します。
   • その他の失敗：失敗の内容を明確に説明し、主な技術的な原因を含めます。

9. 実際に支払いが必要な場合に限り、Agent Payments Protocol / x402 の支払いフローを実行する okx-agent-payments-protocol を使用し、確認、ログイン、署名、チャージ、再送のフローに従います。

   • HTTP 402 Payment Required チャレンジに対して、必要な Agent Payments Protocol / x402 の支払い証明を生成し、同じリクエストを再送します。
   • 最新の OKX 支払いスキルで、新しい charge 支払い方式が示されている、または必須とされている場合は、従来の x402 専用の証明フローを強制せず、その charge フローを使用します。
   • 実際に支払いが必要だと判明する前に、ウォレットの状態を確認しないでください。
   • 先回りしてログインしないでください。
   • 憶測でチャージしないでください。
   • チャレンジの金額が 0 の場合、有効なゼロ金額の支払いチャレンジとして扱い、正確に 0 を使って必要な証明または認証を生成します。0.000001 やその他の最小非ゼロ金額に置き換えてはいけません。
   • EOA の秘密鍵で署名する場合、OKX の支払いフローで x402 の証明に署名する際は、exact スキームを使用します。
   • OKX コントラクトウォレット／ウォレットセッションで署名する場合、OKX の支払いフローで x402 の証明に署名する際は、aggr_deferred スキームを使用します。

10. まったく同じリクエストを再送する OKX の支払いフローが完了したら、同じメソッド、URL、クエリパラメーター、リクエスト本文で再送します。選択した Agent Payments Protocol / x402 または charge フローで必要な支払いヘッダーまたは認証データのみを追加します。

11. 支払い後の最終レスポンスを返す 中間の 402 ペイロードではなく、再送したリクエストから得られた成功結果を返します。

複数呼び出しのガード

ユーザーが複数回の有料 API 呼び出しを必要とする可能性の高い広範な分析を依頼し、有効な COINANK_API_KEY がない場合は、処理を中断し、複数回の Agent Payments Protocol / x402 の支払いが発生する可能性があることを警告します。複数回の呼び出しを伴う有料ワークフローを開始する前に、確認を求めます。

重要なルール

• スキーマを一括読み込みしないでください ユーザーがカテゴリをまたいだ分析を明示的に依頼しない限り、複数の OpenAPI JSON ファイルを同時に開かないでください。

• パラメーターを勝手に追加しないでください 選択したスキーマで定義されているパラメーターのみを渡してください。余分なパラメーターを追加すると、空の結果を返すエンドポイントもあります。

• 支払い対応を勝手に仮定しないでください CoinAnk が実際に HTTP 402 Payment Required チャレンジを返した場合に限り、リクエストを Agent Payments Protocol／x402 支払い対象として扱ってください。チャレンジの金額が 0 でも有効な支払いチャレンジです。プルーフの生成中も、正確にゼロのまま維持してください。

• 署名方式を混在させないでください EOA 秘密鍵による署名には exact を使用し、OKX のコントラクトウォレットまたは OKX のウォレットセッションによる署名には aggr_deferred を使用してください。

• チャレンジを迂回しないでください 実行するリクエストそのものに対して実際の 402 レスポンスをすでに受け取っていない限り、Agent Payments Protocol／x402 の署名を試みないでください。

• 支払い対象のリクエストを変更しないでください リプレイするリクエストは、支払いヘッダーを除き、元のリクエストと完全に一致させてください。

• 先に必須引数を検証してください リクエストを行う前に、すべての必須パラメーターが存在し、スキーマに準拠していることを確認してください。

• 文書化されたレスポンス形式を守ってください CoinAnk の成功時の "code": "1" は数値ではなく文字列です。

• 失敗を明確に説明してください リクエストまたは支払いフローが失敗した場合は、ユーザーにわかりやすく問題を説明し、トラブルシューティングに必要な技術的な原因も残してください。

API キーモード

CoinAnk の会員は、直接アクセスを設定できます。

export COINANK_API_KEY="your_api_key"

ユーザーが Agent Payments Protocol または x402 による従量課金を明示的に希望しない限り、有効な API キーが利用可能な場合は常に直接モードを使用してください。

タイムスタンプのルール

endTime は現在のミリ秒単位のタイムスタンプである必要があります

# Correct
NOW=$(python3 -c "import time; print(int(time.time()*1000))")

# Wrong on macOS: %3N is not supported
NOW=$(date +%s%3N)

エンドポイントで endTime が必要な場合、ユーザーが別の有効な時間範囲を明示的に指定しない限り、現在のミリ秒単位のタイムスタンプを使用してください。

パラメーターのルール

サポートされていないパラメーターを送信しないでください

一部のエンドポイントは endTime または size を受け付けません。たとえば、getLiqHeatMap などの清算ヒートマップエンドポイントは、サポートされていないパラメーターが含まれていると空のデータを返すことがあります。選択したスキーマに正確に従ってください。

集計エンドポイントでは exchanges が必須です

getAggCvd、getAggBuySellCount、getAggBuySellValue、getAggBuySellVolume などの市場注文集計エンドポイントでは、exchanges パラメーターが必須です。すべての取引所を集計するには、exchanges= を使用してください。

interval の値はエンドポイントによって異なります

サポートされる interval の値は API ファミリーによって異なります。選択したスキーマのパラメーター説明で、許可されている値を必ず確認してください。

エンドポイントの種類	サポートされる interval の値
K 線／市場注文統計／ロング・ショート比率／建玉	1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d
清算ヒートマップ（getLiqHeatMap）	12h, 1d, 3d, 1w, 2w, 1M, 3M, 6M, 1Y
RSI スクリーナー	1H, 4H, 1D
資金調達率ヒートマップ	1D, 1W, 1M, 6M

レスポンスの処理

CoinAnk の成功レスポンスでは "code": "1" が使用されます。一部のエンドポイントは、次の例のように data 内にネストされたペイロードを返します。

{"success": true, "code": "1", "data": {"success": true, "code": "1", "data": [...]}}

実際のレスポンス形式を確認し、必要に応じてネストされた data フィールドを展開してください。

Agent Payments Protocol／x402 の利用可否に関する注意事項

CoinAnk は Agent Payments Protocol または x402 による従量課金アクセスをサポートしています。実際には、スキルは各リクエストに対するサーバーの実際の HTTP 動作に従う必要があります。リクエストが HTTP 402 チャレンジを返さない場合、スキルは支払いフローを捏造してはなりません。

OpenAPI の例に関する注意事項

references/*.json に示されている値、特に example フィールドのタイムスタンプは、過去の例にすぎません。リクエストを作成する際は、最新の値に置き換えてください。

エラー処理

エラー	原因	解決方法
HTTP 401	apikey がない、無効、または拒否された、あるいはゲートウェイ／上流サービスによって支払いデータが拒否された	API キーモードと従量課金モードのどちらを使用するか確認してください。捏造した認証情報で再試行しないでください。従量課金モードを使用する場合は、新しいチャレンジをリクエストし、生成された支払いデータを使って同じリクエストを再送してください。
HTTP 402 Payment Required	CoinAnk がこのリクエストに対して Agent Payments Protocol／x402 による支払いを必要としている	支払い処理を okx-agent-payments-protocol に委任してください。ゼロ以外の金額はユーザーに確認し、ゼロ金額のチャレンジは返されたとおりに処理し、支払い証明または charge の完了後に元のリクエストを再送してください。
エンドポイントパラメーターの不足または非対応	必須のクエリパラメーターがない、古い、または選択した CoinAnk エンドポイントで受け付けられない	該当する OpenAPI リファレンスファイルを読み、不足している値をユーザーに尋ね、タイムスタンプとシンボルの形式に関するルールに従ってください。
支払いスキルを利用できない	必須の OKX 支払いヘルパーがインストールされていない、またはアクセスできない	従量課金モードには okx-agent-payments-protocol が必要であることを説明し、インストールまたは有効化をユーザーに依頼するか、利用可能であれば API キーモードを使用してください。
レート制限、タイムアウト、または上流サービスの利用不可	CoinAnk または CDN／キャッシュ層が一時的にリクエストを拒否した、または処理に失敗した	失敗したことを明確に伝え、ユーザーの確認なしに重複する有料リクエストを再送せず、安全な場合に限り再試行してください。

セキュリティに関する注意事項

• このプラグインは市場データの取得と支払いの調整のみを行い、単独で取引を実行したり資産を移動したりすることはありません。
• 秘密鍵、シードフレーズ、API キー、支払い証明、認証ヘッダー、ウォレットセッションの認証情報を要求、表示、永続化、または公開しないでください。
• COINANK_API_KEY は、ユーザーが設定した環境またはシークレットストアからのみ使用し、CoinAnk の apikey ヘッダーとしてのみ送信してください。
• Agent Payments Protocol／x402 の証明生成、OKX ウォレットの署名、charge の処理は okx-agent-payments-protocol に委任してください。確認フローを回避しないでください。
• ゼロ以外の支払い金額は、実行前に必ずユーザーに確認してください。見込みで請求しないでください。
• ゼロ金額の支払いチャレンジは有効なものとして扱いますが、ゼロをゼロ以外の代替金額に置き換えないでください。