{
  "openapi": "3.1.0",
  "info": {
    "title": "GEXLOG Agent API",
    "version": "1.0.0",
    "description": "SPX options market intelligence for AI agents. Gamma regime classification, GEX levels, dealer positioning, and AI-generated market narratives. Free current data; historical and bulk endpoints gated by x402 USDC micropayments.",
    "x-guidance": "Start with GET /agent/current for today's briefing (free). Use GET /agent/dates to discover available archive dates (free). Historical lookups, date ranges, and regime timelines require x402 payment. All responses are JSON.",
    "contact": {
      "email": "contact@gexlog.com"
    }
  },
  "servers": [
    {
      "url": "https://agent.gexlog.com"
    }
  ],
  "paths": {
    "/agent/current": {
      "get": {
        "operationId": "get_current_briefing",
        "summary": "Current morning briefing",
        "description": "Today's SPX options market briefing including gamma regime, GEX levels, dealer positioning, pivot levels, expected move, and AI-generated narrative. Returns morning report on trading days, weekend preview on weekends.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Current market briefing",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketBriefing" }
              }
            }
          }
        }
      }
    },
    "/agent/evening": {
      "get": {
        "operationId": "get_evening_briefing",
        "summary": "Current evening briefing",
        "description": "Post-market session recap with forecast accuracy scoring, session high/low analysis, and next-day outlook.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Evening market briefing",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketBriefing" }
              }
            }
          }
        }
      }
    },
    "/agent/weekend": {
      "get": {
        "operationId": "get_weekend_briefing",
        "summary": "Current weekend preview",
        "description": "Weekend market preview with week-ahead outlook. Available on Saturdays; Sunday requests return the Saturday file.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Weekend market preview",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MarketBriefing" }
              }
            }
          }
        }
      }
    },
    "/agent/dates": {
      "get": {
        "operationId": "get_available_dates",
        "summary": "Available archive dates",
        "description": "List of all dates with archived SPX options market data. Use these dates as input to /agent/historical, /agent/range, and /agent/regime.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Array of available date strings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dates": {
                      "type": "array",
                      "items": { "type": "string", "format": "date" },
                      "description": "Available archive dates in YYYY-MM-DD format"
                    },
                    "count": {
                      "type": "integer",
                      "description": "Total number of available dates"
                    }
                  },
                  "required": ["dates", "count"]
                }
              }
            }
          }
        }
      }
    },
    "/agent/health": {
      "get": {
        "operationId": "health_check",
        "summary": "Health check",
        "description": "Returns API health status and server timestamp.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Health status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["ok"] },
                    "timestamp": { "type": "string", "format": "date-time" }
                  },
                  "required": ["status", "timestamp"]
                }
              }
            }
          }
        }
      }
    },
    "/agent/solana-blockhash": {
      "get": {
        "operationId": "get_solana_blockhash",
        "summary": "Solana blockhash proxy",
        "description": "Proxies getLatestBlockhash from Solana mainnet RPC. Required because browser requests to Solana RPC are blocked. Used internally by the x402 Solana payment flow.",
        "tags": ["Free"],
        "security": [],
        "responses": {
          "200": {
            "description": "Solana blockhash result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "context": {
                      "type": "object",
                      "properties": {
                        "slot": { "type": "integer" }
                      }
                    },
                    "value": {
                      "type": "object",
                      "properties": {
                        "blockhash": { "type": "string" },
                        "lastValidBlockHeight": { "type": "integer" }
                      },
                      "required": ["blockhash", "lastValidBlockHeight"]
                    }
                  },
                  "required": ["context", "value"]
                }
              }
            }
          }
        }
      }
    },
    "/agent/historical": {
      "get": {
        "operationId": "get_historical_briefing",
        "summary": "Historical briefing by date",
        "description": "Full SPX options market report for any past date. By default returns morning, evening, and weekend reports bundled. Use report_type to request a specific report.",
        "tags": ["Paid"],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.010000" },
          "protocols": [{ "x402": {} }]
        },
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "description": "Target date in YYYY-MM-DD format. Use /agent/dates to discover valid dates."
          },
          {
            "name": "report_type",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "enum": ["morning", "evening", "weekend", "both"], "default": "both" },
            "description": "Which report to return. 'both' (default) returns morning, evening, and weekend keyed by type."
          }
        ],
        "responses": {
          "200": {
            "description": "Historical briefing data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "morning": { "$ref": "#/components/schemas/MarketBriefing" },
                    "evening": { "$ref": "#/components/schemas/MarketBriefing" },
                    "weekend": { "$ref": "#/components/schemas/MarketBriefing" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/agent/range": {
      "get": {
        "operationId": "get_date_range",
        "summary": "Multi-day dataset",
        "description": "SPX options market data for a date range, max 30 days. Returns regime classifications, key levels, and positioning data for each trading day in the range.",
        "tags": ["Paid"],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" },
          "protocols": [{ "x402": {} }]
        },
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "description": "Range start date (YYYY-MM-DD)"
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "date" },
            "description": "Range end date (YYYY-MM-DD)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 30, "maximum": 30 },
            "description": "Maximum number of days to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of daily briefing data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/MarketBriefing" }
                    },
                    "count": { "type": "integer" },
                    "start": { "type": "string", "format": "date" },
                    "end": { "type": "string", "format": "date" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    },
    "/agent/regime": {
      "get": {
        "operationId": "get_regime_history",
        "summary": "Regime classification timeline",
        "description": "Lightweight gamma regime classification history, max 90 days. Shows how dealer positioning and gamma regime shifted over time without full briefing data.",
        "tags": ["Paid"],
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" },
          "protocols": [{ "x402": {} }]
        },
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Range start date (YYYY-MM-DD). Defaults to 90 days ago."
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "date" },
            "description": "Range end date (YYYY-MM-DD). Defaults to today."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 90, "maximum": 90 },
            "description": "Maximum number of days to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of regime classification records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/RegimeRecord" }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "402": { "description": "Payment Required" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MarketBriefing": {
        "type": "object",
        "description": "Full SPX options market briefing with gamma regime, levels, positioning, and AI narrative.",
        "properties": {
          "generated_at": { "type": "string", "format": "date-time", "description": "When this briefing was generated" },
          "market": {
            "type": "object",
            "description": "Current market data snapshot",
            "properties": {
              "spx": { "type": "number" },
              "vix": { "type": "number" },
              "es": { "type": "number" },
              "nq": { "type": "number" }
            }
          },
          "levels": {
            "type": "object",
            "description": "Key price levels from options positioning",
            "properties": {
              "current": { "type": "number", "description": "SPX spot price at generation" },
              "call_wall": { "type": "number" },
              "put_wall": { "type": "number" },
              "gex_flip": { "type": ["number", "null"], "description": "GEX flip level, null if no zero crossing in observable chain" },
              "max_gamma": { "type": "number" }
            }
          },
          "forecast": {
            "type": "object",
            "description": "Market forecast including gamma regime and expected move",
            "properties": {
              "factors": {
                "type": "object",
                "properties": {
                  "gamma": {
                    "type": "object",
                    "properties": {
                      "regime": { "type": "string", "description": "Gamma regime classification" },
                      "total_gex": { "type": "number" }
                    }
                  }
                }
              }
            }
          },
          "guidance": {
            "type": "object",
            "description": "Trade guidance signals",
            "properties": {
              "signal": { "type": "string", "enum": ["GO", "CAUTION", "WAIT"], "description": "Primary trade signal" },
              "confidence": { "type": "number" }
            }
          },
          "ai_narrative_primary": { "type": "string", "description": "AI-generated market narrative (Claude)" },
          "ai_narrative_secondary": { "type": "string", "description": "AI-generated market narrative (Gemini)" }
        }
      },
      "RegimeRecord": {
        "type": "object",
        "description": "Single-day gamma regime classification",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "regime": { "type": "string", "description": "Gamma regime classification (e.g., Positive Gamma, Negative Gamma, Transition)" },
          "total_gex": { "type": "number", "description": "Total gamma exposure value" },
          "signal": { "type": "string", "enum": ["GO", "CAUTION", "WAIT"] },
          "spx_close": { "type": "number" },
          "vix_close": { "type": "number" }
        },
        "required": ["date", "regime"]
      }
    }
  }
}