{
  "openapi": "3.1.0",
  "info": {
    "title": "OutcomeScout API",
    "version": "0.1.0",
    "description": "Paid x402 endpoint that maps a news headline to top tradeable Polymarket prediction markets."
  },
  "servers": [
    {
      "url": "https://outcomescout.vercel.app"
    }
  ],
  "paths": {
    "/api/v1/news-to-markets": {
      "post": {
        "summary": "Map a news headline to tradeable Polymarket markets",
        "operationId": "newsToMarkets",
        "x-x402": { "scheme": "exact", "price": "$0.01", "network": "eip155:8453", "asset": "USDC", "payTo": "0xF0EfAfeD3BED84b12dc89Ba80E62131FAACE0eCD" },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["headline"],
                "properties": {
                  "headline": {
                    "type": "string",
                    "minLength": 5,
                    "maxLength": 500,
                    "description": "A news headline to map to prediction markets.",
                    "examples": ["Trump pushes Russia and Ukraine toward a ceasefire"]
                  },
                  "min_liquidity_usd": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Optional. Drop markets whose max safe 3%-slippage trade is below this USD size."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked tradeable Polymarket markets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "headline": { "type": "string" },
                    "request_ms": { "type": "number" },
                    "cost_paid": { "type": "string", "examples": ["$0.01 USDC"] },
                    "fetched_at": { "type": "string", "format": "date-time" },
                    "top_markets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": { "type": "integer" },
                          "relevance_score": { "type": "number" },
                          "event_title": { "type": "string" },
                          "outcome_type": { "type": "string", "enum": ["binary", "categorical", "threshold", "date"] },
                          "primary_label": { "type": "string" },
                          "market_question": { "type": "string" },
                          "current_price": { "type": "number", "description": "YES probability, 0-1." },
                          "spread_cents": { "type": "number" },
                          "size_at_best_ask_usd": { "type": "number" },
                          "max_safe_trade_3pct_usd": { "type": "number" },
                          "drift_24h_pct": { "type": ["number", "null"] },
                          "volume_24h": { "type": "number" },
                          "outcomes_in_event": { "type": "integer" },
                          "collapsed_count": { "type": "integer" },
                          "ladder": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "label": { "type": "string" },
                                "price": { "type": "number" }
                              }
                            }
                          },
                          "days_to_resolution": { "type": ["integer", "null"] },
                          "implied_level": { "type": ["string", "null"] },
                          "bet_link": { "type": "string", "format": "uri" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "x402 payment required. Price: $0.01 USDC on Base mainnet, exact scheme."
          }
        }
      }
    }
  }
}