Help & API Guide
Complete English reference for Datasourceforcryptocurrency-2 (primary Space) and v4 complement. Copy any example and run it — no setup beyond this URL.
API Base:
| Swagger UI
| API Explorer
| Extended legacy guide
| Pages catalog API
1. Quick Start (3 steps)
Every example uses your current origin. Replace BASE if you call from another app.
const BASE = window.location.origin; // e.g. https://really-amin-datasourceforcryptocurrency-2.hf.space
// Step 1 — Is the server alive?
const health = await fetch(`${BASE}/health`).then(r => r.json());
console.log(health.status); // "healthy"
// Step 2 — Dashboard numbers (cards on home page)
const dash = await fetch(`${BASE}/api/dashboard/overview`).then(r => r.json());
console.log(dash.cards);
// Step 3 — Analyze one sentence
const sentiment = await fetch(`${BASE}/api/sentiment`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text: 'Bitcoin looks bullish today' })
}).then(r => r.json());
console.log(sentiment.sentiment, sentiment.confidence);
Python: use requests.get(BASE + "/health") the same way. Always set timeout=30 on HF Spaces.
2. Discovery & Health
Find every endpoint before you integrate.
| Method | Path | What you get |
|---|---|---|
| GET | /health | Simple alive check (also /api/health) |
| GET | /api/status | Provider connectivity probe |
| GET | /api/system/status | Full system drawer data (pools, models, keys) |
| GET | /api/endpoints | Grouped list of all routes |
| GET | /api/routers | Which routers are loaded |
| GET | /api/uptime/probe | Probe 12 critical endpoints |
| GET | /docs | Interactive Swagger UI |
curl "%BASE%/api/endpoints"
curl "%BASE%/api/routers"
3. Dashboard API
The home dashboard reads one endpoint for all hero cards.
| Method | Path | Response highlights |
|---|---|---|
| GET | /api/dashboard/overview | cards: resources, API keys, models v2+v4, rotation pools |
| GET | /api/resources/summary | Registry totals and categories |
| GET | /api/models/summary | Models by category + v4 complement block |
const overview = await fetch(`${BASE}/api/dashboard/overview`).then(r => r.json());
// cards.total_resources, cards.api_keys_env, cards.api_keys_file
// cards.models_loaded_v2, cards.models_loaded_v4, cards.pools_healthy
4. Market Data
Prices, top coins, OHLCV. Automatic fallback: local → Binance → v4 complement → cache.
| Method | Path | Parameters |
|---|---|---|
| GET | /api/market?limit=50 | Top market rows for dashboard table |
| GET | /api/coins/top?limit=50 | Top coins by market cap |
| GET | /api/trending | Trending coins |
| GET | /api/ohlcv?symbol=BTC&timeframe=1h&limit=100 | Candles for charts |
| GET | /api/klines?symbol=BTCUSDT&interval=1h&limit=100 | Binance-style alias |
| GET | /api/market/gainers?limit=20 | Top gainers (with fallbacks) |
| GET | /api/market/losers?limit=20 | Top losers |
// Market table data
const market = await fetch(`${BASE}/api/market?limit=20`).then(r => r.json());
// OHLCV for TradingView-style charts
const ohlcv = await fetch(`${BASE}/api/ohlcv?symbol=BTC&timeframe=1h&limit=200`).then(r => r.json());
5. Sentiment & Fear/Greed
| Method | Path | Body / notes |
|---|---|---|
| GET | /api/fear-greed?limit=30 | Fear & Greed index + history |
| GET | /api/sentiment/global | Global market mood |
| GET | /api/sentiment/asset/BTC | Per-asset sentiment |
| POST | /api/sentiment | {"text":"..."} — v2 then v4 fallback |
| POST | /api/sentiment/analyze | {"text":"...","mode":"crypto"} |
| POST | /api/hf/run-sentiment | {"texts":["sentence 1"]} — must be array |
// Fear & Greed (dashboard chart)
const fng = await fetch(`${BASE}/api/fear-greed?limit=30`).then(r => r.json());
// Text sentiment
const result = await fetch(`${BASE}/api/sentiment`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ text: 'ETH breaking resistance, very bullish' })
}).then(r => r.json());
6. AI Models (Hugging Face)
v2 loads models locally when possible. v4 complement adds more models via Inference API when v2 is exhausted.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/models/summary | Best for UI — categories + v4 block |
| GET | /api/models/status | Registry status, models_loaded |
| GET | /api/models/list | Full catalog |
| GET | /api/models/health | Per-model health entries |
| GET | /api/hf/models | Alias → models list |
| GET | /api/hf/health | HF connectivity check |
| POST | /api/models/reinitialize | Warm models again |
| POST | /api/ai/decision | {"symbol":"BTC","horizon":"swing"} |
const summary = await fetch(`${BASE}/api/models/summary`).then(r => r.json());
console.log('v2 loaded:', summary.summary?.loaded_models);
console.log('v4 loaded:', summary.complement_v4?.loaded);
// HF sentiment batch (texts must be an array)
await fetch(`${BASE}/api/hf/run-sentiment`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ texts: ['BTC pump incoming'] })
});
Set Space secret HF_TOKEN and variable HF_MODE=auth for gated models. v4 Space uses Inference API when local torch is unavailable.
7. API Keys, Resources & Rotation
Keys come from HF Secrets (env) plus inline keys in config/api_keys.json. Rotation uses api-resources/crypto_resources_unified_2025-11-11.json (10 pools).
Recommended Space secrets
CRYPTOCOMPARE_API_KEY,COINMARKETCAP_KEY_1,COINMARKETCAP_KEY_2ETHERSCAN_KEY_1,ETHERSCAN_KEY_2,BSCSCAN_API_KEY,TRONSCAN_API_KEYNEWSAPI_KEY,HF_TOKEN,COINGECKO_API_KEY(optional)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/resources/rotation/health | 10 pools + env key probe |
| GET | /api/resources/rotation | Full rotation status |
| GET | /api/resources/fallback-chains | Failover chain JSON |
| GET | /api/resources/summary | Registry + key counts |
| GET | /api/providers | Named provider list |
| GET | /api/complement/v4/status | v4 Space health |
const rotation = await fetch(`${BASE}/api/resources/rotation/health`).then(r => r.json());
console.log(rotation.pools_healthy, '/', rotation.pools_total);
console.log('Env keys:', rotation.env_keys?.configured);
8. News
| Method | Path | Notes |
|---|---|---|
| GET | /api/news/latest?limit=20 | Latest crypto news |
| GET | /api/news?limit=20 | Alias |
const news = await fetch(`${BASE}/api/news/latest?limit=10`).then(r => r.json());
(news.articles || news.news || []).forEach(a => console.log(a.title));
9. Indicators & Technical Analysis
| Method | Path | Notes |
|---|---|---|
| GET | /api/indicators/services | List indicator services |
| GET | /api/indicators/rsi?symbol=BTC&timeframe=1h | RSI |
| GET | /api/indicators/macd?symbol=BTC&timeframe=1h | MACD |
| GET | /api/indicators/comprehensive?symbol=BTC | Multi-indicator bundle |
| POST | /api/technical/ta-quick | Body: symbol, timeframe, ohlcv array |
| POST | /api/technical/comprehensive | Combined TA + FA + on-chain |
const ohlcv = await fetch(`${BASE}/api/ohlcv?symbol=BTC&timeframe=4h&limit=200`).then(r => r.json());
const ta = await fetch(`${BASE}/api/technical/ta-quick`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ symbol: 'BTC', timeframe: '4h', ohlcv: ohlcv.data })
}).then(r => r.json());
10. v4 Complement Space
Secondary Space: https://really-amin-datasourceforcryptocurrency-4.hf.space. v2 calls it when local providers or models are exhausted.
- v2
POST /api/sentiment→ local model → v4 → lexical fallback - v2
/api/models/summaryincludescomplement_v4counts - v4 runs HF Inference API with
HF_MODE=authwhen torch is unavailable
const v4 = await fetch(`${BASE}/api/complement/v4/status`).then(r => r.json());
console.log(v4.probe); // endpoints_ok, healthy
11. Errors & Tips
- 404 on route — Check
/api/endpointsor/docs; path may differ from old docs. - 503 on market — CoinGecko rate limit; retry or use
/api/market(Binance fallback). - 422 on sentiment —
/api/hf/run-sentimentrequires{"texts":["..."]}(array), not a single string. - Empty models — Call
POST /api/models/reinitializeor wait for lazy load; checkHF_TOKEN. - Space sleeping — First request may take 30–60s; increase client timeout.
- Hard refresh UI —
Ctrl+Shift+Rafter deploys.
Diagnostic checklist
curl "%BASE%/health"
curl "%BASE%/api/dashboard/overview"
curl "%BASE%/api/resources/rotation/health"
curl "%BASE%/api/models/summary"
HTTP only required. WebSocket endpoints are optional; the dashboard polls REST every 30 seconds. For interactive testing, open /docs or click the green ? floating button on the dashboard.