{
  "openapi": "3.1.0",
  "info": {
    "title": "Stocks On Chain API",
    "version": "1.0.0",
    "summary": "Tokenized stock data, free and keyless.",
    "description": "Static JSON describing every tokenized stock we track: the stock, each instrument (one per issuer, with the legal wrapper and corporate-action mechanic), each listing under it (chain, contract address), prices with timestamps, and corporate actions read from chain state. No authentication, no rate limit, CORS open. Nothing in this API ranks or rates anything; every ordered collection states its own sortKey.",
    "contact": {
      "name": "Gwei, Inc.",
      "email": "gweistocksonchain@gmail.com",
      "url": "https://stocksonchain.io"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://stocksonchain.io"
    }
  ],
  "externalDocs": {
    "description": "Agent and API documentation",
    "url": "https://stocksonchain.io/developers/agents"
  },
  "components": {
    "schemas": {
      "Mechanics": {
        "description": "How one issuer handles corporate actions for a stock. A tagged union - read `kind` before reaching for any other field. Anything that is not erc8056 has no multiplier at all; the field is structurally absent, not null and not 1.0. `kind` is the shape reported here, NOT the standard a contract implements: only Robinhood tokens implement ERC-8056, Ondo publishes the same figure from a separate oracle, and Backed reads it from a Token-2022 extension.",
        "oneOf": [
          {
            "type": "object",
            "title": "erc8056",
            "required": [
              "kind",
              "multiplier",
              "supplyUI"
            ],
            "properties": {
              "kind": {
                "const": "erc8056"
              },
              "multiplier": {
                "type": "number"
              },
              "supplyUI": {
                "type": "number"
              },
              "supplyDerived": {
                "type": "boolean"
              },
              "pending": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "events": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "effectiveYield": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          {
            "type": "object",
            "title": "distribution",
            "required": [
              "kind"
            ],
            "properties": {
              "kind": {
                "const": "distribution"
              },
              "lastDistribution": {
                "type": [
                  "object",
                  "null"
                ]
              }
            }
          },
          {
            "type": "object",
            "title": "reserve",
            "required": [
              "kind"
            ],
            "properties": {
              "kind": {
                "const": "reserve"
              },
              "attestationUrl": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ratio": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          }
        ]
      }
    }
  },
  "paths": {
    "/api/tokens.json": {
      "get": {
        "operationId": "listTokens",
        "summary": "Every tokenized stock, with every instrument and listing",
        "description": "The full snapshot. Each stock carries an instruments array (one per issuer) and a listings array (one per issuer and chain). An issuer can put the same product on several chains, so instruments answer what the options are and listings answer what the address is on a given chain.",
        "responses": {
          "200": {
            "description": "Snapshot of all stocks and listings.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/tokens/{slug}.json": {
      "get": {
        "operationId": "getToken",
        "summary": "One stock",
        "description": "One stock, its listings, the events recorded against it, holder concentration and a daily history rollup.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Lowercase ticker, for example `nvda`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One stock and everything known about it.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No stock with that slug is tracked."
          }
        }
      }
    },
    "/api/events.json": {
      "get": {
        "operationId": "listEvents",
        "summary": "Corporate actions",
        "description": "Splits, distributions and multiplier changes read from chain state, each with a transaction hash, plus scheduled changes not yet effective. Ordered by when the event took effect, newest first. That is chronology, not a ranking.",
        "responses": {
          "200": {
            "description": "The corporate-action tape.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/tradfi.json": {
      "get": {
        "operationId": "listTradfiTickers",
        "summary": "Every ticker on the old market",
        "description": "Ticker and company name for the whole listed market, from the SEC's own company_tickers.json. This is what lets a consumer answer \"that is a real stock, and it is not tokenized yet\" instead of returning nothing.",
        "responses": {
          "200": {
            "description": "Ticker index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/manifest.json": {
      "get": {
        "operationId": "getAgentManifest",
        "summary": "Agent tier terms",
        "description": "The free endpoints, the bulk dataset, and its price if the paid tier is live.",
        "responses": {
          "200": {
            "description": "Machine-readable tier descriptor.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/dataset.json": {
      "get": {
        "operationId": "getDataset",
        "summary": "Bulk dataset",
        "description": "Everything in one request: snapshot, chains matrix, yields, event tape and position changes. Currently free while the paid tier is being switched on.",
        "responses": {
          "200": {
            "description": "The bulk dataset.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  }
}