マーケットカタログAPI

/api/v1/markets/query エンドポイントは、マーケット一覧や検索フローで使う公開マーケットカタログを返します。各項目は MarketCatalogueEntry で、マーケット識別子、アウトカム、ライフサイクル状態、作成者が設定した表示メタデータ、カテゴリタグ、取引サマリ指標を含みます。

カタログは、マーケットカードや発見ページ向けの累計・表示指標として次のフィールドを公開します。

フィールド	型	意味
`ammBotBudgetSubunits`	`int64`	受取手数料を差し引いた、作成後の確定済み資金提供の合計。単位はmsatです。クライアントは資金提供総額として表示します。新しい支払いが確定すると増えます。取引では減りません。現在の注文板流動性、Botの残り在庫、入金者のポジション、引き出し可能な残高ではありません。
`fundingRevision`	`string \| null`	`ammBotBudgetSubunits` を生成した正確なイベント順序です。最初の資金提供が確定する前は null です。
`liquiditySubunits`	`int64`	そのマーケットの注文板に現在残っている注文の額面合計。単位はmsatです。
`traderCount`	`int32`	そのマーケットで約定済み取引を決済した重複なしのトレーダー数。
`volumeLifetimeSubunits`	`int64`	そのマーケットの履歴全体における全約定の決済済み担保額面の累計。単位は担保サブユニット。

レスポンスには、ローリング出来高やソート用の volume24hSubunits と volume30dSubunits も含まれます。Volume、資金提供総額、Traders の表示には、volumeLifetimeSubunits、ammBotBudgetSubunits、traderCount を使ってください。liquiditySubunits は残存注文のサマリです。資金提供総額として表示しないでください。

作成結果を確認する登録情報の読み取り

GET /api/v1/markets/{conditionId}/registration は、コンディション1件の公開登録情報を返します。conditionId、null の場合がある creatorPubkey、登録済み outcomes、baseAsset、divisibility、null の場合がある thumbnailUrl、outcomeDetails を含みます。ウォレットやサインインは不要です。

マーケット作成のレスポンスを受け取れなかった場合、このエンドポイントで登録を確認してください。一致した登録として扱う前に、返されたコンディション、作成者、アウトカム、base asset、divisibility を作成リクエストと照合します。このレスポンスは、現在のマーケット状態、取引サマリ、価格を示しません。現在のカタログ情報には /api/v1/markets/query を使ってください。

コンディションIDが無効な場合は 400、登録がない場合に限り 404 を返します。それ以外のエラーを未登録として扱わないでください。公開マーケットクエリのレート制限も適用されます。

作成者のマーケット

GET /api/v1/creators/{pubkey}/markets は、作成者の登録済みマーケットを返します。各項目には conditionId、createdAt、state、totalVolumeSubunits が含まれます。状態は open または closed です。取引高は、確定済み約定の担保額面の累計です。単位は担保サブユニットで、カタログの累計取引高と一致します。ローカルの発見用の記録だけでは、この状態や取引高は確認できません。読み取りに失敗した場合や項目がない場合は、データを取得できないものとして扱ってください。取引高がゼロの開いたマーケットとして扱わないでください。

アウトカムの表示メタデータ

MarketCatalogueEntry.outcomes はアウトカムのIDリストです。省略可能な outcomeDetails 配列は表示メタデータを追加します。各要素は正確な name を持ち、 color を持つ場合があります。IDリストとの対応には、正確な名前を使ってください。配列の位置に依存しないでください。古いレスポンスでは color が省略されるか、 null の場合があります。色はアウトカムのIDや決済に影響しません。

マーケット作成では、各 CreateMarketOutcome に color を指定できます。先頭に # を付けた6桁の16進数を使ってください。サーバーは英字の大文字と小文字をどちらも受け付け、色がある場合は大文字の #RRGGBB を返します。省略すると、サーバーが色を割り当てます。CreateMarketResponse.outcomeDetails とカタログの outcomeDetails で解決済みの色を確認できます。古い作成レスポンスでは outcomeDetails が省略される場合があります。

サーバーは明示した色を保持します。色がない場合は、正確な結果名で並べ替え、既定のパレットから未使用の色を選びます。パレットは緑、赤、オレンジから始まり、その後に他の異なる色が続きます。

価格と評価額

latestConfirmedTrades 配列が公開マーケット価格の正です。各プリミティブアウトカムの最新の承認済み約定を一定数まで含み、正規のプリミティブアウトカムID順に並びます。取引されていないアウトカムは含まれません。空の配列は承認済み取引がないことを示すため、マーケットに公開価格はありません。クライアントは No trades yet または em dash を表示します。登録値、資金提供額、均一な初期値、Bid/Askのミッドポイントをマーケット価格に使わないでください。ミッドポイントは注文入力の参考値にすぎません。

価格履歴ポイントは volumeSubunits と eventOrder を公開します。 eventOrder は約定の正規の順序を示す不透明な値です。この値を変えずに、上限付きの履歴読み取りの minimumEventOrder に渡してください。取引確定後は、選択中の時間枠のスナップショット全体を置き換えてください。リアルタイムの価格更新を、保持中の系列に統合しないでください。読み取り要求の世代番号で、古いレスポンスを破棄してください。レスポンスの到着順で最新の価格を選ばないでください。

