Coinbase API の使い方：ステップごとのガイド

デジタル資産取引のグローバルリーダーであるCoinbaseは、堅牢なアプリケーションプログラミングインターフェース（API）スイートを提供しています。これらのAPIは、Coinbaseの取引サービスおよびデータサービスとのプログラムによる統合を求める開発者、アルゴリズムトレーダー、金融機関にとっての基盤となります。本ガイドでは、Coinbase Exchange APIの実践的な実装、コア機能、運用上のベストプラクティスに焦点を当てた詳細な技術解説を行います。

💡

美しいAPIドキュメントを生成する優れたAPIテストツールが必要ですか？

開発チームが最大限の生産性で共同作業できる統合されたオールインワンプラットフォームが必要ですか？

Apidogはこれらの要望すべてに応え、Postmanをはるかに手頃な価格で置き換えます！

ボタン

初期設定と認証

Coinbase Exchange APIとのやり取りを成功させるには、アカウントの準備、安全なAPIキー管理、そして認証プロトコルを正確に理解することから始まります。

アカウントの前提条件とAPIキーの生成

通常、Coinbase Advanced Tradeまたは機関投資家向けアカウントのような、認証済みのCoinbaseアカウントが必要です。APIキーはアカウント設定内で生成されます。このプロセスにより、以下の3つの重要な情報が得られます。

APIキー: アプリケーションを識別する公開の英数字文字列（例: k7b9f2d7e8h1g3j4）です。
APIシークレット: 非公開の英数字文字列（例: S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i）です。このシークレットは生成時に一度だけ表示されるため、安全に保管する必要があります。
パスフレーズ: キー生成時にご自身で作成する追加のセキュリティ認証情報（例: mySecureP@$$phr@se2024!）です。

APIキーの権限は細かく設定可能で、アクション（例: 閲覧のみ、取引実行、出金機能）を制限できます。常に最小権限の原則に従ってください。

APIリクエスト認証

Coinbase Exchange APIは、すべてのプライベート認証エンドポイントに対して、署名ベースの認証メカニズム（HMAC-SHA256）を採用しています。各リクエストには、いくつかのカスタムHTTPヘッダーが必要です。

CB-ACCESS-KEY: あなたのAPIキーです。
CB-ACCESS-SIGN: base64エンコードされたHMAC-SHA256署名です。
CB-ACCESS-TIMESTAMP: 現在のUnixエポックタイムスタンプ（秒単位）です。
CB-ACCESS-PASSPHRASE: あなたのAPIキーのパスフレーズです。

署名（CB-ACCESS-SIGN）は、プリハッシュ文字列のHMAC-SHA256ハッシュを作成することによって生成されます。プリハッシュ文字列は、以下の連結です。

タイムスタンプ（文字列として）。
大文字のHTTPメソッド（例: GET、POST）。
リクエストパス（例: /orders、/products/BTC-USD/book）。
リクエストボディ（POSTリクエストの場合。ボディがない場合は空文字列）。

プリハッシュ文字列構築例（POSTリクエストの場合）:

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // JSON string, not Python dict
prehash_string = timestamp + method + request_path + body_json_string

// The API Secret needs to be base64-decoded before being used as the HMAC key.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

誤って構築されたプリハッシュ文字列やタイムスタンプの不一致（サーバーの時計がNTP経由で同期されていることを確認してください）は、認証エラー（HTTP 401）の一般的な原因です。

クライアントライブラリと開発環境

Python（cbpro）、Node.js（coinbase-pro-node）、Java、Goなどの言語用の公式およびコミュニティ開発のクライアントライブラリは、これらの認証の複雑さを抽象化します。あるいは、curlや標準のHTTPクライアントモジュールなどのツールを使用して直接HTTPリクエストを行うことも可能ですが、その場合は署名プロセスの手動実装が必要です。

テスト用のサンドボックス環境

Coinbaseは、開発およびテスト用のサンドボックス環境を提供しています。これはライブマーケットと連携する前に非常に重要です。

目的と機能

サンドボックスは本番環境のAPI機能をミラーリングしますが、テスト資金とシミュレーションされた市場データを使用します。これにより、以下が可能になります。

リスクなしでの取引アルゴリズムのテスト。
API統合ロジックとエラー処理の検証。
APIリクエスト/レスポンス構造の習熟。

本番環境との主な違い

