{"openapi":"3.1.0","servers":[{"url":"https://api.spark.fi","description":"Production"}],"info":{"title":"Spark Savings Data API","version":"0.0.1","description":"Read-only API exposing current and historic savings data for Spark and Sky **Savings Vaults V2** — ERC-4626 yield-bearing vaults that accrue a continuous savings rate.\n\nOnly a limited set of vaults is currently exposed. Each is addressed by `protocol`, `chain`, and underlying `token`:\n\n| Protocol | Chain | Token | Vault |\n| --- | --- | --- | --- |\n| spark | mainnet | usdc | spUSDC |\n| spark | mainnet | usdt | spUSDT |\n| sky | mainnet | usdt | sUSDT |\n\n**Data freshness.** On-chain metrics (`apy`, `tvl`, `depositCap`) reflect the latest block. Analytics-derived fields (`users`, `liquidity`, `collateralComposition`) may lag on-chain state by roughly 5–10 minutes.\n\nThe machine-readable OpenAPI specification for this API is available at [https://api.spark.fi/openapi.json](https://api.spark.fi/openapi.json).\n\nSee the [Spark Vaults Smart Contracts integration guide](/integrators/spark-vaults-v2) for more details."},"components":{"schemas":{"VaultTokenInfo":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address (checksummed).","example":"0x28B3a8fb53B741A8Fd78c0fb9A6B2393d896a43d"},"decimals":{"type":"integer","minimum":0,"description":"Number of decimals the token uses.","example":6},"symbol":{"type":"string","description":"Token symbol.","example":"spUSDC"},"name":{"type":"string","description":"Token name.","example":"Spark USDC"}},"required":["address","decimals","symbol","name"],"description":"The savings vault share token (e.g. `spUSDC`) that depositors receive."},"AssetTokenInfo":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address (checksummed).","example":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"},"decimals":{"type":"integer","minimum":0,"description":"Number of decimals the token uses.","example":6},"symbol":{"type":"string","description":"Token symbol.","example":"USDC"},"name":{"type":"string","description":"Token name.","example":"USD Coin"}},"required":["address","decimals","symbol","name"],"description":"The underlying token (e.g. `USDC`) deposited into the vault."},"LiquidityEntry":{"type":"object","properties":{"protocol":{"type":"string","description":"Liquidity source the funds are deployed to (e.g. `psm`, `morpho`, `sparklend`).","example":"psm"},"value":{"type":"string","description":"Amount available at this source, in units of the underlying asset (decimal string).","example":"3849983274.646926"}},"required":["protocol","value"]},"CollateralEntry":{"type":"object","properties":{"category":{"type":"string","description":"Collateral category label (e.g. `Stablecoins`, `AAA Corporate Debt`, `Idle`).","example":"Stablecoins"},"value":{"type":"string","description":"Estimated value backing the savings in this category, in units of the underlying asset (decimal string).","example":"195743150.920491"}},"required":["category","value"]},"SavingsResponse":{"type":"object","properties":{"vault":{"$ref":"#/components/schemas/VaultTokenInfo"},"asset":{"$ref":"#/components/schemas/AssetTokenInfo"},"apy":{"type":"string","description":"Current annual percentage yield as a decimal fraction (e.g. `0.0365` = 3.65%).","example":"0.0365"},"tvl":{"type":"string","description":"Total value locked, in units of the underlying asset (decimal string).","example":"403886846.850673"},"users":{"type":"number","description":"Number of unique depositors. May lag on-chain state by ~5–10 minutes.","example":1111},"depositCap":{"type":"string","description":"Maximum total deposits allowed, in units of the underlying asset (decimal string).","example":"2000000000"},"liquidity":{"type":"array","items":{"$ref":"#/components/schemas/LiquidityEntry"},"description":"Available liquidity broken down by the source it is deployed to. May lag on-chain state by ~5–10 minutes."},"collateralComposition":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/CollateralEntry"}},"description":"Breakdown of the collateral backing the savings, keyed by token symbol (e.g. `usds`, `usdc`). Each entry is the estimated value held in a given collateral category. May lag on-chain state by ~5–10 minutes.","example":{"usds":[{"category":"Stablecoins","value":"195743150.920491"},{"category":"Onchain Crypto Lending","value":"68567180.437736"},{"category":"Short Duration Treasury Bills","value":"66092816.698696"},{"category":"AAA Corporate Debt","value":"18079571.770374"}],"usdc":[{"category":"Idle","value":"9999969.995893"}]}}},"required":["vault","asset","apy","tvl","users","depositCap","liquidity","collateralComposition"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable error code.","example":"not_found"}},"required":["error"]},"HistoricSavingsEntry":{"type":"object","properties":{"date":{"type":"string","description":"Date of the data point (ISO-8601, UTC midnight).","example":"2026-05-21T00:00:00.000Z"},"apy":{"type":"string","description":"Annual percentage yield on this date as a decimal fraction.","example":"0.0365"},"tvl":{"type":"string","description":"Total value locked on this date, in units of the underlying asset (decimal string).","example":"403885794.520300"}},"required":["date","apy","tvl"]}},"parameters":{}},"paths":{"/v1/savings/{protocol}/{chain}/{token}":{"get":{"operationId":"getCurrentSavings","tags":["Savings"],"summary":"Get current savings data","description":"Returns the current APY, TVL, deposit cap, liquidity, and collateral composition for a savings vault, along with the vault share token and underlying asset token details (address, decimals, symbol, name).","parameters":[{"schema":{"type":"string","description":"Savings protocol. Supported: `spark`, `sky` (case-insensitive).","example":"spark"},"required":true,"name":"protocol","in":"path"},{"schema":{"type":"string","description":"Chain name. Supported: `mainnet` (case-insensitive).","example":"mainnet"},"required":true,"name":"chain","in":"path"},{"schema":{"type":"string","description":"Underlying asset symbol. Supported: `usdc`, `usdt` (case-insensitive). Not every protocol/chain/token combination exists — see the API description for the available vaults.","example":"usdc"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Current savings data for the requested vault.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SavingsResponse"}},"required":["data"]}}}},"404":{"description":"No savings vault matches the given protocol/chain/token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error"}}}}}}},"/v1/savings/{protocol}/{chain}/{token}/historic":{"get":{"operationId":"getHistoricSavings","tags":["Savings"],"summary":"Get historic savings data","description":"Returns the historic daily APY and TVL series for a savings vault.","parameters":[{"schema":{"type":"string","description":"Savings protocol. Supported: `spark`, `sky` (case-insensitive).","example":"spark"},"required":true,"name":"protocol","in":"path"},{"schema":{"type":"string","description":"Chain name. Supported: `mainnet` (case-insensitive).","example":"mainnet"},"required":true,"name":"chain","in":"path"},{"schema":{"type":"string","description":"Underlying asset symbol. Supported: `usdc`, `usdt` (case-insensitive). Not every protocol/chain/token combination exists — see the API description for the available vaults.","example":"usdc"},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Historic savings series for the requested vault.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoricSavingsEntry"}}},"required":["data"]}}}},"404":{"description":"No savings vault matches the given protocol/chain/token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"internal_error"}}}}}}}}}