{
  "openapi": "3.0.3",
  "info": {
    "title": "PARE public API",
    "version": "2026-09-30",
    "description": "Read-only data for PARE on Robinhood Chain (chain id 4663): pool prices, fixed rates, the market's dividend forecast, the dividend oracle, and the lending market. No key. Responses are cached about 30 seconds. Addresses and how to act on chain: https://parestocks.com/agents.md"
  },
  "servers": [{ "url": "https://parestocks.com" }],
  "paths": {
    "/api/rates": {
      "get": {
        "summary": "Fixed rates and the market's dividend forecast, per series",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rates" } } } } }
      }
    },
    "/api/oracle": {
      "get": {
        "summary": "The dividend oracle: multiplier, dividend index, split factor and sync state per stock token",
        "parameters": [{ "name": "token", "in": "query", "required": false, "schema": { "type": "string", "example": "pfe" }, "description": "One token by key (aapl, spy, qqq, pfe, schd, nvda, msft, sgov, jnj)" }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Oracle" } } } } }
      }
    },
    "/api/markets": {
      "get": {
        "summary": "Every Uniswap v3 pool the app trades through, with price and depth",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Markets" } } } } }
      }
    },
    "/api/market": {
      "get": {
        "summary": "The Morpho Blue lending markets for pTokens",
        "parameters": [{ "name": "id", "in": "query", "required": false, "schema": { "type": "string", "example": "pspy" }, "description": "One market by key. Without it, every market." }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LendingMarket" } } } } }
      }
    },
    "/api/history": {
      "get": {
        "summary": "Daily history of the fixed rate and the market's dividend forecast, since the pools opened (for backtesting)",
        "parameters": [
          { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "enum": ["pfe", "spy", "qqq", "aapl", "all"], "default": "pfe" } },
          { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["csv"] }, "description": "CSV with one row per series-day" },
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "First UTC day to include" }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/History" } }, "text/csv": {} } } }
      }
    },
    "/api/pool": {
      "get": {
        "summary": "One pool: price history, state now, LP positions",
        "parameters": [
          { "name": "series", "in": "query", "required": true, "schema": { "type": "string", "example": "pfe" } },
          { "name": "pair", "in": "query", "required": false, "schema": { "type": "string", "enum": ["stock"] }, "description": "For pfe, the pPFE/PFE pool instead of pPFE/USDG" }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/series": {
      "get": {
        "summary": "Vault and accountant state for one series",
        "parameters": [{ "name": "series", "in": "query", "required": true, "schema": { "type": "string", "example": "spy" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/rh-tokens": {
      "get": {
        "summary": "Every Robinhood stock token on the chain, with dividend and coverage flags",
        "parameters": [{ "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": ["text"] } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/read": {
      "get": {
        "summary": "One eth_call against Robinhood Chain",
        "parameters": [
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "data", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "block", "in": "query", "required": false, "schema": { "type": "string", "default": "latest" } }
        ],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/tx": {
      "get": {
        "summary": "What one transaction did, with the revert reason decoded if it failed",
        "parameters": [{ "name": "hash", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/api/liq": {
      "get": {
        "summary": "USD liquidity of stock tokens against USDG and WETH on Uniswap v3",
        "parameters": [{ "name": "tokens", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated token addresses" }],
        "responses": { "200": { "description": "OK" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Rates": {
        "type": "object",
        "properties": {
          "asOf": { "type": "integer", "description": "Unix seconds" },
          "series": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string", "example": "pfe" },
                "symbol": { "type": "string", "example": "PFE" },
                "tag": { "type": "string", "example": "PFE-DEC27" },
                "stock": { "type": "string" }, "vault": { "type": "string" }, "pt": { "type": "string" }, "yt": { "type": "string" },
                "pool": { "type": "string", "description": "The pToken/stock pool" },
                "ytPool": { "type": "string", "nullable": true, "description": "The yToken/stock pool read for py, if any" },
                "px": { "type": "number", "nullable": true, "description": "Stock per pToken" },
                "discount": { "type": "number", "nullable": true, "description": "1 − px" },
                "fixed": { "type": "number", "nullable": true, "description": "Annualised return from buying at px and redeeming one share at maturity" },
                "py": { "type": "number", "nullable": true, "description": "Stock per yToken: the price of every dividend to maturity, as a fraction of a share" },
                "dividendsToMaturity": { "type": "number", "nullable": true, "description": "py when the yToken pool has a price, else 1 − px" },
                "impliedDividendYield": { "type": "number", "nullable": true, "description": "dividendsToMaturity ÷ years: the market's dividend forecast, simple annual" },
                "impliedSource": { "type": "string", "nullable": true, "enum": ["yt-pool", "pt-discount"] },
                "maturity": { "type": "integer", "nullable": true, "description": "Unix seconds" },
                "years": { "type": "number", "nullable": true },
                "synced": { "type": "boolean", "nullable": true, "description": "False while a multiplier change awaits classification: treat prices as stale" },
                "drip": { "type": "number", "nullable": true, "description": "Dividend growth the vault has banked so far" }
              }
            }
          }
        }
      },
      "History": {
        "type": "object",
        "properties": {
          "key": { "type": "string" }, "symbol": { "type": "string" }, "tag": { "type": "string" }, "maturity": { "type": "integer" }, "asOf": { "type": "integer" },
          "days": { "type": "array", "items": { "type": "object", "properties": {
            "date": { "type": "string", "format": "date", "description": "UTC day" },
            "px": { "type": "number", "nullable": true, "description": "Close, stock per pToken" },
            "fixed": { "type": "number", "nullable": true, "description": "Annualised return from px to maturity, at that day's end" },
            "py": { "type": "number", "nullable": true, "description": "Close, stock per yToken" },
            "dividendsToMaturity": { "type": "number", "nullable": true },
            "impliedDividendYield": { "type": "number", "nullable": true, "description": "dividendsToMaturity ÷ years left, simple annual" },
            "source": { "type": "string", "nullable": true, "enum": ["yt-pool", "pt-discount"] },
            "years": { "type": "number" },
            "ptSwaps": { "type": "integer", "description": "Trades in the pToken pool that day; 0 means the close was carried forward" },
            "ytSwaps": { "type": "integer" } } } }
        }
      },
      "Oracle": {
        "type": "object",
        "properties": {
          "asOf": { "type": "integer" },
          "tokens": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" }, "symbol": { "type": "string" }, "stock": { "type": "string" }, "accountant": { "type": "string" },
                "uiMultiplier": { "type": "number" }, "newUIMultiplier": { "type": "number" }, "effectiveAt": { "type": "integer" }, "scheduled": { "type": "boolean" },
                "dividendIndex": { "type": "number" }, "splitFactor": { "type": "number" }, "isSynced": { "type": "boolean" },
                "pending": { "type": "object", "nullable": true }, "lastEvent": { "type": "object", "nullable": true }
              }
            }
          }
        }
      },
      "Markets": {
        "type": "object",
        "properties": {
          "asOf": { "type": "integer" },
          "pools": { "type": "array", "items": { "type": "object", "properties": {
            "a": { "type": "string" }, "b": { "type": "string" }, "fee": { "type": "integer", "description": "Fee tier in hundredths of a bip: 500 = 0.05%" }, "addr": { "type": "string" },
            "sqrtPriceX96": { "type": "string" }, "tick": { "type": "integer" }, "liquidity": { "type": "string" }, "token0": { "type": "string" }, "balances": { "type": "object" } } } },
          "checked": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Every pair looked up, so absent pools can be cached too" }
        }
      },
      "LendingMarket": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "example": "pspy" }, "id": { "type": "string", "description": "Morpho market id" }, "morpho": { "type": "string" },
          "pt": { "type": "string" }, "loan": { "type": "string" }, "oracle": { "type": "string" }, "lltv": { "type": "number", "example": 0.625 },
          "lent": { "type": "number" }, "borrowed": { "type": "number" }, "available": { "type": "number" }, "utilisation": { "type": "number" },
          "borrowApy": { "type": "number" }, "lendApy": { "type": "number" }, "open": { "type": "boolean" },
          "oracleRead": { "type": "object", "properties": { "priceUsdgPerPt": { "type": "number" }, "synced": { "type": "boolean" }, "feedStale": { "type": "boolean" } } }
        }
      }
    }
  }
}