pmxt-core 2.50.16 → 2.51.0

package/dist/exchanges/hunch/api.js

@@ -0,0 +1,820 @@
+"use strict";
+/**
+ * Embedded Hunch agent-platform OpenAPI spec (subset).
+ *
+ * SOURCED VERBATIM from the LIVE spec at https://www.playhunch.xyz/openapi.json
+ * (fetched while authoring this adapter), trimmed to the operations the Hunch
+ * adapter actually drives. operationIds are preserved exactly so the implicit
+ * API generated by parseOpenApiSpec() exposes them under the same names:
+ *   listMarkets, getMarket, researchMarket, quoteBet, placeBet,
+ *   listPositions, getResult, checkWallet, getStats, getHealth.
+ *
+ * MAINTAINER NOTE: regenerate by re-fetching /openapi.json (the project would
+ * normally do this via `npm run fetch:openapi`; this exchange was authored
+ * against the live prod spec directly). Hunch reads are keyless (no security
+ * scheme); the trade route settles via x402 / EIP-3009 — see index.ts createOrder.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hunchApiSpec = void 0;
+exports.hunchApiSpec = {
+    "openapi": "3.1.0",
+    "info": {
+        "title": "Hunch agent platform API",
+        "version": "hunch-agent-api-v1"
+    },
+    "servers": [
+        {
+            "url": "https://www.playhunch.xyz"
+        }
+    ],
+    "paths": {
+        "/api/agent/v1/markets": {
+            "get": {
+                "operationId": "listMarkets",
+                "summary": "List tradeable markets with live odds.",
+                "description": "List tradeable markets with live odds.",
+                "tags": [
+                    "markets"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "status",
+                        "in": "query",
+                        "required": false,
+                        "description": "open (default) = tradeable now; all includes settled markets.",
+                        "schema": {
+                            "type": "string",
+                            "enum": [
+                                "open",
+                                "all"
+                            ],
+                            "default": "open"
+                        }
+                    },
+                    {
+                        "name": "type",
+                        "in": "query",
+                        "required": false,
+                        "description": "Exact targetMetric filter (e.g. market_cap, price_direction, token_mcap_flip).",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "token",
+                        "in": "query",
+                        "required": false,
+                        "description": "Case-insensitive token symbol filter (e.g. BNKR).",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "ids",
+                        "in": "query",
+                        "required": false,
+                        "description": "Comma-separated batch of market ids or slugs.",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "required": false,
+                        "description": "Maximum results (≤ 200).",
+                        "schema": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 200
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "The Base-only tradeable market list with live odds.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "count": {
+                                            "type": "integer"
+                                        },
+                                        "markets": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/AgentMarketRef"
+                                            }
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "count",
+                                        "markets"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/markets/{id}": {
+            "get": {
+                "operationId": "getMarket",
+                "summary": "One market's full reference: question, odds, outcomes, deadline, fee, links.",
+                "description": "One market's full reference: question, odds, outcomes, deadline, fee, links.",
+                "tags": [
+                    "markets"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "required": true,
+                        "description": "Market id or slug.",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "The market's enriched reference (live odds + stats folded in).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "market": {
+                                            "$ref": "#/components/schemas/AgentMarketRef"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "market"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/markets/{id}/research": {
+            "get": {
+                "operationId": "researchMarket",
+                "summary": "Decision-grade research: resolution rules, odds history, observations, price impact, related markets.",
+                "description": "Decision-grade research: resolution rules, odds history, observations, price impact, related markets.",
+                "tags": [
+                    "markets"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "required": true,
+                        "description": "Market id or slug.",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Decision-grade research. The advisory field is DATA ONLY (always null in Phase 1) — the betting decision is the agent's own.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "research": {
+                                            "$ref": "#/components/schemas/AgentResearch"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "research"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/quote": {
+            "get": {
+                "operationId": "quoteBet",
+                "summary": "Price a bet: tier, priceCents, estimatedShares, fee breakdown, 60s quoteId.",
+                "description": "Price a bet: tier, priceCents, estimatedShares, fee breakdown, 60s quoteId.",
+                "tags": [
+                    "trading"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "marketId",
+                        "in": "query",
+                        "required": true,
+                        "description": "Market id or slug.",
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "side",
+                        "in": "query",
+                        "required": false,
+                        "description": "yes | no | up | down | <bucketKey> — validated against the market's outcome keys.",
+                        "schema": {
+                            "type": "string",
+                            "default": "yes"
+                        }
+                    },
+                    {
+                        "name": "sizeUsd",
+                        "in": "query",
+                        "required": false,
+                        "description": "Bet size in USD. $1 floor, NO maximum — a quote above $10 persists a verifiable 60-second lock behind its quoteId.",
+                        "schema": {
+                            "type": "number",
+                            "minimum": 1,
+                            "default": 1
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "The live quote. Always carries a quoteId; pass suggestedMinSharesOut back as minSharesOut on a locked-tier trade.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "quote": {
+                                            "$ref": "#/components/schemas/AgentQuote"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "quote"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "invalid_request — marketId missing, or sizeUsd above the $1,000,000,000 technical precision bound (split the bet).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "size_below_min (the $1 floor) or invalid_side.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "429": {
+                        "description": "rate_limited — 30 quotes/min per IP.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "internal_error — the book or quote storage was unreadable; retry shortly.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/trade": {
+            "post": {
+                "operationId": "placeBet",
+                "summary": "Place a bet via x402 (USDC on Base). simulate:true = $0 dry-run of the full pipeline. $1 floor, NO maximum.",
+                "description": "Settle a real USDC bet on Base via x402 — or dry-run it for $0 with \"simulate\": true (runs the FULL validation pipeline, including locked-tier quote verification, but moves nothing). Flow: POST the bet body with no payment header → HTTP 402 challenge → sign an EIP-3009 transferWithAuthorization for exactly accepts[0].maxAmountRequired → retry the SAME body with the X-PAYMENT header. Keyless: the paying wallet IS the account. $1 floor, NO maximum; above $10 the body must also carry quoteId plus minSharesOut or maxPriceCents (from GET /api/agent/v1/quote). Idempotent on idemKey — a replay returns the original receipt and never double-settles.",
+                "tags": [
+                    "trading"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "X-PAYMENT",
+                        "in": "header",
+                        "required": false,
+                        "description": "base64(JSON x402 envelope) carrying the signed EIP-3009 transferWithAuthorization. Omit on the first call to receive the 402 challenge; retry the SAME body with this header to settle. Not needed when simulate is true.",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/AgentTradeRequest"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "The trade receipt. simulated:true receipts carry txHash:null — no funds moved.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "replay": {
+                                            "type": "boolean",
+                                            "description": "true when this idemKey had already settled — the ORIGINAL receipt is returned (no double-settle)."
+                                        },
+                                        "receipt": {
+                                            "$ref": "#/components/schemas/AgentTradeReceipt"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "receipt"
+                                    ]
+                                }
+                            }
+                        },
+                        "headers": {
+                            "X-Payment-Response": {
+                                "description": "base64 settlement summary {success, transaction, network, payer}. Present after real settlement; absent on a simulate receipt.",
+                                "schema": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "invalid_request — the body is not valid JSON or fails the strict AgentTradeRequest schema (per-field problems are listed in the error's issues extra).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "402": {
+                        "description": "x402 payment challenge — the request carried no (or an invalid) X-PAYMENT header. Sign an EIP-3009 transferWithAuthorization for exactly accepts[0].maxAmountRequired to accepts[0].payTo on Base, then retry the SAME POST body with the X-PAYMENT header (base64 of the signed envelope). The challenge resource embeds this trade's intent hash for audit.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/X402Challenge"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "409": {
+                        "description": "market_closed (no longer accepts bets) or idem_conflict (this idemKey was used for a DIFFERENT trade — generate a fresh one).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "invalid_side / invalid_wallet / size_below_min / quote_required / quote_expired / quote_mismatch / slippage_exceeded / insufficient_balance / pool_impact_exceeded / unsupported_market / payment_invalid — the error code + hint say exactly what to change.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "429": {
+                        "description": "rate_limited — 10 trades/min per wallet (also returned with status 409 semantics when the same idemKey is already settling — retry it shortly to fetch the receipt).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "internal_error — possibly reconcilable: if the tx WAS submitted but recording failed, the body carries txHash; retry with the SAME idemKey to fetch the receipt (settlement is idempotent).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "503": {
+                        "description": "platform_paused — trading is temporarily paused (kill switch) or settlement is unavailable. Poll GET /api/agent/v1/health.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/positions": {
+            "get": {
+                "operationId": "listPositions",
+                "summary": "A wallet's open + resolved positions with live PnL (merges the Bankr partner rail).",
+                "description": "A wallet's open + resolved positions with live PnL (merges the Bankr partner rail).",
+                "tags": [
+                    "positions"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "wallet",
+                        "in": "query",
+                        "required": true,
+                        "description": "The betting wallet (0x + 40 hex). Merges BOTH rail identities (agent: and bankr:) so the full book is visible.",
+                        "schema": {
+                            "type": "string",
+                            "pattern": "^0x[0-9a-fA-F]{40}$"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Open + resolved positions with live PnL, newest first.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "wallet": {
+                                            "type": "string"
+                                        },
+                                        "count": {
+                                            "type": "integer"
+                                        },
+                                        "summary": {
+                                            "$ref": "#/components/schemas/AgentPositionsSummary"
+                                        },
+                                        "positions": {
+                                            "type": "array",
+                                            "items": {
+                                                "$ref": "#/components/schemas/AgentPosition"
+                                            }
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "wallet",
+                                        "count",
+                                        "summary",
+                                        "positions"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "invalid_wallet — not a 0x + 40-hex Base address.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/result": {
+            "get": {
+                "operationId": "getResult",
+                "summary": "A market's resolution status, winning outcome, and payout-per-share.",
+                "description": "A market's resolution status, winning outcome, and payout-per-share.",
+                "tags": [
+                    "positions"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "marketId",
+                        "in": "query",
+                        "required": true,
+                        "description": "Market id or slug — resolved against the FULL catalogue (anything the agent may hold).",
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "The resolution view. An unresolved market returns status \"pending\" with null outcome fields.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "result": {
+                                            "$ref": "#/components/schemas/AgentResult"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "result"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "invalid_request — marketId is required.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/wallet/{address}/readiness": {
+            "get": {
+                "operationId": "checkWallet",
+                "summary": "Wallet readiness: Base USDC balance, min-bet coverage, funding guidance (gas never needed).",
+                "description": "Wallet readiness: Base USDC balance, min-bet coverage, funding guidance (gas never needed).",
+                "tags": [
+                    "platform"
+                ],
+                "x-hunch-status": "live",
+                "parameters": [
+                    {
+                        "name": "address",
+                        "in": "path",
+                        "required": true,
+                        "description": "Base wallet address (0x + 40 hex).",
+                        "schema": {
+                            "type": "string",
+                            "pattern": "^0x[0-9a-fA-F]{40}$"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Funding readiness: Base USDC balance, min-bet coverage, funding guidance. Gas is NEVER needed — transfers are relayed; the wallet only holds USDC.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "readiness": {
+                                            "$ref": "#/components/schemas/AgentReadiness"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "readiness"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "invalid_wallet — not a 0x + 40-hex Base address.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/stats": {
+            "get": {
+                "operationId": "getStats",
+                "summary": "Platform trust stats: markets, volume, payouts, auto-payout rate, proof samples.",
+                "description": "Platform trust stats: markets, volume, payouts, auto-payout rate, proof samples.",
+                "tags": [
+                    "platform"
+                ],
+                "x-hunch-status": "live",
+                "responses": {
+                    "200": {
+                        "description": "Platform trust stats (cached ~60s): markets, lifetime bets + volume, paid-out USD, auto-payout rate, on-chain proof samples.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "stats": {
+                                            "$ref": "#/components/schemas/AgentStats"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "stats"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "/api/agent/v1/health": {
+            "get": {
+                "operationId": "getHealth",
+                "summary": "Liveness + trading status. 200 even when degraded; ok:false means paused.",
+                "description": "Liveness + trading status. Deliberately HTTP 200 even when degraded — branch on the BODY's health.ok (false = trading paused), never on the status code.",
+                "tags": [
+                    "platform"
+                ],
+                "x-hunch-status": "live",
+                "responses": {
+                    "200": {
+                        "description": "Always 200 while the platform flag is on; health.ok carries the signal.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "meta": {
+                                            "$ref": "#/components/schemas/AgentMeta"
+                                        },
+                                        "health": {
+                                            "$ref": "#/components/schemas/AgentHealth"
+                                        }
+                                    },
+                                    "required": [
+                                        "meta",
+                                        "health"
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found — an unknown id/slug, or the agent platform flag is off (the entire /api/agent/v1 surface returns 404 while dark).",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/AgentError"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+};