api-resources/README.md

API Resources — Datasourceforcryptocurrency-2

Canonical data-source registry for the v2 Hugging Face Space.

Files

File	Role
crypto_resources_unified_2025-11-11.json	Primary reference — structured registry (~274 external + local routes), rotation pools
ultimate_crypto_pipeline_2025_NZasinich.json	Supplement — 55 curated sources with rate limits, TypeScript examples, free-tier notes
fallback_chains.json	Hierarchical failover — ordered provider chains per data type (market, news, sentiment, explorers)

Architecture

Request
  → local v2 endpoint (priority 0)
  → rotation pool from unified registry (priority / round_robin / weighted)
  → fallback_chains.json ordered chain (on 429 / 5xx / timeout)
  → v4 complement Space (only if v2 chain exhausted)
  → never return empty — cached stale data as last resort

Registry choice

• Primary: crypto_resources_unified_2025-11-11.json — machine-readable schema, section keys match resource_rotation_bridge.py, env key resolution via HF secrets.
• Supplement: ultimate_crypto_pipeline_2025_NZasinich.json — human-friendly examples; merged into unified when URLs are unique. Fixed: stray filename line removed so JSON parses cleanly.

API keys

Never hardcode keys in registry JSON. Use HF Space secrets:

• CRYPTOCOMPARE_API_KEY, COINMARKETCAP_KEY_1/2, ETHERSCAN_KEY_1/2
• BSCSCAN_API_KEY, TRONSCAN_API_KEY, NEWSAPI_KEY, HF_TOKEN, COINGECKO_API_KEY

See config/api_keys.json for the full mapping.

Regenerate merged registry

python patches/datasource-v2/scripts/merge_api_registries.py

Endpoints

• GET /api/resources/rotation — pool plan + runtime stats
• GET /api/resources/rotation/health — pool availability
• GET /api/resources/fallback-chains — all chain names
• GET /api/resources/fallback-chains?data_type=market_price — single chain