API共通仕様

エンドポイント全体に共通するルールです。URLの構成、レスポンスエンベロープ、シンボル、単位、タイムスタンプ、ページネーション、キャッシュについて説明します。

ベースURLとバージョニング

すべてのエンドポイントは1つのベースURLの配下にあり、HTTPS GETで呼び出します。現在のパスはバージョンv1です。v1内での変更は追加のみです。フィールドやエンドポイントが追加されることはありますが、既存のフィールドの名前、型、意味は変わりません。破壊的変更は新しいパスで提供され、事前に変更履歴で告知されます。

ベースURLhttps://www.coinboss.com/api

レスポンスエンベロープ

すべてのJSONレスポンスには、トップレベルにsuccessフラグがあります。自社収集データ層のエンドポイント（/api/sd配下のパス）は、これに加えて次のブロックを共通で返します。

フィールド	説明
success	呼び出しが成功した場合はtrue。必ず確認してください。
schema	レスポンス構造の識別子とメジャーバージョン。
now	レスポンスを組み立てた時点のサーバー時刻（ミリ秒）。
coverage	集計に含まれる取引所、利用不可の取引所とその理由、鮮度切れのため除外された取引所。
method	レスポンス内の各集計値の計算式またはルール。
meta	ソース、タイムスタンプ、ウィンドウ、品質グレード、鮮度切れフラグ、キャッシュの有効期間、フォールバック時の挙動。

古いエンドポイントはsuccessとdataフィールドを返し、coverage、method、metaを含まない場合があります。正確なフィールドは各リファレンスページに記載しています。

銘柄、契約、取引所

coinパラメータには、BTCやPEPEなど、大文字のベースシンボルを指定します。
1000PEPEやkPEPEなどの乗数付き契約は、数量を換算したうえでベース銘柄に統合されます。
取引所の識別子は小文字です。例：binance、okx、bybit、hyperliquid。
契約シンボルは、取引所での名称のまま返されます。USDT建て、USDC建て、コイン証拠金型の契約および限月先物は、これらが混在するエンドポイントでは契約種別フィールドで区別されます。
暗号資産とティッカーが重複するトークン化株式やコモディティの無期限先物は、暗号資産の集計値から除外されます。

単位

_usdで終わるフィールドは、米ドル建ての想定元本です。
資金調達率はパーセントではなく小数で表します。0.0001は0.01%を意味します。_8hで終わるフィールドは8時間間隔に正規化した値で、元の間隔は生のレートと併せて返されます。
_pctで終わるフィールドはパーセント値です。1.5は1.5%を意味します。
建玉は、フィールドの説明に別途記載がない限り、USD建ての片側想定元本です。両側の数値を公表している取引所は、methodブロックに注記されます。
一部のレガシーエンドポイントは、精度を保つために小数を文字列で返します。フィールド表では型がstring(decimal)と表示されます。

タイムスタンプ

タイムスタンプは、フィールドの説明に別途記載がない限り、UTCのUnixエポックミリ秒です。
observed_atは、集計に含まれる最新レコードの取引所側タイムスタンプです。取引所が提供していない場合はnullになります。
received_atは、CoinBossのコレクターがそのレコードを保存した時刻です。
fetched_atは、レスポンスを組み立てた時刻です。キャッシュされたレスポンスの場合、呼び出し時刻より最大でキャッシュTTLの分だけ古くなります。
日次の系列は、UTCの日付境界で区切られます。

ウィンドウと間隔

ウィンドウパラメータには、1h、4h、12h、24hなどの短いトークンを使用します。一部のエンドポイントでは3d、7d、30d、90dも指定できます。各エンドポイントで指定可能な値はリファレンスページに記載しています。
不明なウィンドウ値は、INVALID_PARAMで拒否されるか、ドキュメント記載のデフォルト値にフォールバックします。どちらになるかはパラメータごとに明記しています。
時系列のバケットサイズはウィンドウによって異なり、リファレンスページに記載しています。

ページネーションとソート

リスト系エンドポイントは、エンドポイントごとの記載に従ってlimitとoffset、またはpageとsizeを使用します。件数には上限があり、それを超える値は上限値に切り詰められます。
レスポンスにtotalが含まれる場合、その値はページネーション適用前の行数です。
エンドポイントがsortパラメータを記載していない限り、ソート順は固定です。

null、0、欠落

nullは値が不明または利用不可であることを意味します。0は実測値としてのゼロを意味します。
チャートでは、nullの箇所を空白として表示する必要があります。補間はしないでください。
フィールド表で「省略される場合あり」と記載されたフィールドは、オブジェクトから完全に欠落することがあります。nullと同様に扱ってください。

キャッシュ

各エンドポイントにはサーバーキャッシュのTTLがあり、リファレンスページとmeta.cache_ttl_sで確認できます。X-CacheヘッダーはHIT、STALE、MISSのいずれかを示します。
ほとんどのGETエンドポイントの前段には、約10秒の短いエッジキャッシュがあります。
TTLより短い間隔でポーリングしても同一のデータが返されるだけで、レート制限を消費します。

WebSocket

WebSocketwss://www.coinboss.com/ws

ストリームはプッシュ専用のJSONです。各メッセージにはtypeフィールドがあります。
切断後は、間隔を空けて再接続し、対応するHTTPエンドポイントからバックフィルしてください。

機械可読なドキュメント

カタログ、各エンドポイントのパラメータとフィールド表、ステータス、品質マトリックスは/api/meta配下でJSONとして取得できます。カタログ全体はOpenAPI 3ドキュメントとしても提供しています。