{
  "openapi": "3.1.0",
  "info": {
    "title": "OnTheTape Partner API",
    "version": "1.0.0",
    "description": "Read-only API mirroring onthetape.io \u2014 firms, verified payouts, RiseUSD cash-on-hand, whales, Topstep & Lucid boards. Same data path as the website. No scraping. No writes."
  },
  "servers": [
    {
      "url": "https://onthetape.io",
      "description": "Production"
    },
    {
      "url": "https://site-staging-eb18.up.railway.app",
      "description": "Staging"
    },
    {
      "url": "http://127.0.0.1:8088",
      "description": "Local"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "example": "1234.56",
            "description": "Decimal string (never a JSON number)"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              },
              "details": {
                "type": "object"
              }
            }
          }
        }
      }
    },
    "parameters": {
      "limit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "default": 50,
          "maximum": 200
        }
      },
      "cursor": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        }
      },
      "window": {
        "name": "window",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "24h",
            "7d",
            "30d",
            "365d",
            "ytd",
            "alltime"
          ],
          "default": "24h"
        }
      }
    }
  },
  "paths": {
    "/v1/health": {
      "get": {
        "security": [],
        "summary": "Liveness",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/meta": {
      "get": {
        "summary": "Capabilities + freshness",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "security": [],
        "summary": "OpenAPI document",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Rankings for a window",
        "parameters": [
          {
            "$ref": "#/components/parameters/window"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/firms": {
      "get": {
        "summary": "List firms",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          },
          {
            "$ref": "#/components/parameters/window"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "-total"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/firms/{firm_id}": {
      "get": {
        "summary": "Firm detail (includes windows[] for every ranking period)",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/window"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/firms/{firm_id}/bundle": {
      "get": {
        "summary": "Full firm pack: all windows, pulse, cash, payouts, board",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "payout_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/firms/{firm_id}/payouts": {
      "get": {
        "summary": "Payouts for one firm",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          },
          {
            "$ref": "#/components/parameters/window"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/firms/{firm_id}/pulse": {
      "get": {
        "summary": "30 UTC-day payout pulse",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/firms/{firm_id}/cash-on-hand": {
      "get": {
        "summary": "Latest RiseUSD treasury snapshot",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "No snapshot"
          }
        }
      }
    },
    "/v1/firms/{firm_id}/cash-on-hand/history": {
      "get": {
        "summary": "Treasury history (latest-only until site publishes series)",
        "parameters": [
          {
            "name": "firm_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/payouts": {
      "get": {
        "summary": "Recent verified payouts",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          },
          {
            "name": "firm_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_amount",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/cash-on-hand": {
      "get": {
        "summary": "Latest snapshot for every mapped treasury",
        "parameters": [
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "$ref": "#/components/parameters/cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/treasuries": {
      "get": {
        "summary": "Alias of cash-on-hand list",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/inflows": {
      "get": {
        "summary": "Recent RiseUSD treasury deposits",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/cash": {
      "get": {
        "summary": "Full cash radar bundle",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/whales": {
      "get": {
        "summary": "Pseudonymous payee tags",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/topstep": {
      "get": {
        "summary": "Topstep board (Discord bot book)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/lucid": {
      "get": {
        "summary": "Lucid board",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Search firms + recent payouts",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "summary": "Ingest lane health",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/stream": {
      "get": {
        "summary": "SSE instructions (shares /api/stream)",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}