マーケットメタデータスナップショットは totalVolumeSubunits と totalLiquiditySubunits を公開します。メタデータの totalLiquiditySubunits は常にゼロです。Botへの資金提供額、保管資金、約定可能な注文板の厚さを示すものではありません。

マーケット作成リクエストは資金提供額を受け付けません。作成後に、永続的なCashu送信APIでマーケットメイカーに資金を提供してください。各支払いには個別の承認が必要です。同じマーケットに複数回の資金提供ができます。資金提供は公開マーケット価格を作りません。公開価格には latestConfirmedTrades を使ってください。

資金提供のリアルタイム更新

リアルタイムフィードでマーケットに参加したクライアントは、資金提供の受領がコミットされた後に MarketFundingUpdated メッセージを受け取ります。このメッセージは conditionId、ammBotBudgetSubunits、fundingRevision を含みます。アクティブなLMSRパラメータや注文板の厚さは示しません。

このプッシュはベストエフォートです。リプレイでは同じリビジョンが再送される場合があります。クライアントがアウトカムマーケットに参加または再参加したとき、サーバーは現在のコミット済み資金提供も送信します。クライアントは最新のリビジョンを保持してください。古いカタログレスポンスで、新しいライブメッセージから得た合計を減らさないでください。最初の支払い前は、カタログの fundingRevision は null です。

コメントのリアルタイム更新通知

いずれかのアウトカムマーケットグループに参加したクライアントは、コメントのソースイベントがコミットされた後に、ベストエフォートの MarketCommentsChanged { conditionId, eventOrder } 通知を受け取ります。取引確定後に送信したコメントも対象です。この通知は、コメントスナップショットを読み取れることを保証しません。上限付きの読み取りと再接続の規則は、コメントと価格履歴の更新を参照してください。

ネイティブの market-watch は、この通知を更新済みの market.snapshot に変換します。マーケットと注文板の値が変わらない場合も、この更新トリガーを返します。元の通知やソース位置は転送しません。このトリガーでコメントを読み取る場合は、refresh=true を使ってください。

ライフサイクルのリアルタイム更新

closed は、取引が終了したことを示します。勝利アウトカムの証明ではありません。検証済みのオラクル証拠でアウトカムが特定されるまで、finalOutcome は null です。期限によるクローズだけでは、勝者は決まりません。後から検証済みの結果が届くと、取引を再開せずに finalOutcome を設定します。 closedAt は最初のクローズ時刻を保持します。解決後に参加したクライアントも、現在の解決済み状態を受け取ります。 state が closed のままでも、MarketStatusChanged は検証済みの結果を通知します。

Portfolioクライアントは SetPortfolioValuationSubscriptions(conditionIds) で、確定した取引とライフサイクルの通知を受け取れます。このコンディション単位の購読は、注文板への参加やスナップショットの取得を行いません。その接続の購読対象を、最大200件の配列で置き換えます。空の配列で購読を解除してください。再接続後は購読対象を再送してください。値の確認にはPortfolio APIを使ってください。通知はベストエフォートであり、更新後の値を取得できる前に届く場合があります。

カタログの deadline は省略される場合や null の場合があります。これは期限がないことを示します。 createdAt で代用したり、不完全なレスポンスと扱ったりしないでください。期限がない場合も、ライフサイクルの正として state を使ってください。

マーケットのライフサイクル状態は、クライアントが閲覧している最中に変化することがあります。リアルタイムフィードでマーケットを購読しているクライアントは、コンディションの状態が遷移したとき—たとえばオラクルのアテステーションが到着するか解決期限を過ぎて open から closed になったとき—に MarketStatusChanged のプッシュを受け取ります。このメッセージは conditionId、新しい state（open または closed）、マーケットがクローズした後の closedAt タイムスタンプ、そしてアウトカムが確定している場合の勝利アウトカム finalOutcome を含みます。プッシュは、そのコンディションのいずれかのアウトカム別マーケットに参加しているクライアントに届きます。

マーケット詳細ページでは、そのマーケットのアウトカム別グループに参加している間、ライフサイクルの通知でベストエフォートの更新を行います。一覧や検索ページは、ライフサイクルの通知だけを目的として表示中の全マーケットへ参加しないでください。状態の正となるのはカタログの state フィールドです。接続、再接続、起動、またはバックグラウンドからの復帰時には、/api/v1/markets/query から現在の状態を読み取ってください。すべての通知を受信できるとは限りません。通知の欠落は、バックグラウンドポーリングではなく、起動時と表示復帰時の再照合で補ってください。

公開アテステーションの証拠

GET /api/v1/conditions/{conditionId}/attestation は、ウォレットやサインインを必要としません。レスポンスは conditionId、attestedOutcome、oracleWitness、 registeredAuthority、attestationEvent を含みます。検証済みの解決証拠がない場合は 404 を返します。期限でクローズした未解決マーケットも、この場合に含まれます。無効なコンディション識別子には 400 を返します。

attestationEvent は、保持された署名済み kind-89 イベントそのものです。 id、pubkey、createdAt、kind、tags、content、sig を含みます。 kind は数値の 89 です。 createdAt は、NIP-01 の created_at の Unix 時刻を保持します。署名済みイベントを復元する際は、タグの順序を変えないでください。この読み取りは、署名を作成せず、ミントでの償還完了も証明しません。請求にイベントを使う場合や、関連する説明を検証する場合は、登録済みのオラクル権限を検証してください。