予測市場は、APIを構築する上で技術的に最も要求の厳しい領域の一つです。有効期限のある金融商品、リアルタイムで価格が変動する確率、複雑な資本関係を持つ複数の結果を伴うイベント、そしてUIをクリックする人間とアービトラージ戦略を実行する自動取引ボットの両方を含むユーザーベースを扱います。あらゆる設計上の決定が即座にストレステストされます。
現在、取引量で世界最大の予測市場プラットフォームであるPolymarketは、まさにこの理由から研究に値するAPIエコシステムを構築しています。それは単なるデータベース上のCRUD APIではありません。それは、オープン性とセキュリティ、リアルタイムデータと履歴データ、伝統的な金融パターンと暗号通貨ネイティブのプリミティブという根本的な緊張関係を処理する、注意深く層化されたアーキテクチャです。
彼らがどのように行ったかから抽出する価値のある8つの設計パターンを以下に示します。
パターン1：ドメイン分離型APIレイヤー
Polymarketは、それぞれ明確なドメインを持つ3つの異なるAPIを公開しています。
- Gamma API (
gamma-api.polymarket.com) — 市場発見、イベント、タグ、検索 - CLOB API (
clob.polymarket.com) — オーダーブックデータ、価格設定、注文発注 - Data API (
data-api.polymarket.com) — ユーザーポジション、取引、分析、リーダーボード
これは単なる命名規則ではありません。各APIには異なる認証要件、異なる更新頻度、異なる利用者プロファイルがあります。Gamma APIは完全に公開されており、ブラウジングと発見に最適化されています。CLOB APIには公開エンドポイント（誰でもオーダーブックを読み取れる）と認証済みエンドポイント（取引には資格情報が必要）の両方があります。Data APIは公開されていますが、ウォレットアドレス指定されており、ユーザーアドレスでポジションを照会します。
ここでの設計上の教訓は、エンティティではなくドメインによって分離することで、より一貫性のあるAPIが生まれるということです。素朴なアプローチでは、/markets、/orders、/usersがすべて一つの屋根の下に置かれるでしょう。Polymarketは代わりに、「このAPIは何のためのものか？」と問い、その質問を中心に構築しています。発見には取引とは異なるアクセスパターンがあります。取引には分析とは異なるレイテンシー要件があります。それぞれに独自のベースURLを与えることで、それぞれが独立して進化し、スケーリングし、認証を行うことができます。
パターン2：パブリックファーストのデータアクセス
市場データ（価格、オーダーブック、イベントメタデータ、履歴取引）に関するすべては完全に公開されています。
curl "https://gamma-api.polymarket.com/events?limit=5"
APIキーもOAuthも不要です。読み取りエンドポイントにレート制限もありません。データが得られます。
これは、ほとんどの金融プラットフォームが採用しない意図的な選択です。伝統的な取引所は市場データを収益源として保護します。Polymarketはそれをインフラと見なしています。より多くの人々がデータを読み取り、その上に構築できるようになればなるほど、市場はより流動的で有用になります。これは、APIに適用された公共財の論理です。
API設計者にとっての実用的な結果は注目に値します。認証を一律に適用するのではなく、読み取りアクセスと書き込みアクセスを第一級の懸念事項として分離することは、データの消費がデータの生成をはるかに上回るプラットフォームでは、ほとんど常に正しい判断です。ユーザーが資格情報なしで市場価格を読み取れるようにすれば、潜在的なオーディエンスの95%から摩擦が取り除かれます。摩擦は、実際に重要になる時点、つまり実際の注文を出したいときにのみ追加されます。
パターン3：真の信頼を反映する2段階認証
取引エンドポイントには認証が必要ですが、Polymarketの認証モデルは、ほとんどのAPI設計者がこれまで見たことのない構造を持っています。それは、明確な目的を持つ2つのレベルです。
L1認証は、ユーザーの秘密鍵からのEIP-712署名を使用します。これはウォレットの所有権を証明します。API資格情報を導出するために、これを1回（またはまれに）使用します。
// L1: 秘密鍵を使用してAPI資格情報を導出する
const credentials = await client.createOrDeriveApiKey();
// → { key: "...", secret: "...", passphrase: "..." }
L2認証は、導出された資格情報とともにHMAC-SHA256を使用します。これは、すべての取引リクエストに添付するものです。
// すべての取引リクエストのL2ヘッダー
{
"POLY_ADDRESS": "0x...",
"POLY_SIGNATURE": "<hmac-sha256>",
"POLY_TIMESTAMP": "1716000000",
"POLY_API_KEY": "550e8400-...",
"POLY_PASSPHRASE": "..."
}
ここでの洞察は、異なる操作には異なるセキュリティ手順がふさわしいということです。APIキーの作成にはウォレットの制御を証明する必要があります。これは高リスクな行動であり、秘密鍵からの暗号署名を要求すべきです。しかし、一度その信頼が確立されれば、日常的な取引リクエストは、すべての呼び出しで秘密鍵による再署名を必要とすべきではありません。L2資格情報は、L1アイデンティティに紐付けられつつ、高頻度利用に十分なほど軽量です。
このパターンは暗号通貨以外の分野にもよく当てはまります。これを「あなたはその人物であることを証明する」（L1、利用可能な最強の資格情報でまれに行われる）と「このリクエストがあなたから来たことを証明する」（L2、セッション資格情報で常に行われる）の違いと考えてください。ほとんどのWebアプリはこれらを一つの認証フローにまとめ、セキュリティのニュアンスを失っています。
パターン4：API呼び出しではなく、署名付きメッセージとしての注文
予測市場が従来のAPI設計と最も大きく異なるのはここです。Polymarketで注文を出すとき、単にサーバーにデータを送信しているわけではありません。あなたは、強制力のある金融コミットメントである暗号署名付きメッセージを作成しているのです。
const response = await client.createAndPostOrder(
{
tokenID: "71321045679...",
price: 0.65,
size: 100,
side: Side.BUY,
},
{
tickSize: "0.01",
negRisk: false,
},
OrderType.GTC
);
内部では、SDKがEIP-712型データ構造を構築し、秘密鍵で署名し、その署名を注文とともに提出します。マッチングエンジンはオフチェーンで動作しますが、取引がマッチングされると、それらの署名を使用してPolygonを介してオンチェーンで決済されます。オペレーターは取引を捏造したり、資金を移動させたりすることはできません。署名付きメッセージが承認となります。
これにより、「API呼び出し」が意味するものが変わります。通常、エンドポイントに提出することは「私の代わりにこれを実行してください」を意味します。ここでは、注文を提出することは「この取引を承認する署名付き証書です」を意味します。APIは意思決定を行う仲介者ではなく、暗号的に自己承認されたメッセージの中継役です。
暗号通貨分野以外のAPI設計者にとっての教訓は次のとおりです。ペイロード自体が、トランスポート層の資格情報に完全に依存するのではなく、承認を運ぶことができる場合、否認防止と検証可能性が無料で得られます。金融システム、法的文書、および高リスクな操作はすべて、このパターンの候補となります。
パターン5：データモデルにおける明示的なオントロジー
Polymarketは、イベントとマーケットという2つのオブジェクトを中心にデータを構築しています。この区別は重要です。
イベントは質問です。「2026年のペンシルベニア州上院選で誰が勝つか？」。これにはタイトル、カテゴリ、解決日があります。マーケットは、そのイベント内の特定の取引可能なバイナリ結果です。「ボブ・ケーシーは勝つか？」。1つのイベントには複数のマーケットが含まれることがあります。
{
"id": "501",
"title": "2026 Pennsylvania Senate Race",
"negRisk": true,
"markets": [
{ "id": "2301", "question": "Will Bob Casey win?", "outcomePrices": "[\"0.42\", \"0.58\"]" },
{ "id": "2302", "question": "Will Dave McCormick win?", "outcomePrices": "[\"0.35\", \"0.65\"]" },
{ "id": "2303", "question": "Will a third candidate win?", "outcomePrices": "[\"0.23\", \"0.77\"]" }
]
}
これは明示的なオントロジーです。APIはデータを保存するだけでなく、エンティティ間の概念的な関係性をエンコードします。価格は、インデックス位置が結合規則となる並列配列として表現されます。outcomes[0]はoutcomePrices[0]に対応します。イベントレベルのnegRiskフラグは、その中のマーケットが独立したマーケットには存在しない資本関係を持つことを示します。
ほとんどのAPIはこれらの関係を平坦化します。Polymarketは、それらがシステムが機能するために不可欠であるため、それらを表面化します。もし自動トレーダーを構築していてnegRisk: trueを見落とすと、誤ったポジションモデルを構築し、損失を出す可能性があります。API設計は概念的な構造を可視化することで、それを見落とすことが意識的な選択であり、暗黙のデフォルトではないようにしています。
パターン6：NegRisk — 資本関係を第一級の懸念事項として扱う
イベントのnegRiskフラグは、Polymarketの最も興味深いAPI設計パターンの一つ、つまり金融上の等価性をプログラマブルにすることを示しています。
標準的な複数結果イベントでは、各マーケットは独立しています。しかし、NegRiskイベント（正確に1つの結果のみが勝ち得る）では、ポジション間に数学的な関係が存在します。
結果AのNoトークン1つ ≡ 他のすべての結果のYesトークン1つ
これは単なる数学ではありません。スマートコントラクトで実装され、APIを通じて表面化されています。ペンシルベニア州上院選で「その他」のNoポジションを保有している場合、それを変換できます。
| 変更前 | 変更後 |
|---|---|
| 1× No (その他) | 1× Yes (ケーシー) + 1× Yes (マコーミック) |
APIはこれを明示的に示しています。マーケットオブジェクトのnegRisk: trueと、これらのマーケットを取引する際の注文オプションで必要なnegRisk: trueです。これを間違えると、注文は拒否されるか、誤って決済されます。
ここでの設計パターンは、ドメイン不変条件をドキュメントの脚注として残すのではなく、型付きAPIフィールドとしてエンコードすることです。NegRiskフラグは、それが便利だから存在するわけではありません。それを省略すると誤った動作を引き起こすため存在します。ドメインに厳密な制約（1つの結果しか勝てない、ポジションには変換等価性があるなど）がある場合、それらの制約はドキュメントだけでなく、APIサーフェスに表示されるべきです。
パターン7：市場の状態としての動的なティックサイズ
ほとんどの金融APIは、ティックサイズを静的な設定として扱います。PolymarketのAPIはもっと興味深いことをします。ティックサイズは市場価格に基づいて動的に変化し、APIはこれをリアルタイムのイベントストリームとして公開します。
市場価格が極端な値（0.96以上または0.04以下）に近づくと、最小ティックサイズは0.01から0.001に狭まります。
{
"event_type": "tick_size_change",
"asset_id": "65818619657...",
"old_tick_size": "0.01",
"new_tick_size": "0.001",
"timestamp": "100000000"
}
その理由は直感的です。極端な確率では、1セントのティックは25%の変動（0.04から0.03への変化）を表します。これは、意味のある価格発見には粗すぎます。極端な値の近くでより細かいティックは、市場が97%に丸めるのではなく、97.3%のような確率を表現することを可能にします。
API設計の選択としてこれが注目に値するのは、ティックサイズが一度取得すればよいパラメータではなく、変化し追跡されなければならない状態であるということです。WebSocketはtick_size_changeイベントを公開することで、クライアントが注文構築ロジックを現在の市場状態と一貫させられるようにしています。ティックサイズをハードコードし、このイベントを見逃すと、注文は拒否されます。
これは、より広範な原則を反映しています。金融システム向けAPI設計では、状態を第一級の概念として受け入れる必要があります。市場パラメータは静的ではありません。解決ルールは変更されます。結果は明確化されます。APIはこれらの状態遷移を明示的に伝える必要があり、クライアントが拒否されたリクエストを通じてそれらを発見するように任せるべきではありません。
パターン8：異なる利用者プロファイルのための2つのWebSocketレイヤー
Polymarketは2つの別々のWebSocketシステムを運用しており、その理由を理解することで、オーディエンスのセグメンテーションに関するパターンが見えてきます。
マーケットチャンネル（wss://ws-subscriptions-clob.polymarket.com/ws/market）は、取引利用者向けに構築されています。トークンIDでサブスクライブし、オーダーブックのスナップショット、価格変動、取引約定、ティックサイズ変更を受信します。すべてはアセットIDに紐付けられ、低レイテンシーの注文構築に最適化されています。
{
"assets_ids": ["65818619657568813474341868652308942079804919287380422192892211131408793125422"],
"type": "market"
}
リアルタイムデータソケット（wss://ws-live-data.polymarket.com）は、まったく異なるプロファイル向けに構築されています。コメント、BinanceおよびChainlinkからの暗号通貨価格、株式価格、ソーシャルインタラクションイベントをストリーム配信します。トピックでサブスクライブします。
{
"action": "subscribe",
"subscriptions": [
{ "topic": "crypto_prices", "type": "update", "filters": "btcusdt,ethusd" }
]
}
これら2つのシステムは、根本的に異なるニーズを持つオーディエンスにサービスを提供します。マーケットメーカーはマイクロ秒単位で関連するオーダーブックの差分を必要とします。「Polymarketで今何が起きているか」を示すUIは、コメントフィードやソーシャルアクティビティを必要とします。これらを組み合わせると、ソーシャルフィードを取引グレードのレイテンシー要件で過剰に設計するか、オーダーブックフィードをソーシャルグレードの信頼性仮定で設計不足にするかのいずれかになります。
教訓は単純ですが、しばしば無視されます。リアルタイムの利用者が、レイテンシー許容度、データ量、および障害モードにおいて意味のある違いがある場合、彼らに別々のインフラを提供してください。複数の目的を果たそうとする共有のWebSocketエンドポイントは、複雑さにおいては最大公約数に、パフォーマンスにおいては最小公約数に収束する傾向があります。
これらのパターンに共通すること
PolymarketのAPI設計は、特定の哲学を反映しています。それは、APIがドメインの実際の構造を抽象化するのではなく、可視化すべきであるというものです。
3層アーキテクチャは、実際のドメイン境界に対応しています。パブリックファーストのアクセスは、予測市場の価値がどのように機能するかを反映しています。2段階認証は、本人確認と行動の承認という実際の違いを反映しています。署名付きメッセージとしての注文は、非カストディアルな保証をエンコードします。イベント/マーケットの階層とNegRiskフラグは、そうでなければ見えない関係性を明らかにします。動的なティックサイズは、クライアントの状態を市場の状態と一貫させます。別々のWebSocketレイヤーは、異なるオーディエンスにサービスを提供します。
ほとんどのAPI設計のアドバイスは、エルゴノミクスに焦点を当てています。呼び出しやすく、命名が一貫しており、エラー処理が予測可能であることなどです。PolymarketのAPIはこれらすべてを行っていますが、より興味深い選択は、ドメインへの忠実性に関するものです。ドメインに意味のある区別がある場合、APIはそれを表面化します。ドメインに制約がある場合、APIはそれを強制します。ドメインに変化する状態がある場合、APIはそれをブロードキャストします。
その結果、利用者により多くを要求するAPIとなりますが、正しく理解すれば、取引しているシステムを実際に理解できることを意味します。これは偶然ではありません。予測市場では、価格が情報を反映することがすべてであるため、市場の構造を理解することを要求するAPIは、まさにその役割を果たしているのです。