APIエンドポイント: サンドボックスは異なるベースURLを使用します。
本番環境: https://api.exchange.coinbase.com
サンドボックス: https://api-public.sandbox.exchange.coinbase.com（注: 正確なサンドボックスURLは常に公式ドキュメントで確認してください）。
APIキー: サンドボックス専用のAPIキーを別途生成し、使用する必要があります。
市場データと流動性: 板情報（オーダーブック）の厚み、取引量、価格変動はシミュレーションされます。約定シミュレーションはより単純であり、実際の滑り（スリッページ）や部分約定のシナリオを完全に反映しない場合があります。
実際の資金なし: すべての資産と取引は仮想です。テスト用の残高は通常提供されるか、リセット可能です。

本番環境への移行

堅牢なデプロイ戦略には、主にAPI認証情報とベースURLが異なるサンドボックスと本番環境の個別の構成が含まれます。実際の資金でのエラーを防ぐためには、サンドボックスでの徹底的なテストが不可欠です。

コアAPI機能: エンドポイントとデータ構造

APIは、アカウント管理、市場データ取得、取引操作に大別されます。

アカウント管理

アカウントの状態と履歴を照会するためのエンドポイント。

アカウント残高の取得（GET /accounts）
すべてのユーザーアカウント（法定通貨および仮想通貨）とその残高のリストを取得します。
BTCアカウントのレスポンススニペット例:

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "your-profile-id-string"
}

balanceは合計金額、availableは取引に使用できる金額、holdは未約定注文のために保留されている資金です。

アカウント履歴 / レジャー（GET /accounts/{account_id}/ledger）
特定の口座の取引（トレード、手数料、送金）のページ分割されたリストを提供します。
一般的なクエリパラメータ: before（ページネーション用カーソル）、after（カーソル）、limit（最大100、デフォルト100）、start_date、end_date。
レジャーエントリーのスニペット例:

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

市場データエンドポイント

リアルタイムおよび過去の市場情報へのアクセス。

プロダクト / 取引ペア（GET /products）
利用可能なすべての取引ペアとそのプロパティをリスト表示します。
プロダクトスニペット例（BTC-USD）:

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Minimum order size in base currency
  "base_max_size": "200.0",  // Maximum order size in base currency
  "quote_increment": "0.01", // Smallest price change unit for quote currency
  "base_increment": "0.00000001", // Smallest size change unit for base currency
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Minimum funds for a market order in quote currency
  "max_market_funds": "1000000", // Maximum funds for a market order
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

板情報（オーダーブック）（GET /products/{product_id}/book）
プロダクトの現在の板情報を取得します。
クエリパラメータ: level (1、2、または3)。
* レベル1: ベスト気配値（最良買い・売り価格）のみ。
* レベル2: 各価格レベルでの買い・売り気配値の集約リスト。（片側最大50件）。
* レベル3: 個別、非集約の注文を含む完全な板情報（認証が必要で、より厳しいレート制限がある場合があります）。
レベル2板情報スニペット例（BTC-USD）:

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [price, size, num-orders-at-this-price]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

プロダクトティッカー（GET /products/{product_id}/ticker）
最終取引（ティック）、ベスト気配値（買い・売り）、24時間ボリュームのスナップショット情報。
ティッカースニペット例（BTC-USD）:

{
  "trade_id": 7423739,
  "price": "50001.50", // Last trade price
  "size": "0.005",    // Last trade size
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 24-hour trading volume in base currency
  "time": "2023-10-26T10:06:15.234Z"
}

過去のレート / ローソク足（GET /products/{product_id}/candles）
過去の価格データ（OHLCV）を取得します。
クエリパラメータ: start (ISO 8601 timestamp), end (ISO 8601), granularity (in seconds: 60, 300, 900, 3600, 21600, 86400)。リクエストごとに最大300本のローソク足。
ローソク足データ例（1時間足）:

