# 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

```bash
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