{
  "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"
}