| { | |
| "success": true, | |
| "schema_version": "2.0", | |
| "language": "en", | |
| "title": "Crypto Datasource API — AI Agent Help Guide", | |
| "summary": "Machine-readable guide for LLMs and simple AI agents. Use intent_map to map natural-language questions to HTTP endpoints. All market data is REAL from exchanges — never synthetic.", | |
| "base_url": "https://really-amin-datasourceforcryptocurrency-1.hf.space", | |
| "base_url_placeholder": "{BASE}", | |
| "for_ai_agents": { | |
| "read_this_first": "You are calling a cryptocurrency datasource API on Hugging Face Spaces. Always replace {BASE} with the deployment URL (e.g. https://really-amin-datasourceforcryptocurrency-1.hf.space). Start with GET {BASE}/api/max/help if you are unsure which endpoint to use.", | |
| "query_algorithm": [ | |
| "1. Read the user question and extract keywords (symbol, data type: price/ohlcv/futures/news/sentiment/indicators).", | |
| "2. Search intent_map[] for matching keywords or user_wants text (case-insensitive).", | |
| "3. Pick the best intent id. Build URL: {BASE} + path with path_params substituted.", | |
| "4. Add query_params to the URL. Use GET unless method is POST.", | |
| "5. For POST endpoints, send Content-Type: application/json and use body_json from the intent.", | |
| "6. If no intent matches, call GET {BASE}/api/max/app/symbol/{SYMBOL} for a combined answer.", | |
| "7. Set HTTP timeout to at least 30 seconds (HF Spaces cold start can take 60s).", | |
| "8. Check response field data_state: REAL means live data, UNAVAILABLE means all providers failed." | |
| ], | |
| "recommended_entrypoints": { | |
| "simplest_health": "GET /api/max/health", | |
| "best_single_symbol": "GET /api/max/app/symbol/BTC", | |
| "best_futures": "GET /api/futures/market/snapshot/BTC", | |
| "best_indicators": "GET /api/max/indicators/comprehensive?symbol=BTC&timeframe=1h", | |
| "best_news": "GET /api/max/news?q=bitcoin&limit=10", | |
| "best_sentiment": "GET /api/max/social/sentiment?coin=BTC", | |
| "full_endpoint_list": "GET /api/max/endpoints/catalog" | |
| }, | |
| "symbol_rules": { | |
| "spot_price_path": "Use base asset: BTC, ETH, SOL (not BTCUSDT required on /api/max/market/price/{symbol})", | |
| "ohlcv_path": "Accepts BTC or BTCUSDT on /api/max/trading/ohlcv/{symbol}", | |
| "futures_path": "Use base asset BTC on /api/futures/market/* — server maps to XBTUSDTM on KuCoin" | |
| }, | |
| "response_fields": { | |
| "success": "boolean — request completed without server error", | |
| "data_state": "REAL | CACHED_DB | UNAVAILABLE — never treat UNAVAILABLE as real market data", | |
| "provider": "which exchange/source returned the data", | |
| "attempts": "list of tried providers when fallback was used" | |
| } | |
| }, | |
| "intent_map": [ | |
| { | |
| "id": "health_check", | |
| "user_wants": "Check if the API server is alive", | |
| "keywords": [ | |
| "health", | |
| "alive", | |
| "ping", | |
| "status", | |
| "up" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/health", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "success, status, resource_registry, cache", | |
| "example_url": "{BASE}/api/max/health" | |
| }, | |
| { | |
| "id": "list_all_endpoints", | |
| "user_wants": "List every API endpoint grouped by category", | |
| "keywords": [ | |
| "catalog", | |
| "endpoints", | |
| "list apis", | |
| "discovery", | |
| "openapi" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/endpoints/catalog", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "groups, endpoints[], swagger link", | |
| "example_url": "{BASE}/api/max/endpoints/catalog" | |
| }, | |
| { | |
| "id": "full_help_json", | |
| "user_wants": "Download the complete machine-readable help document", | |
| "keywords": [ | |
| "help", | |
| "documentation", | |
| "guide", | |
| "ai agent", | |
| "llm" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/help", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "This entire document as JSON", | |
| "example_url": "{BASE}/api/max/help" | |
| }, | |
| { | |
| "id": "app_startup_bundle", | |
| "user_wants": "One call to bootstrap a trading app at startup", | |
| "keywords": [ | |
| "bootstrap", | |
| "startup", | |
| "init", | |
| "main app", | |
| "short hunter" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/app/bootstrap", | |
| "query_params": { | |
| "symbols": "BTC,ETH,SOL" | |
| }, | |
| "path_params": {}, | |
| "returns": "providers, market snapshot, sentiment, fallback plan, capabilities", | |
| "example_url": "{BASE}/api/max/app/bootstrap?symbols=BTC,ETH,SOL" | |
| }, | |
| { | |
| "id": "one_symbol_everything", | |
| "user_wants": "Get ALL data for one coin in a single request (best for main apps)", | |
| "keywords": [ | |
| "symbol bundle", | |
| "btc data", | |
| "everything for eth", | |
| "combined", | |
| "one symbol" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/app/symbol/{symbol}", | |
| "query_params": {}, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "price, ohlcv, orderbook, futures_market, futures_validation, sentiment, news, indicators", | |
| "example_url": "{BASE}/api/max/app/symbol/BTC" | |
| }, | |
| { | |
| "id": "multi_symbol_scanner", | |
| "user_wants": "Feed multiple symbols for a scanner or watchlist", | |
| "keywords": [ | |
| "universe", | |
| "scanner", | |
| "multiple symbols", | |
| "watchlist feed" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/app/universe", | |
| "query_params": { | |
| "symbols": "BTC,ETH,SOL" | |
| }, | |
| "path_params": {}, | |
| "returns": "items[] per symbol with price and analysis helper", | |
| "example_url": "{BASE}/api/max/app/universe?symbols=BTC,ETH,SOL" | |
| }, | |
| { | |
| "id": "spot_price", | |
| "user_wants": "Get current spot price for a cryptocurrency", | |
| "keywords": [ | |
| "price", | |
| "spot", | |
| "btc price", | |
| "eth price", | |
| "ticker" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/market/price/{symbol}", | |
| "query_params": {}, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "price, source, data_state REAL|UNAVAILABLE, fallback attempts", | |
| "example_url": "{BASE}/api/max/market/price/BTC" | |
| }, | |
| { | |
| "id": "spot_prices_multi", | |
| "user_wants": "Get prices for several coins at once", | |
| "keywords": [ | |
| "snapshot", | |
| "multiple prices", | |
| "market snapshot" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/market/snapshot", | |
| "query_params": { | |
| "symbols": "BTC,ETH,SOL" | |
| }, | |
| "path_params": {}, | |
| "returns": "items[] with price per symbol", | |
| "example_url": "{BASE}/api/max/market/snapshot?symbols=BTC,ETH,SOL" | |
| }, | |
| { | |
| "id": "spot_ohlcv", | |
| "user_wants": "Get spot candlestick OHLCV data for charts", | |
| "keywords": [ | |
| "ohlcv", | |
| "candles", | |
| "klines", | |
| "chart", | |
| "historical spot" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/trading/ohlcv/{symbol}", | |
| "query_params": { | |
| "interval": "1h", | |
| "limit": "100" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "candles[{time,open,high,low,close,volume}], source binance_spot|kucoin_spot|...", | |
| "example_url": "{BASE}/api/max/trading/ohlcv/BTC?interval=1h&limit=100" | |
| }, | |
| { | |
| "id": "orderbook", | |
| "user_wants": "Get live order book bids and asks", | |
| "keywords": [ | |
| "orderbook", | |
| "order book", | |
| "bids", | |
| "asks", | |
| "depth" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/trading/orderbook/{symbol}", | |
| "query_params": { | |
| "limit": "50" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "bids, asks, source", | |
| "example_url": "{BASE}/api/max/trading/orderbook/BTC?limit=50" | |
| }, | |
| { | |
| "id": "futures_snapshot", | |
| "user_wants": "Get futures mark price, funding rate, and open interest", | |
| "keywords": [ | |
| "futures", | |
| "mark price", | |
| "funding", | |
| "open interest", | |
| "perpetual" | |
| ], | |
| "method": "GET", | |
| "path": "/api/futures/market/snapshot/{symbol}", | |
| "query_params": { | |
| "persist": "true" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "mark_price, funding_rate, open_interest, volume_24h, provider kucoin_futures", | |
| "example_url": "{BASE}/api/futures/market/snapshot/BTC" | |
| }, | |
| { | |
| "id": "futures_ohlcv_live", | |
| "user_wants": "Get live futures candlestick data", | |
| "keywords": [ | |
| "futures candles", | |
| "futures ohlcv", | |
| "futures klines" | |
| ], | |
| "method": "GET", | |
| "path": "/api/futures/market/ohlcv/{symbol}", | |
| "query_params": { | |
| "interval": "1h", | |
| "limit": "50" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "candles[], saved_to_db count, provider", | |
| "example_url": "{BASE}/api/futures/market/ohlcv/BTC?interval=1h&limit=50" | |
| }, | |
| { | |
| "id": "futures_ohlcv_from_db", | |
| "user_wants": "Read stored futures candles from database (no live fetch)", | |
| "keywords": [ | |
| "futures history", | |
| "cached futures", | |
| "database candles" | |
| ], | |
| "method": "GET", | |
| "path": "/api/futures/market/history/{symbol}", | |
| "query_params": { | |
| "interval": "1h", | |
| "limit": "100" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "candles[] from SQLite table cached_futures_ohlc", | |
| "example_url": "{BASE}/api/futures/market/history/BTC?interval=1h&limit=100" | |
| }, | |
| { | |
| "id": "futures_sync_db", | |
| "user_wants": "Force fetch futures snapshot + OHLCV and save to database", | |
| "keywords": [ | |
| "sync futures", | |
| "save futures", | |
| "persist futures" | |
| ], | |
| "method": "POST", | |
| "path": "/api/futures/market/sync/{symbol}", | |
| "query_params": { | |
| "interval": "1h", | |
| "limit": "50" | |
| }, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "snapshot + ohlcv payloads, both persisted", | |
| "example_url": "{BASE}/api/futures/market/sync/BTC?interval=1h&limit=50" | |
| }, | |
| { | |
| "id": "futures_validate_kucoin", | |
| "user_wants": "Validate KuCoin futures contract exists and is tradeable", | |
| "keywords": [ | |
| "kucoin futures", | |
| "contract validate", | |
| "leverage", | |
| "xbtusdtm" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/futures/kucoin/validate/{symbol}", | |
| "query_params": {}, | |
| "path_params": { | |
| "symbol": "BTC" | |
| }, | |
| "returns": "validated, contract, markPrice, maxLeverage", | |
| "example_url": "{BASE}/api/max/futures/kucoin/validate/BTC" | |
| }, | |
| { | |
| "id": "indicators_comprehensive", | |
| "user_wants": "Get RSI, MACD, Bollinger Bands and overall signal for one symbol", | |
| "keywords": [ | |
| "indicators", | |
| "rsi", | |
| "macd", | |
| "bollinger", | |
| "technical analysis", | |
| "signals" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/indicators/comprehensive", | |
| "query_params": { | |
| "symbol": "BTC", | |
| "timeframe": "1h" | |
| }, | |
| "path_params": {}, | |
| "returns": "rsi, macd, bollinger_bands, overall signal BUY|SELL|HOLD", | |
| "example_url": "{BASE}/api/max/indicators/comprehensive?symbol=BTC&timeframe=1h" | |
| }, | |
| { | |
| "id": "indicator_single", | |
| "user_wants": "Get one technical indicator only", | |
| "keywords": [ | |
| "rsi only", | |
| "macd only", | |
| "single indicator" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/indicators/{indicator_id}", | |
| "query_params": { | |
| "symbol": "BTC", | |
| "timeframe": "1h" | |
| }, | |
| "path_params": { | |
| "indicator_id": "rsi" | |
| }, | |
| "returns": "indicator-specific values; indicator_id: rsi|macd|bollinger_bands|sma|ema|...", | |
| "example_url": "{BASE}/api/max/indicators/rsi?symbol=BTC&timeframe=1h" | |
| }, | |
| { | |
| "id": "indicators_batch", | |
| "user_wants": "Analyze multiple symbols or indicators in one POST", | |
| "keywords": [ | |
| "batch indicators", | |
| "analyze many", | |
| "bulk technical" | |
| ], | |
| "method": "POST", | |
| "path": "/api/max/indicators/analyze", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "body_json": { | |
| "symbols": [ | |
| "BTC", | |
| "ETH" | |
| ], | |
| "timeframe": "1h", | |
| "indicators": [ | |
| "rsi", | |
| "macd" | |
| ] | |
| }, | |
| "returns": "results per symbol", | |
| "example_url": "{BASE}/api/max/indicators/analyze" | |
| }, | |
| { | |
| "id": "sentiment_fear_greed", | |
| "user_wants": "Get crypto Fear and Greed index and social sentiment", | |
| "keywords": [ | |
| "sentiment", | |
| "fear greed", | |
| "fng", | |
| "mood", | |
| "social" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/social/sentiment", | |
| "query_params": { | |
| "coin": "BTC" | |
| }, | |
| "path_params": {}, | |
| "returns": "fear_greed value, reddit probe, data_state", | |
| "example_url": "{BASE}/api/max/social/sentiment?coin=BTC" | |
| }, | |
| { | |
| "id": "news_crypto", | |
| "user_wants": "Get latest cryptocurrency news articles", | |
| "keywords": [ | |
| "news", | |
| "headlines", | |
| "articles", | |
| "bitcoin news" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/news", | |
| "query_params": { | |
| "q": "bitcoin", | |
| "limit": "10" | |
| }, | |
| "path_params": {}, | |
| "returns": "items[] with title, url, source; fallback newsapi|cryptocompare|reddit", | |
| "example_url": "{BASE}/api/max/news?q=bitcoin&limit=10" | |
| }, | |
| { | |
| "id": "provider_health", | |
| "user_wants": "Check which data providers are working right now", | |
| "keywords": [ | |
| "providers", | |
| "health", | |
| "probe", | |
| "binance down", | |
| "kucoin status" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/providers/status", | |
| "query_params": { | |
| "symbol": "BTC", | |
| "include_slow": "true" | |
| }, | |
| "path_params": {}, | |
| "returns": "providers[] with live_status ok|down, latency_ms", | |
| "example_url": "{BASE}/api/max/providers/status?symbol=BTC&include_slow=true" | |
| }, | |
| { | |
| "id": "fallback_chains", | |
| "user_wants": "See fallback order when a provider fails", | |
| "keywords": [ | |
| "fallback", | |
| "failover", | |
| "backup provider", | |
| "chain" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/fallback/plan", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "FALLBACK_CHAINS map, binance base rotation", | |
| "example_url": "{BASE}/api/max/fallback/plan" | |
| }, | |
| { | |
| "id": "db_collector_status", | |
| "user_wants": "Check automatic 15-minute database collection worker", | |
| "keywords": [ | |
| "worker", | |
| "scheduler", | |
| "auto collect", | |
| "database sync", | |
| "15 minutes" | |
| ], | |
| "method": "GET", | |
| "path": "/api/worker/comprehensive/status", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "is_running, interval_minutes, last_collection, total_records_saved", | |
| "example_url": "{BASE}/api/worker/comprehensive/status" | |
| }, | |
| { | |
| "id": "db_collector_run_now", | |
| "user_wants": "Trigger immediate full database collection (market+futures+news+sentiment)", | |
| "keywords": [ | |
| "collect now", | |
| "sync database", | |
| "run worker", | |
| "save to db" | |
| ], | |
| "method": "POST", | |
| "path": "/api/worker/comprehensive/run-now", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "totals: market, spot_ohlc, futures_snapshots, futures_ohlc, news, sentiment", | |
| "example_url": "{BASE}/api/worker/comprehensive/run-now" | |
| }, | |
| { | |
| "id": "capabilities_map", | |
| "user_wants": "Get full capability map for integrating client applications", | |
| "keywords": [ | |
| "capabilities", | |
| "features", | |
| "what can this api do" | |
| ], | |
| "method": "GET", | |
| "path": "/api/max/app/capabilities", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "service_matrix, main_app_endpoints, pages", | |
| "example_url": "{BASE}/api/max/app/capabilities" | |
| }, | |
| { | |
| "id": "swagger_ui", | |
| "user_wants": "Browse all 250+ endpoints interactively", | |
| "keywords": [ | |
| "swagger", | |
| "openapi", | |
| "try api", | |
| "interactive docs" | |
| ], | |
| "method": "GET", | |
| "path": "/docs", | |
| "query_params": {}, | |
| "path_params": {}, | |
| "returns": "HTML Swagger UI", | |
| "example_url": "{BASE}/docs" | |
| } | |
| ], | |
| "intent_count": 26, | |
| "quick_examples": { | |
| "health": "curl https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/health", | |
| "symbol_bundle": "curl https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/app/symbol/BTC", | |
| "futures_snapshot": "curl https://really-amin-datasourceforcryptocurrency-1.hf.space/api/futures/market/snapshot/BTC", | |
| "futures_ohlcv": "curl 'https://really-amin-datasourceforcryptocurrency-1.hf.space/api/futures/market/ohlcv/BTC?interval=1h&limit=50'", | |
| "indicators": "curl 'https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/indicators/comprehensive?symbol=BTC&timeframe=1h'", | |
| "news": "curl 'https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/news?q=bitcoin&limit=10'", | |
| "sentiment": "curl 'https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/social/sentiment?coin=BTC'", | |
| "db_collect_now": "curl -X POST https://really-amin-datasourceforcryptocurrency-1.hf.space/api/worker/comprehensive/run-now", | |
| "catalog": "curl https://really-amin-datasourceforcryptocurrency-1.hf.space/api/max/endpoints/catalog" | |
| }, | |
| "catalog": { | |
| "success": true, | |
| "base_prefix": "/api/max", | |
| "total": 37, | |
| "groups": { | |
| "Core": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/health", | |
| "group": "Core", | |
| "purpose": "Layer health, registry, cache" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/health", | |
| "group": "Core", | |
| "purpose": "Simple alive check" | |
| } | |
| ], | |
| "Documentation": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/help", | |
| "group": "Documentation", | |
| "purpose": "This AI-friendly help JSON" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/endpoints/catalog", | |
| "group": "Documentation", | |
| "purpose": "Grouped endpoint catalog" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/docs", | |
| "group": "Documentation", | |
| "purpose": "Swagger UI (250+ routes)" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/openapi.json", | |
| "group": "Documentation", | |
| "purpose": "Full OpenAPI spec" | |
| } | |
| ], | |
| "Main App": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/bootstrap", | |
| "group": "Main App", | |
| "purpose": "Startup bundle for client apps" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/symbol/{symbol}", | |
| "group": "Main App", | |
| "purpose": "All-in-one symbol bundle" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/universe", | |
| "group": "Main App", | |
| "purpose": "Multi-symbol scanner feed" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/capabilities", | |
| "group": "Main App", | |
| "purpose": "Feature and service map" | |
| } | |
| ], | |
| "Market": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/market/price/{symbol}", | |
| "group": "Market", | |
| "purpose": "Spot price with fallback" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/market/snapshot", | |
| "group": "Market", | |
| "purpose": "Multi-asset spot snapshot" | |
| } | |
| ], | |
| "Trading": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/trading/ohlcv/{symbol}", | |
| "group": "Trading", | |
| "purpose": "Spot OHLCV candles" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/trading/orderbook/{symbol}", | |
| "group": "Trading", | |
| "purpose": "Order book" | |
| } | |
| ], | |
| "Futures": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/snapshot/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures mark/funding/OI" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/ohlcv/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Live futures OHLCV + DB save" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/history/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures candles from SQLite" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/futures/market/sync/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Force futures fetch + persist" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/market/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures snapshot via max layer" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/ohlcv/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures OHLCV via max layer" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/kucoin/validate/{symbol}", | |
| "group": "Futures", | |
| "purpose": "KuCoin contract validation" | |
| } | |
| ], | |
| "Indicators": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/services", | |
| "group": "Indicators", | |
| "purpose": "Indicator catalog" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/comprehensive", | |
| "group": "Indicators", | |
| "purpose": "RSI+MACD+BB bundle" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/{indicator_id}", | |
| "group": "Indicators", | |
| "purpose": "Single indicator" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/max/indicators/analyze", | |
| "group": "Indicators", | |
| "purpose": "Batch indicator analysis" | |
| } | |
| ], | |
| "Sentiment": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/social/sentiment", | |
| "group": "Sentiment", | |
| "purpose": "Fear & Greed + Reddit" | |
| } | |
| ], | |
| "News": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/news", | |
| "group": "News", | |
| "purpose": "News with fallback chain" | |
| } | |
| ], | |
| "Providers": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers", | |
| "group": "Providers", | |
| "purpose": "All provider definitions" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers/status", | |
| "group": "Providers", | |
| "purpose": "Live provider probes" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers/test/{provider_id}", | |
| "group": "Providers", | |
| "purpose": "Test one provider" | |
| } | |
| ], | |
| "Operations": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/fallback/plan", | |
| "group": "Operations", | |
| "purpose": "Fallback chain map" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/pressure/status", | |
| "group": "Operations", | |
| "purpose": "Rate-limit / cooldown state" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/cache/status", | |
| "group": "Operations", | |
| "purpose": "In-memory cache stats" | |
| } | |
| ], | |
| "Database Worker": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/comprehensive/config", | |
| "group": "Database Worker", | |
| "purpose": "15-min collector settings" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/comprehensive/status", | |
| "group": "Database Worker", | |
| "purpose": "Collector run stats" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/worker/comprehensive/run-now", | |
| "group": "Database Worker", | |
| "purpose": "Immediate DB sync" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/status", | |
| "group": "Database Worker", | |
| "purpose": "Legacy background worker stats" | |
| } | |
| ] | |
| }, | |
| "endpoints": [ | |
| { | |
| "method": "GET", | |
| "path": "/api/max/health", | |
| "group": "Core", | |
| "purpose": "Layer health, registry, cache" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/help", | |
| "group": "Documentation", | |
| "purpose": "This AI-friendly help JSON" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/endpoints/catalog", | |
| "group": "Documentation", | |
| "purpose": "Grouped endpoint catalog" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/bootstrap", | |
| "group": "Main App", | |
| "purpose": "Startup bundle for client apps" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/symbol/{symbol}", | |
| "group": "Main App", | |
| "purpose": "All-in-one symbol bundle" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/universe", | |
| "group": "Main App", | |
| "purpose": "Multi-symbol scanner feed" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/app/capabilities", | |
| "group": "Main App", | |
| "purpose": "Feature and service map" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/market/price/{symbol}", | |
| "group": "Market", | |
| "purpose": "Spot price with fallback" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/market/snapshot", | |
| "group": "Market", | |
| "purpose": "Multi-asset spot snapshot" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/trading/ohlcv/{symbol}", | |
| "group": "Trading", | |
| "purpose": "Spot OHLCV candles" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/trading/orderbook/{symbol}", | |
| "group": "Trading", | |
| "purpose": "Order book" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/snapshot/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures mark/funding/OI" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/ohlcv/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Live futures OHLCV + DB save" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/futures/market/history/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures candles from SQLite" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/futures/market/sync/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Force futures fetch + persist" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/market/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures snapshot via max layer" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/ohlcv/{symbol}", | |
| "group": "Futures", | |
| "purpose": "Futures OHLCV via max layer" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/futures/kucoin/validate/{symbol}", | |
| "group": "Futures", | |
| "purpose": "KuCoin contract validation" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/services", | |
| "group": "Indicators", | |
| "purpose": "Indicator catalog" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/comprehensive", | |
| "group": "Indicators", | |
| "purpose": "RSI+MACD+BB bundle" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/indicators/{indicator_id}", | |
| "group": "Indicators", | |
| "purpose": "Single indicator" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/max/indicators/analyze", | |
| "group": "Indicators", | |
| "purpose": "Batch indicator analysis" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/social/sentiment", | |
| "group": "Sentiment", | |
| "purpose": "Fear & Greed + Reddit" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/news", | |
| "group": "News", | |
| "purpose": "News with fallback chain" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers", | |
| "group": "Providers", | |
| "purpose": "All provider definitions" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers/status", | |
| "group": "Providers", | |
| "purpose": "Live provider probes" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/providers/test/{provider_id}", | |
| "group": "Providers", | |
| "purpose": "Test one provider" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/fallback/plan", | |
| "group": "Operations", | |
| "purpose": "Fallback chain map" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/pressure/status", | |
| "group": "Operations", | |
| "purpose": "Rate-limit / cooldown state" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/max/cache/status", | |
| "group": "Operations", | |
| "purpose": "In-memory cache stats" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/comprehensive/config", | |
| "group": "Database Worker", | |
| "purpose": "15-min collector settings" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/comprehensive/status", | |
| "group": "Database Worker", | |
| "purpose": "Collector run stats" | |
| }, | |
| { | |
| "method": "POST", | |
| "path": "/api/worker/comprehensive/run-now", | |
| "group": "Database Worker", | |
| "purpose": "Immediate DB sync" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/api/worker/status", | |
| "group": "Database Worker", | |
| "purpose": "Legacy background worker stats" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/health", | |
| "group": "Core", | |
| "purpose": "Simple alive check" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/docs", | |
| "group": "Documentation", | |
| "purpose": "Swagger UI (250+ routes)" | |
| }, | |
| { | |
| "method": "GET", | |
| "path": "/openapi.json", | |
| "group": "Documentation", | |
| "purpose": "Full OpenAPI spec" | |
| } | |
| ], | |
| "swagger": "/docs", | |
| "openapi": "/openapi.json", | |
| "timestamp": "2026-06-07T07:33:09.745319+00:00" | |
| }, | |
| "database_tables": [ | |
| { | |
| "table": "cached_market_data", | |
| "contains": "Spot prices saved by background collector", | |
| "read_via": "Internal; use /api/max/market/price for live" | |
| }, | |
| { | |
| "table": "cached_ohlc", | |
| "contains": "Spot OHLC candles", | |
| "read_via": "/api/ohlcv or /api/max/trading/ohlcv" | |
| }, | |
| { | |
| "table": "cached_futures_snapshot", | |
| "contains": "Futures mark price, funding, OI snapshots", | |
| "read_via": "/api/futures/market/snapshot or history" | |
| }, | |
| { | |
| "table": "cached_futures_ohlc", | |
| "contains": "Futures OHLC candles", | |
| "read_via": "/api/futures/market/history/{symbol}" | |
| }, | |
| { | |
| "table": "news_articles", | |
| "contains": "Collected news articles", | |
| "read_via": "/api/news/latest or /api/max/news" | |
| }, | |
| { | |
| "table": "sentiment_metrics", | |
| "contains": "Fear & Greed and other sentiment metrics", | |
| "read_via": "/api/max/social/sentiment" | |
| }, | |
| { | |
| "table": "market_prices", | |
| "contains": "Historical spot price rows", | |
| "read_via": "Internal time-series" | |
| } | |
| ], | |
| "workers": [ | |
| { | |
| "name": "Comprehensive DB Collector", | |
| "interval_minutes": 15, | |
| "env_enable": "COMPREHENSIVE_DB_COLLECTOR_ENABLED=true", | |
| "collects": [ | |
| "market prices", | |
| "spot OHLC", | |
| "futures snapshot", | |
| "futures OHLC", | |
| "news", | |
| "sentiment" | |
| ], | |
| "database": "data/api_monitor.db", | |
| "status_api": "/api/worker/comprehensive/status", | |
| "run_now_api": "POST /api/worker/comprehensive/run-now" | |
| }, | |
| { | |
| "name": "Legacy Background Worker", | |
| "interval_minutes": "5 UI + 15 historical", | |
| "database": "data/crypto_data.db", | |
| "status_api": "/api/worker/status" | |
| } | |
| ], | |
| "product_tiers": [ | |
| { | |
| "tier": "Basic", | |
| "includes": [ | |
| "spot price", | |
| "fear & greed", | |
| "/api/max/health" | |
| ] | |
| }, | |
| { | |
| "tier": "Trader", | |
| "includes": [ | |
| "Basic", | |
| "OHLCV", | |
| "indicators", | |
| "futures snapshot", | |
| "orderbook" | |
| ] | |
| }, | |
| { | |
| "tier": "Pro", | |
| "includes": [ | |
| "Trader", | |
| "news", | |
| "DB futures history", | |
| "provider status" | |
| ] | |
| }, | |
| { | |
| "tier": "Enterprise", | |
| "includes": [ | |
| "Pro", | |
| "/api/max/app/* bundles", | |
| "comprehensive DB worker", | |
| "batch indicators" | |
| ] | |
| } | |
| ], | |
| "ui_pages": [ | |
| { | |
| "route": "/help", | |
| "purpose": "This guide (human + loads /api/max/help)" | |
| }, | |
| { | |
| "route": "/market", | |
| "purpose": "Live market dashboard" | |
| }, | |
| { | |
| "route": "/services", | |
| "purpose": "Indicator services + main-app API links" | |
| }, | |
| { | |
| "route": "/technical-analysis", | |
| "purpose": "Charts and TA" | |
| }, | |
| { | |
| "route": "/trading-assistant", | |
| "purpose": "Trading tools" | |
| }, | |
| { | |
| "route": "/news", | |
| "purpose": "News feed" | |
| }, | |
| { | |
| "route": "/sentiment", | |
| "purpose": "Sentiment dashboard" | |
| }, | |
| { | |
| "route": "/api-explorer", | |
| "purpose": "Try APIs in browser" | |
| }, | |
| { | |
| "route": "/system-monitor", | |
| "purpose": "Provider visual graph" | |
| } | |
| ], | |
| "important_rules": [ | |
| "Never fabricate prices if data_state is UNAVAILABLE — report failure to the user.", | |
| "Prefer /api/max/app/symbol/{symbol} when the user asks for 'everything about BTC'.", | |
| "Futures primary provider is KuCoin (US-safe); Binance fapi may be geo-blocked on HF US.", | |
| "First request after Space sleep may take 30-60 seconds — use timeout>=60.", | |
| "POST /api/futures/market/sync/{symbol} persists data; GET history reads from DB.", | |
| "Comprehensive DB collector runs every 15 minutes when COMPREHENSIVE_DB_COLLECTOR_ENABLED=true." | |
| ], | |
| "common_errors": [ | |
| { | |
| "http": 404, | |
| "fix": "Call GET /api/max/endpoints/catalog or /openapi.json to verify path" | |
| }, | |
| { | |
| "http": 503, | |
| "fix": "All providers in chain failed; check GET /api/max/providers/status" | |
| }, | |
| { | |
| "http": 422, | |
| "fix": "POST body schema wrong — see body_json on the intent_map entry" | |
| }, | |
| { | |
| "symptom": "Empty futures history", | |
| "fix": "Run POST /api/worker/comprehensive/run-now or POST /api/futures/market/sync/BTC first" | |
| } | |
| ], | |
| "related_files": { | |
| "json_mirror": "api-resources/ai_api_help_guide.json", | |
| "human_help_page": "/help", | |
| "swagger": "/docs" | |
| }, | |
| "timestamp": "2026-06-07T07:33:09.745340+00:00" | |
| } |