#!/usr/bin/env python3 """ Machine-readable API help guide for humans, LLMs, and simple AI agents. Served at GET /api/max/help and mirrored to api-resources/ai_api_help_guide.json. Write every section in plain English with explicit intent → endpoint mapping. """ from __future__ import annotations import json from datetime import datetime, timezone from pathlib import Path from typing import Any, Dict, List ROOT = Path(__file__).resolve().parents[2] GUIDE_JSON_PATH = ROOT / "api-resources" / "ai_api_help_guide.json" DEFAULT_BASE = "https://really-amin-datasourceforcryptocurrency-1.hf.space" def _now_iso() -> str: return datetime.now(timezone.utc).isoformat() # --------------------------------------------------------------------------- # Intent map — dumb-AI friendly: match keywords → call this endpoint # --------------------------------------------------------------------------- INTENT_MAP: List[Dict[str, Any]] = [ { "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", }, ] ALL_ENDPOINTS: List[Dict[str, str]] = [ {"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"}, ] AI_AGENT_INSTRUCTIONS: Dict[str, Any] = { "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", }, } DATABASE_TABLES: List[Dict[str, str]] = [ {"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: List[Dict[str, Any]] = [ { "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: List[Dict[str, Any]] = [ {"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"]}, ] def build_endpoint_catalog() -> Dict[str, Any]: groups: Dict[str, List[Dict[str, str]]] = {} for item in ALL_ENDPOINTS: groups.setdefault(item["group"], []).append(item) return { "success": True, "base_prefix": "/api/max", "total": len(ALL_ENDPOINTS), "groups": groups, "endpoints": ALL_ENDPOINTS, "swagger": "/docs", "openapi": "/openapi.json", "timestamp": _now_iso(), } def build_api_help_payload(base_url: str = DEFAULT_BASE) -> Dict[str, Any]: """Full payload returned by GET /api/max/help.""" catalog = build_endpoint_catalog() payload = { "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": base_url, "base_url_placeholder": "{BASE}", "for_ai_agents": AI_AGENT_INSTRUCTIONS, "intent_map": INTENT_MAP, "intent_count": len(INTENT_MAP), "quick_examples": { "health": f"curl {base_url}/api/max/health", "symbol_bundle": f"curl {base_url}/api/max/app/symbol/BTC", "futures_snapshot": f"curl {base_url}/api/futures/market/snapshot/BTC", "futures_ohlcv": f"curl '{base_url}/api/futures/market/ohlcv/BTC?interval=1h&limit=50'", "indicators": f"curl '{base_url}/api/max/indicators/comprehensive?symbol=BTC&timeframe=1h'", "news": f"curl '{base_url}/api/max/news?q=bitcoin&limit=10'", "sentiment": f"curl '{base_url}/api/max/social/sentiment?coin=BTC'", "db_collect_now": f"curl -X POST {base_url}/api/worker/comprehensive/run-now", "catalog": f"curl {base_url}/api/max/endpoints/catalog", }, "catalog": catalog, "database_tables": DATABASE_TABLES, "workers": WORKERS, "product_tiers": PRODUCT_TIERS, "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": _now_iso(), } return payload def write_guide_json_file(base_url: str = DEFAULT_BASE) -> Path: """Persist guide to api-resources for static download / git visibility.""" payload = build_api_help_payload(base_url=base_url) GUIDE_JSON_PATH.parent.mkdir(parents=True, exist_ok=True) GUIDE_JSON_PATH.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8") return GUIDE_JSON_PATH