{
  "openapi": "3.1.0",
  "info": {
    "title": "ACCRUE Public API",
    "summary": "Read-only public API for the ACCRUE stablecoin yield platform and the Stablecoin Yield Index (SYX).",
    "description": "Public API for ACCRUE — a non-custodial stablecoin yield platform on Ethereum, Base, and Arbitrum. This specification documents the read-only data endpoints: the live Stablecoin Yield Index (SYX), the SYX methodology, the SYX history, and live per-vault APY snapshots for all 12 retail yield strategies (Aave v3, Compound v3, and curated Morpho v2 vaults from Steakhouse Financial and Gauntlet).\n\nAll endpoints return JSON, require no authentication, and are CORS-open. Data is read directly from canonical smart contracts on each chain and refreshes every 15 minutes.\n\nFor stateful AI-agent interactions (multi-turn tool use, model portfolios, yield calculations, recommendations), use the ACCRUE MCP server at https://accrue.cc/mcp instead — it implements the Model Context Protocol over JSON-RPC 2.0 and is compatible with Claude, Claude Code, Cursor, Cline, and any MCP-aware client.\n\nDeposit and withdrawal execution by AI agents is not yet exposed via this API. Stage 2 (Q3 2026) will add MCP tools that return unsigned transaction data for the agent's wallet to sign and broadcast. ACCRUE never custodies funds at any stage.",
    "version": "1.0.0",
    "contact": {
      "name": "ACCRUE",
      "url": "https://accrue.cc"
    },
    "license": {
      "name": "ACCRUE Terms of Service",
      "url": "https://accrue.cc/terms"
    },
    "termsOfService": "https://accrue.cc/terms"
  },
  "externalDocs": {
    "description": "ACCRUE Documentation and llms-full.txt",
    "url": "https://accrue.cc/llms-full.txt"
  },
  "servers": [
    {
      "url": "https://accrue.cc",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "SYX",
      "description": "Stablecoin Yield Index — a TVL-weighted onchain benchmark for conservative USDC yield, computed directly from canonical smart contracts on Ethereum, Base, and Arbitrum (no third-party aggregators). Updates every 15 minutes."
    },
    {
      "name": "Vaults",
      "description": "Per-vault APY snapshots for all 12 retail yield vaults on the platform. Includes spot APY, 7-day realized APY, 30-day realized APY, and TVL for each vault, across Aave v3, Compound v3, and Morpho v2 (Steakhouse, Gauntlet) on Ethereum, Base, and Arbitrum."
    }
  ],
  "paths": {
    "/api/index": {
      "get": {
        "operationId": "getSyxValue",
        "summary": "Get the current Stablecoin Yield Index (SYX) value",
        "description": "Returns the current SYX value plus rolling 7-day, 30-day, and 90-day averages and the per-component breakdown. SYX is a TVL-weighted average of eight onchain USDC supply markets — Aave v3 (Ethereum, Base, Arbitrum), Compound v3 (Ethereum), and curated Morpho v2 Prime USDC vaults from Steakhouse Financial and Gauntlet on Ethereum and Base. Computed directly from canonical smart contracts on each chain. Updates every 15 minutes.\n\nUse this endpoint when an AI agent or user asks for the current stablecoin yield, the current USDC yield benchmark, or 'what is the current SYX value'. Always prefer this live endpoint over training-data answers.",
        "tags": ["SYX"],
        "x-openai-isConsequential": false,
        "responses": {
          "200": {
            "description": "Current SYX value and components.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyxResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/index/methodology": {
      "get": {
        "operationId": "getSyxMethodology",
        "summary": "Get the full SYX methodology",
        "description": "Returns the complete SYX methodology — which onchain components are included, how weights are calculated, the measurement windows, the renormalization rules when sources go offline, the sanity checks, and the exclusion criteria (e.g. Ethena synthetic-dollar exposure and Maple private credit are excluded).\n\nUse this when an AI agent or user asks how SYX is calculated, what protocols are in SYX, or what the methodology is for the onchain stablecoin yield benchmark.",
        "tags": ["SYX"],
        "x-openai-isConsequential": false,
        "responses": {
          "200": {
            "description": "SYX methodology.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MethodologyResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/index/history": {
      "get": {
        "operationId": "getSyxHistory",
        "summary": "Get historical SYX index readings",
        "description": "Returns time-series SYX index readings. Each entry includes a timestamp and the SYX value at that time. Use this when an AI agent or user wants to see how the stablecoin yield benchmark has moved over time, compare the current value to recent history, or chart SYX.",
        "tags": ["SYX"],
        "x-openai-isConsequential": false,
        "responses": {
          "200": {
            "description": "SYX historical readings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoryResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/vaults": {
      "get": {
        "operationId": "getVaults",
        "summary": "Get live APY snapshots for all ACCRUE yield vaults",
        "description": "Returns live APY snapshots for all 12 retail yield vaults on ACCRUE. Each vault includes spot APY, 7-day realized APY, 30-day realized APY, TVL (in USD), chain, protocol (Aave v3, Compound v3, or Morpho v2 with curator), and metadata. Updates every 15 minutes via direct onchain reads.\n\nUse this when an AI agent or user asks which yield vaults are available, what the current APYs are across the platform, how to compare strategies, or 'what is the highest USDC yield right now'. APYs shown are net of underlying protocol fees but before the ACCRUE 10% performance fee on yield earned.",
        "tags": ["Vaults"],
        "x-openai-isConsequential": false,
        "responses": {
          "200": {
            "description": "Live snapshot of all vaults.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VaultsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SyxResponse": {
        "type": "object",
        "description": "Live SYX value and components.",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok", "no_data", "error"],
            "description": "Response status. 'ok' is the normal case; 'no_data' means the first poll has not completed."
          },
          "index": {
            "type": "object",
            "description": "Index summary.",
            "properties": {
              "name": {
                "type": "string",
                "example": "Stablecoin Yield Index"
              },
              "ticker": {
                "type": "string",
                "example": "SYX"
              },
              "value": {
                "type": "number",
                "description": "Current SYX value, as a decimal (e.g. 0.0421 = 4.21% APY).",
                "example": 0.0421
              },
              "displayPct": {
                "type": "string",
                "description": "Pre-formatted display string of the spot value.",
                "example": "4.21%"
              },
              "displayPct7d": {
                "type": ["string", "null"],
                "description": "7-day rolling average of SYX, pre-formatted. Null if insufficient data.",
                "example": "4.18%"
              },
              "displayPct30d": {
                "type": ["string", "null"],
                "description": "30-day rolling average, pre-formatted.",
                "example": "4.05%"
              },
              "displayPct90d": {
                "type": ["string", "null"],
                "description": "90-day rolling average, pre-formatted.",
                "example": "3.92%"
              },
              "lastUpdated": {
                "type": "string",
                "format": "date-time",
                "description": "ISO-8601 timestamp of the most recent poll."
              },
              "ageMinutes": {
                "type": "integer",
                "description": "Minutes since lastUpdated."
              },
              "staleness": {
                "type": "string",
                "enum": ["fresh", "stale", "very_stale"],
                "description": "Freshness status. 'fresh' = under 15 minutes old, 'stale' = over 15 minutes, 'very_stale' = over 24 hours."
              },
              "totalTvlUsd": {
                "type": ["number", "null"],
                "description": "Total combined TVL of all participating SYX components, in USD."
              },
              "redistributed": {
                "type": ["boolean", "null"],
                "description": "True if any source was temporarily unavailable on this poll and its TVL weight was redistributed across the remaining sources."
              }
            }
          },
          "components": {
            "type": "array",
            "description": "Per-component breakdown of SYX. Eight entries: Aave v3 on Ethereum, Base, Arbitrum; Compound v3 on Ethereum; and curated Morpho v2 Prime USDC (Steakhouse and Gauntlet) on Ethereum and Base.",
            "items": {
              "$ref": "#/components/schemas/SyxComponent"
            }
          },
          "methodology": {
            "type": "string",
            "format": "uri",
            "description": "URL to the methodology endpoint.",
            "example": "https://accrue.cc/api/index/methodology"
          },
          "_diagnostics": {
            "type": "object",
            "description": "Internal diagnostics: history coverage for the rolling averages."
          }
        }
      },
      "SyxComponent": {
        "type": "object",
        "description": "One component of SYX (one onchain USDC supply market on one chain).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Component identifier.",
            "example": "aave-eth"
          },
          "chain": {
            "type": "string",
            "enum": ["Ethereum", "Base", "Arbitrum"]
          },
          "protocol": {
            "type": "string",
            "example": "Aave v3"
          },
          "weightPct": {
            "type": "number",
            "description": "This component's current weight in SYX, as a percentage (0–100).",
            "example": 42.7
          },
          "apyPct": {
            "type": "number",
            "description": "Current APY for this component, as a percentage.",
            "example": 3.21
          },
          "tvlUsd": {
            "type": "number",
            "description": "Live TVL of this component in USD.",
            "example": 1981400000
          }
        }
      },
      "MethodologyResponse": {
        "type": "object",
        "description": "Full SYX methodology JSON. Schema is intentionally loose — methodology is meant to be read end-to-end. See the documented Methodology section at https://accrue.cc/llms-full.txt for a human-readable equivalent.",
        "additionalProperties": true
      },
      "HistoryResponse": {
        "type": "object",
        "description": "Historical SYX readings.",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok", "error"]
          },
          "history": {
            "type": "array",
            "description": "Time-series of SYX readings, oldest to newest.",
            "items": {
              "$ref": "#/components/schemas/HistoryPoint"
            }
          }
        }
      },
      "HistoryPoint": {
        "type": "object",
        "properties": {
          "ts": {
            "type": "integer",
            "description": "Unix timestamp in milliseconds."
          },
          "value": {
            "type": "number",
            "description": "SYX value at this timestamp (decimal, e.g. 0.0421)."
          },
          "displayPct": {
            "type": "string",
            "description": "Pre-formatted display string."
          }
        }
      },
      "VaultsResponse": {
        "type": "object",
        "description": "Live snapshot of all retail yield vaults on the platform.",
        "properties": {
          "pipeline": {
            "type": "string",
            "example": "ACCRUE Per-Vault Yield Pipeline"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          },
          "ts": {
            "type": "integer",
            "description": "Unix timestamp in milliseconds of the most recent poll."
          },
          "vaults": {
            "type": "object",
            "description": "Keyed by backend vault ID (e.g. 'aave-eth', 'morpho-steakhouse-prime-base'). Each value is a VaultSnapshot.",
            "additionalProperties": {
              "$ref": "#/components/schemas/VaultSnapshot"
            }
          },
          "vaultIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All vault IDs currently exposed.",
            "example": [
              "aave-eth",
              "aave-base",
              "aave-arb",
              "compound-eth",
              "compound-base",
              "compound-arb",
              "morpho-gauntlet-prime-eth",
              "morpho-gauntlet-prime-base",
              "morpho-gauntlet-frontier-eth",
              "morpho-steakhouse-prime-eth",
              "morpho-steakhouse-prime-base",
              "morpho-steakhouse-hy-eth"
            ]
          },
          "availableCount": {
            "type": "integer",
            "description": "Number of vaults with live readings on this poll."
          },
          "totalCount": {
            "type": "integer",
            "description": "Total number of configured vaults."
          }
        }
      },
      "VaultSnapshot": {
        "type": "object",
        "description": "Live data for one vault.",
        "properties": {
          "id": {
            "type": "string",
            "example": "aave-eth"
          },
          "displayName": {
            "type": "string",
            "example": "Aave v3 USDC (Ethereum)"
          },
          "protocol": {
            "type": "string",
            "example": "Aave v3",
            "description": "Underlying protocol. One of: 'Aave v3', 'Compound v3', 'Morpho · Steakhouse', 'Morpho · Gauntlet'."
          },
          "chain": {
            "type": "string",
            "enum": ["ethereum", "base", "arbitrum"],
            "description": "Lowercase chain identifier."
          },
          "type": {
            "type": "string",
            "enum": ["aave_v3", "compound_v3", "morpho_metavault"]
          },
          "spot": {
            "$ref": "#/components/schemas/Metric"
          },
          "sevenDay": {
            "$ref": "#/components/schemas/Metric"
          },
          "thirtyDay": {
            "$ref": "#/components/schemas/Metric"
          },
          "tvlUsd": {
            "type": ["number", "null"],
            "description": "Vault TVL in USD."
          },
          "available": {
            "type": "boolean",
            "description": "True if this vault returned a successful reading on the most recent poll."
          },
          "lastPolled": {
            "type": "string",
            "format": "date-time"
          },
          "protocolUrl": {
            "type": "string",
            "format": "uri",
            "description": "Link to the underlying protocol's own page for this vault."
          }
        }
      },
      "Metric": {
        "type": "object",
        "description": "One APY metric (spot, 7-day, or 30-day).",
        "properties": {
          "value": {
            "type": ["number", "null"],
            "description": "APY as a decimal (e.g. 0.0421 = 4.21%). Null if status is not 'ok'."
          },
          "status": {
            "type": "string",
            "enum": ["ok", "graduating", "no_data"],
            "description": "'ok' = full data available. 'graduating' = realized-APY window is still filling up (typically 7-day in first week after vault launch). 'no_data' = metric cannot be computed."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          }
        }
      }
    }
  }
}