[
  // [time, low, high, open, close, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // time is Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

取引操作

注文の発注、管理、照会を行うためのエンドポイント。

注文の発注（POST /orders）
新しい注文をマッチングエンジンに送信します。
一般的なリクエストボディパラメータ:

{
  "client_oid": "my-unique-client-order-id-001", // Optional: UUID for idempotency
  "product_id": "BTC-USD",
  "side": "buy", // "buy" or "sell"
  "type": "limit", // "limit", "market", or "stop" (stop orders are more complex)
  "price": "49500.00", // Required for limit orders
  "size": "0.0125", // Amount of base currency to buy/sell
  // "funds": "500.00", // For market buy orders: amount of quote currency to spend
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (used with GTT)
  "post_only": false, // If true, order is rejected if it would immediately match (ensures maker)
  "stp": "dc" // Self-trade prevention: "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

注文の発注が成功すると、サーバーが割り当てたidを含む注文の詳細が返されます。

注文の管理

**注文ステータスの取得（GET /orders/{order_id_or_client_oid}）**: サーバーIDまたはclient_oidで単一の注文を取得します（client_oidの場合はclient:をプレフィックスとして付けます。例: GET /orders/client:my-unique-client-order-id-001）。
**未約定注文のリスト表示（GET /orders）**: アクティブな注文のページ分割されたリストを返します。status（open、pending、active）やproduct_idなどのパラメータでフィルタリングできます。
**注文のキャンセル（DELETE /orders/{order_id_or_client_oid}）**: 特定の未約定注文をキャンセルします。キャンセルリクエストが成功すると注文IDを返します。
**全注文のキャンセル（DELETE /orders）**: すべての未約定注文をキャンセルします。オプションで特定のproduct_idを指定できます。

約定履歴（GET /fills）
実行された取引（約定）のページ分割されたリストを取得します。
クエリパラメータ: order_id、product_id、before、after、limit。
約定履歴スニペット例:

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // "M" for Maker, "T" for Taker
  "fee": "0.00000250", // Fee in quote currency (USD for BTC-USD) or base currency depending on API.
  "settled": true,
  "side": "buy"
}

マッチングエンジン

マッチングエンジンは、価格・時間優先アルゴリズムに基づいて買い注文と売り注文をペアリングします。

**価格優先:** より有利な価格の注文が優先されます（買い注文は高い価格、売り注文は低い価格）。
**時間優先:** 同一価格の注文の中では、最も早く提出された注文が優先されます。

**メイカー注文 vs. テイカー注文:**
**メイカー:** 板情報に流動性を追加する注文（例: 即座に約定しない指値注文）。通常、低い取引手数料（例: 0.00% - 0.40%）の恩恵を受けます。post_onlyフラグは、注文がメイカーとなることを保証するのに役立ちます。
**テイカー:** 流動性を取り除く注文（例: 成行注文、または即座に約定する指値注文）。わずかに高い手数料（例: 0.05% - 0.60%）が発生します。手数料ティアは、多くの場合、過去30日間のボリュームに基づいています。

このロジックを理解することは、注文発注戦略、スリッページの管理、手数料の最適化にとって不可欠です。

レート制限とスロットリング

APIアクセスは、プラットフォームの安定性と公平な利用を確保するためにレート制限の対象となります。

種類と識別

制限は通常、APIキーごと、IPアドレスごとに適用され、エンドポイントごとに異なる場合があります（例: プライベート認証エンドポイント vs. パブリック非認証エンドポイント）。パブリックエンドポイントは、IPあたり秒間3〜10リクエストのような制限がある場合があります。プライベート（認証済み）エンドポイントは、APIキーごとにもより高い制限があることが多いです。

APIレスポンスには、現在のレート制限ステータスを示すヘッダーが含まれています。

CB-RATELIMIT-LIMIT: 現在のウィンドウでの合計リクエスト制限。
CB-RATELIMIT-REMAINING: ウィンドウ内に残っているリクエスト数。
CB-RATELIMIT-RESET: 制限ウィンドウがリセットされるUnixタイムスタンプ。

制限を超過すると、HTTP 429 Too Many Requestsエラーが発生します。

処理戦略

**プロアクティブな監視:** リクエストを行う前にCB-RATELIMIT-REMAININGを確認します。
**効率的なAPIの使用:**

必要なデータのみを取得します。
RESTエンドポイントをポーリングする代わりに、リアルタイムデータにはWebSocketフィードを使用します。
静的またはめったに変更されないデータ（例: /productsからのプロダクト詳細）をキャッシュします。

**指数バックオフ:** 429エラーを受信した場合、再試行する前に待機します。サーバーに過負荷をかけないように、指数バックオフ（例: 1秒待機後、2秒、4秒、8秒など、ジッターを含む）を実装します。
**リアルタイムデータのためのWebSocket:** 板情報更新、ライブトレード、ティッカーには、WebSocket接続はRESTポーリングよりもはるかに効率的です。

運用上の卓越性: ランブック原則

堅牢な運用プラクティスは、あらゆる取引API統合にとって不可欠です。

監視とアラート

**API接続性とレイテンシ:** APIエンドポイントへのping時間と成功率を監視します。
**レート制限消費:** CB-RATELIMIT-REMAININGを追跡し、ゼロに近づいたときにアラートを発します。
**注文実行:** 注文の発注失敗、予期された期間を超えてpendingステータスでスタックした注文、または重大な約定の不一致についてアラートを発します。
**残高の不一致:** 主要なアカウント残高の予期しない偏差を監視します。
**エラー率:** HTTP 4xxおよび5xxエラーの割合を追跡し、急増を調査します。Prometheus/GrafanaやDatadogのようなツールが一般的に使用されます。
**Coinbaseシステムステータス:** プラットフォーム全体の問題やメンテナンスについて、公式のCoinbaseステータスページ（例: status.coinbase.com）を購読または定期的に確認します。

ロギング

デバッグと監査のために不可欠な情報をログに記録します。

タイムスタンプ（UTC）。
リクエスト: メソッド、パス、ヘッダー（APIキーは編集済み）、ボディ（機密データは編集済み）。
レスポンス: ステータスコード、ヘッダー（特にレート制限およびCB-TRACE-IDのようなリクエストID）、ボディ。
相関ID: システムが使用している場合、またはレスポンスヘッダーからのCB-TRACE-IDを使用します。

セキュリティのベストプラクティス

**APIキーのセキュリティ:** キーは安全な保管庫（例: HashiCorp Vault、AWS Secrets Manager）または環境変数に保存します。ハードコードしたり、バージョン管理にコミットしたりしないでください。
**IPホワイトリスト:** 利用可能な場合、APIキーのアクセスを特定のIPアドレスに制限します。
**最小権限の原則:** APIキーには、絶対に必要とされる権限のみを付与します。
**定期的な監査:** APIキーの使用状況と権限を定期的にレビューします。
**APIバージョニング:** APIバージョンの変更（例: /v2/products、/v3/products）に注意してください。非推奨スケジュールと移行パスについて、開発者向けのお知らせを監視します。

高度なトピックとテクニック

リアルタイムデータのためのWebSocketフィード

Coinbase Exchangeは、低レイテンシのリアルタイムデータのためのWebSocketフィードを提供しています。

**エンドポイント:** 通常、単一のWebSocket URLです（例: wss://ws-feed.exchange.coinbase.com）。
**サブスクリプション:** 接続後、チャネルとプロダクトIDを購読するためにJSONメッセージを送信します。
サブスクリプションメッセージ例:

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // For Level 2 order book updates
        "heartbeat", // To keep connection alive and monitor status
        {
            "name": "ticker", // Ticker channel for specific products
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // For updates on product trading statuses
    ],
    // For user-specific updates (orders, balances), authentication is required within the WebSocket handshake or initial messages.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (if auth needed for certain channels)
}

