{"openapi":"3.0.3","info":{"title":"eurostablecoins.xyz v1 API","version":"v1","description":"Free, keyless, CORS-enabled REST API for EUR stablecoin supply, peg, activity, holders, and DEX market data.\n\nNo authentication required. All endpoints return JSON.\n\nCache-Control: s-maxage=60, stale-while-revalidate=300 (most endpoints).\nCache-Control: s-maxage=3600, stale-while-revalidate=7200 (/api/v1 root and /api/v1/markets/dex).\n\nData is not real-time. Collection cadences:\n- Supply: every 4 hours\n- Peg: every 6 hours (tracked coins only)\n- Activity: hourly at :30 UTC (including 08:30 UTC)\n- Holders: daily at 10:00 UTC\n- CEX markets: daily at 06:00 UTC (CCXT direct exchange feeds)\n- DEX markets: every 6 hours\n\nAttribution requested (CC BY 4.0): \"Data from eurostablecoins.xyz\".\nSee https://www.eurostablecoins.xyz/docs for full documentation.","contact":{"url":"https://www.eurostablecoins.xyz/docs"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://www.eurostablecoins.xyz/api/v1","description":"Production"}],"tags":[{"name":"meta","description":"API index and coin registry"},{"name":"supply","description":"Token supply data (total, circulating, per-chain)"},{"name":"peg","description":"EUR peg metrics and history"},{"name":"activity","description":"Mint/burn and transfer volume history"},{"name":"holders","description":"Holder count snapshots"},{"name":"markets","description":"DEX market data"}],"paths":{"/":{"get":{"tags":["meta"],"summary":"API index","description":"Returns base info, all endpoint paths, valid coin IDs, period values, and collection cadence.","operationId":"getApiRoot","responses":{"200":{"description":"API index object","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/overview":{"get":{"tags":["meta"],"summary":"Aggregated market overview","description":"Total EUR supply, MiCA breakdown, HHI concentration index, dominant coin, per-coin summary.","operationId":"getOverview","responses":{"200":{"description":"Market overview object","content":{"application/json":{"schema":{"type":"object","properties":{"coin_count":{"type":"integer"},"total_circulating_eur":{"type":"number"},"mica_licensed_count":{"type":"integer"},"mica_breakdown":{"type":"object"},"dominant":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"share":{"type":"number"},"note":{"type":"string"}}},"hhi_concentration":{"type":"number"},"coins":{"type":"array","items":{"type":"object"}},"data_as_of":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the most recent supply snapshot in this response"},"source":{"type":"string"}}}}}}}}},"/coins":{"get":{"tags":["meta"],"summary":"All tracked coins","description":"Registry index — all active tracked coins with metadata and latest supply state.","operationId":"getCoins","responses":{"200":{"description":"Coins list","content":{"application/json":{"schema":{"type":"object","properties":{"coin_count":{"type":"integer"},"coins":{"type":"array","items":{"type":"object"}},"timestamp":{"type":"string"},"source":{"type":"string"}}}}}}}}},"/coins/{id}":{"get":{"tags":["meta"],"summary":"Single coin registry entry","description":"Metadata, chain list, and latest supply snapshot for one coin.","operationId":"getCoin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"Coin registry entry","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/supply":{"get":{"tags":["supply"],"summary":"Latest supply for all coins","operationId":"getSupply","responses":{"200":{"description":"Supply snapshot for all coins","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/supply/{id}":{"get":{"tags":["supply"],"summary":"Latest supply for one coin","operationId":"getCoinSupply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"Supply snapshot","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/supply/{id}/{chain}":{"get":{"tags":["supply"],"summary":"Latest supply for one coin on one chain","operationId":"getCoinChainSupply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"chain","in":"path","required":true,"schema":{"type":"string"},"description":"Chain key (e.g. ethereum, polygon, solana). Must be a chain on which this coin is deployed."}],"responses":{"200":{"description":"Supply snapshot for (coin, chain) pair","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown coin_id or chain not deployed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/supply/{id}":{"get":{"tags":["supply"],"summary":"Daily supply history for one coin","operationId":"getCoinSupplyHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","90d","6m","12m","1y","2y","all","max"],"default":"30d"},"description":"Time window for history endpoints. Default: 30d."},{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Custom start date (YYYY-MM-DD). Alternative to period."},{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Custom end date (YYYY-MM-DD). Used with start. Default: today."}],"responses":{"200":{"description":"Daily supply series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}}}},"400":{"description":"Invalid period or date parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/supply/{id}/{chain}":{"get":{"tags":["supply"],"summary":"Daily supply history for one coin on one chain","operationId":"getCoinChainSupplyHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"chain","in":"path","required":true,"schema":{"type":"string"},"description":"Chain key (e.g. ethereum, polygon, solana). Must be a chain on which this coin is deployed."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","90d","6m","12m","1y","2y","all","max"],"default":"30d"},"description":"Time window for history endpoints. Default: 30d."}],"responses":{"200":{"description":"Daily supply series for one chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}}}},"404":{"description":"Unknown coin_id or chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/peg":{"get":{"tags":["peg"],"summary":"Latest peg metrics for all tracked coins","description":"Only coins with a tracked public price source are included.","operationId":"getPeg","responses":{"200":{"description":"Peg metrics for all coins with a price source","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/peg/{id}":{"get":{"tags":["peg"],"summary":"Latest peg metrics for one coin","operationId":"getCoinPeg","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"Peg metrics object","content":{"application/json":{"schema":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"current_price_eur":{"type":"number"},"deviation_bps":{"type":"number"},"avg_deviation_bps_7d":{"type":"number"},"avg_deviation_bps_30d":{"type":"number"},"max_deviation_bps_7d":{"type":"number"},"max_deviation_bps_30d":{"type":"number"},"time_in_band_10bps_30d":{"type":"integer"},"time_in_band_50bps_30d":{"type":"integer"},"depeg_events_30d":{"type":"integer"},"peg_score_100":{"type":"number"},"price_source":{"type":"string"},"date":{"type":"string","format":"date"},"source":{"type":"string"}}}}}},"404":{"description":"Unknown coin_id or no price source for this coin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/peg/{id}":{"get":{"tags":["peg"],"summary":"Daily peg history for one coin","operationId":"getCoinPegHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","90d","6m","12m","1y","2y","all","max"],"default":"30d"},"description":"Time window for history endpoints. Default: 30d."}],"responses":{"200":{"description":"Daily peg series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}}}},"404":{"description":"Unknown coin_id or no price source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/mint-burn/{id}":{"get":{"tags":["activity"],"summary":"Daily mint and burn history","operationId":"getCoinMintBurnHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","90d","6m","12m","1y","2y","all","max"],"default":"30d"},"description":"Time window for history endpoints. Default: 30d."}],"responses":{"200":{"description":"Daily mint/burn series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transfer-volume":{"get":{"tags":["activity"],"summary":"Peer transfer volume for all tracked coins","operationId":"getMarketTransferVolume","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","6m","12m","all"],"default":"30d"},"description":"Rolling complete-UTC-day window for transfer volume."}],"responses":{"200":{"description":"Market total, daily series, per-coin totals, coverage and quality metadata"}}}},"/transfer-volume/{id}":{"get":{"tags":["activity"],"summary":"Peer transfer-volume summary for one coin","operationId":"getCoinTransferVolume","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","6m","12m","all"],"default":"30d"},"description":"Rolling complete-UTC-day window for transfer volume."}],"responses":{"200":{"description":"Period total, daily average, daily series, coverage and quality metadata"},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history/transfer-volume/{id}":{"get":{"tags":["activity"],"summary":"Daily transfer volume history","operationId":"getCoinTransferHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","14d","30d","3m","6m","12m","all"],"default":"30d"},"description":"Rolling complete-UTC-day window for transfer volume."}],"responses":{"200":{"description":"Daily transfer series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryResponse"}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/holders/{id}":{"get":{"tags":["holders"],"summary":"Latest holder count snapshot","description":"Point-in-time unique address count with a positive balance, summed across all chains. No historical series.","operationId":"getCoinHolders","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"Holder snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"total_holders":{"type":"integer"},"active_holders_30d":{"type":"integer","nullable":true,"description":"Always null — deprecated"},"chain_breakdown":{"type":"object"},"source":{"type":"string"},"recorded_at":{"type":"string","format":"date-time"},"note":{"type":"string"}}}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets":{"get":{"tags":["markets"],"summary":"Markets overview","description":"Top-level summary of CEX and DEX market coverage — counts, timestamps, cadence notes, and endpoint paths.","operationId":"getMarkets","responses":{"200":{"description":"Markets overview","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"endpoints":{"type":"object"},"cex":{"type":"object"},"dex":{"type":"object"}}}}}}}}},"/markets/cex":{"get":{"tags":["markets"],"summary":"All direct CEX market data","description":"Direct CCXT exchange-API data for all tracked coins. Collected daily at 06:00 UTC. Prices and volumes are in the pair's native quote currency.","operationId":"getMarketsCex","responses":{"200":{"description":"CEX markets for all coins","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"fallback_used":{"type":"boolean"},"source":{"type":"string"},"note":{"type":"string"},"pairs_count":{"type":"integer"},"coins_covered":{"type":"integer"},"markets":{"type":"array","items":{"$ref":"#/components/schemas/CexMarket"}}}}}}}}}},"/markets/cex/{id}":{"get":{"tags":["markets"],"summary":"Direct CEX market data for one coin","description":"Returns an empty markets array (with note) when the coin has no CEX coverage.","operationId":"getMarketsCexCoin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"CEX markets for one coin","content":{"application/json":{"schema":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"fallback_used":{"type":"boolean"},"source":{"type":"string"},"markets_count":{"type":"integer"},"markets":{"type":"array","items":{"$ref":"#/components/schemas/CexMarket"}},"note":{"type":"string","nullable":true}}}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets/dex":{"get":{"tags":["markets"],"summary":"Latest DEX pool snapshots","description":"Price, liquidity, 24h volume, and tx counts for all tracked EUR stablecoin DEX pairs. Collected every 6 hours.","operationId":"getMarketsDex","responses":{"200":{"description":"DEX pool snapshots","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"type":"string"}},"fallback_live_fetch":{"type":"boolean"},"pairs_count":{"type":"integer"},"coins_covered":{"type":"integer"},"chains_covered":{"type":"integer"},"pairs":{"type":"array","items":{"$ref":"#/components/schemas/DexPair"}}}}}}}}}},"/markets/dex/{id}":{"get":{"tags":["markets"],"summary":"DEX pool data for one coin","description":"Returns an empty pairs array (with note) when the coin has no DEX coverage.","operationId":"getMarketsDexCoin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"DEX pools for one coin","content":{"application/json":{"schema":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"sources":{"type":"array","items":{"type":"string"}},"fallback_live_fetch":{"type":"boolean"},"pairs_count":{"type":"integer"},"pairs":{"type":"array","items":{"$ref":"#/components/schemas/DexPair"}},"note":{"type":"string","nullable":true}}}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets/{id}":{"get":{"tags":["markets"],"summary":"Combined CEX + DEX market data for one coin","description":"Returns both cex and dex market data in a single response. Each key is always present; inner arrays are empty when no coverage exists.","operationId":"getMarketsCoin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["aeur","deuro","eur0","eura","eurau","eurc","eurcv","eure","euri","eurm","eurod","euroe","europ","eurq","eurr","eurs","eurt","heuro"]},"description":"Coin identifier. Valid values are listed in /api/v1 under valid_coin_ids."}],"responses":{"200":{"description":"Combined markets for one coin","content":{"application/json":{"schema":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"cex":{"type":"object"},"dex":{"type":"object"}}}}}},"404":{"description":"Unknown coin_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error message"}}},"HistoryResponse":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"period":{"type":"string"},"points":{"type":"integer"},"earliest":{"type":"string","format":"date"},"latest":{"type":"string","format":"date"},"series":{"type":"array","items":{"type":"object"}},"source":{"type":"string"}}},"CexMarket":{"type":"object","properties":{"coin_id":{"type":"string"},"exchange_id":{"type":"string"},"exchange_name":{"type":"string"},"symbol":{"type":"string"},"base":{"type":"string"},"quote":{"type":"string"},"last":{"type":"number","nullable":true},"bid":{"type":"number","nullable":true},"ask":{"type":"number","nullable":true},"spread_bps":{"type":"number","nullable":true},"base_volume_24h":{"type":"number","nullable":true},"quote_volume_24h":{"type":"number","nullable":true},"source_type":{"type":"string"},"stale":{"type":"boolean"},"fetched_at":{"type":"string","format":"date-time"}}},"DexPair":{"type":"object","properties":{"coin_id":{"type":"string"},"ticker":{"type":"string"},"chain":{"type":"string"},"dex_id":{"type":"string"},"dex_label":{"type":"string"},"pair_label":{"type":"string"},"pool_address":{"type":"string"},"price_usd":{"type":"number","nullable":true},"liquidity_usd":{"type":"number","nullable":true},"volume_24h_usd":{"type":"number","nullable":true},"txns_24h":{"type":"integer","nullable":true},"pool_class":{"type":"string","nullable":true},"source":{"type":"string"},"source_url":{"type":"string","nullable":true},"warning_flags":{"type":"array","items":{"type":"string"}}}}}}}