**メッセージタイプ:**

heartbeat: 接続の健全性を確認し、現在のプロダクトステータスを提供する定期的なメッセージ。
snapshot: 購読データの初期状態（例: level2の完全な板情報スナップショット）。
l2update: レベル2板情報の増分変更（買い/売り気配値の追加、変更、削除）。
ticker: リアルタイムの価格、ボリューム、買い/売り気配値の更新。
matches（またはtrade）: 購読プロダクトのリアルタイム約定取引。
error: サブスクリプションまたは接続の問題を示します。
WebSocket接続の管理には、再接続ロジック、メッセージシーケンス処理（該当する場合、メッセージ内のシーケンス番号経由）、ローカル状態の維持（例: snapshotおよびl2updateメッセージからの板情報の再構築）が含まれます。

冪等性と`client_oid`

ネットワークの問題や再試行による重複した注文送信を防ぐために、POST /ordersリクエストにはclient_oidフィールドを含めることができます。これは、クライアントによって生成される一意の識別子（例: UUID v4）である必要があります。

指定されたclient_oidを持つ注文が受信および処理された場合、一定期間内（例: 24時間）に同じclient_oidを含む後続の同一リクエストは新しい注文を作成せず、代わりに元の注文のステータスを返します。
これにより、「注文発注」リクエストの再試行が安全になります。

自己取引防止（STP）

注文発注（POST /orders）におけるstpパラメータは、アカウントの注文同士が約定するのを防ぐのに役立ちます。オプションには通常以下が含まれます。

dc (Decrease and Cancel): アグレッシブな（テイカー）注文はキャンセルされ、残っている（メイカー）注文のサイズはアグレッシブな注文のサイズだけ減少します。
co (Cancel Oldest): 古い方の注文がキャンセルされます。
cn (Cancel Newest): 新しい方（アグレッシブな）注文がキャンセルされます。
cb (Cancel Both): 両方の注文がキャンセルされます。

結論

Coinbase Exchange APIは、開発者が洗練された取引アプリケーションや統合を構築するための包括的なツールキットを提供します。その認証を習得し、データ構造を理解し、レート制限を尊重し、堅牢な運用プラクティスを実装することが、その可能性を最大限に活用するための鍵となります。リアルタイムデータのためのWebSocketフィードへの移行や、冪等性のためのclient_oidのような機能は、開発者がペースの速い仮想通貨取引の世界で回復力があり効率的なシステムを作成することをさらに可能にします。Coinbaseの公式開発者ドキュメントに継続的に注意を払うことは、新機能、エンドポイントの変更、ベストプラクティスに関する最新情報を得るために不可欠です。