{"openapi":"3.1.0","info":{"title":"WHYLY API","summary":"Market reasoning protocol — structured explanations of why crypto prices moved.","description":"WHYLY answers one question: **Why did the price move?**\n\nIt returns structured, weighted explanations with cited sources.\n\n## Quick Start\n\n```bash\ncurl -H 'X-API-Key: sk8f3kx9m2v7nq4w1jabc' https://api.whyly.app/v1/explain\n```\n\n## Endpoints\n\n| Endpoint | Auth | Description |\n|----------|------|-------------|\n| `GET /v1/explain` | API key | Get market movement explanation |\n| `GET /v1/assets` | None | List supported assets |\n| `GET /v1/plans` | None | List plans and pricing |\n| `GET /v1/subscribe` | None | Get subscription plans and payment info |\n| `GET /v1/health` | None | Health check |\n\n## Authentication\n\nPass your API key via the `X-API-Key` header on every request to `/v1/explain`.\n\n**Public key (free tier):** `sk8f3kx9m2v7nq4w1jabc` — no signup required.\n\n## Rate Limits\n\nCheck `X-RateLimit-Remaining` in response headers. Limits reset at midnight UTC. See `GET /v1/plans` for plan details.\n\n## Error Handling\n\nEvery error includes a `hint` field explaining what went wrong and how to fix it. Agents should read the `hint` before retrying.","contact":{"name":"WHYLY","url":"https://whyly.app/","email":"api@whyly.app"},"license":{"name":"Proprietary"},"version":"v1"},"servers":[{"url":"https://api.whyly.app","description":"Production"},{"url":"http://localhost:8000","description":"Local development"}],"paths":{"/v1/explain":{"get":{"tags":["explain"],"summary":"Explain market movement","description":"Returns a structured explanation of why the given asset (or overall market) moved in the specified time window.\n\n**Response includes:**\n- `market_direction`: up, down, or flat\n- `confidence`: 0.0-1.0 signal quality score\n- `drivers`: weighted, categorized reasons with cited sources\n- `total_drivers`: total count before plan truncation (free plan gets 2 drivers)\n- `plan`: caller's plan — use this to render paywalls in client apps\n- `summary`: 1-2 sentence explanation in requested language\n\n**Language (pro+):** Pass `lang` parameter (e.g. `lang=uk`, `lang=es`) to get titles, explanations, and summary in that language. Default: `en`. Free tier is English only.\n\n**Rescan:** Pass `rescan=true` to bypass cache and get fresh analysis. Pro only, limited to 10/day. Check `X-Rescan-Remaining` header.\n\n**Caching:** Responses are cached for 1 hour. Check `X-Cache` header (HIT/MISS) and `cache_expires_at` in the response body.\n\n**Rate limits:** Check `X-RateLimit-Remaining` header. See `GET /v1/plans` for limits.","operationId":"explainAsset","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"asset","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Asset","description":"Asset to explain","default":"MARKET"},"description":"Asset to explain"},{"name":"window","in":"query","required":false,"schema":{"$ref":"#/components/schemas/TimeWindow","description":"Time window","default":"24h"},"description":"Time window"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","maxLength":5,"description":"Response language (en, uk, es, de, fr, ja, zh, etc.). Pro+ only, free tier is English only.","default":"en","title":"Lang"},"description":"Response language (en, uk, es, de, fr, ja, zh, etc.). Pro+ only, free tier is English only."},{"name":"rescan","in":"query","required":false,"schema":{"type":"boolean","description":"Force-refresh, bypasses cache. Pro only, 10/day.","default":false,"title":"Rescan"},"description":"Force-refresh, bypasses cache. Pro only, 10/day."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"example":{"error":{"code":"UNAUTHORIZED","message":"Missing X-API-Key header.","hint":"Include your API key in the X-API-Key header. Get a key at https://whyly.app/keys","status":401}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Asset not available on your plan, or rescan not available","content":{"application/json":{"example":{"error":{"code":"ASSET_NOT_AVAILABLE","message":"Asset 'BTC' is not available on the free plan.","hint":"Upgrade to the pro plan for access to all tokens. See GET /v1/assets for the full list.","status":403}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Daily rate limit or rescan limit exceeded","content":{"application/json":{"example":{"error":{"code":"RATE_LIMITED","message":"Daily rate limit of 10 requests exceeded.","hint":"Your limit resets at midnight UTC. Upgrade to pro for 100 requests/day.","status":429}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"tags":["meta"],"summary":"Health check","description":"Returns API status, version, and server timestamp. No authentication required.","operationId":"healthCheck","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/assets":{"get":{"tags":["meta"],"summary":"List supported assets","description":"Returns all assets supported by the API and available time windows. Useful for agent auto-discovery of available analysis targets.","operationId":"listAssets","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetsResponse"}}}}}}},"/v1/plans":{"get":{"tags":["meta"],"summary":"List available plans","description":"Returns all plans with their rate limits, available assets, and pricing. Useful for agents to programmatically discover pricing and choose a plan.","operationId":"listPlans","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlansResponse"}}}}}}},"/v1/subscribe":{"get":{"tags":["meta"],"summary":"Get subscription plans and payment info","description":"Returns API subscription plans with pricing and payment instructions.\n\n**How to subscribe:**\n1. Choose a plan (Pro or Enterprise)\n2. Send USDT to the provided wallet address\n3. Email your transaction hash to api@whyly.app\n4. Receive your API key within 24 hours\n\nNo authentication required. Designed for agents to programmatically discover pricing and guide users through purchase.","operationId":"subscribe","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}}}}}},"components":{"schemas":{"Asset":{"type":"string","enum":["MARKET","AAVE","ADA","ALGO","APT","ARB","ATOM","AVAX","BCH","BGB","BNB","BONK","BTC","CRO","DOGE","DOT","ENA","ETC","ETH","FIL","FLR","GT","HBAR","HNT","HYPE","ICP","JUP","KAS","KCS","LEO","LINK","LTC","MNT","NEAR","NEXO","OKB","ONDO","PEPE","POL","POPCAT","QNT","RENDER","SEI","SHIB","SOL","SUI","TAO","TON","TRUMP","TRX","UNI","VET","WLD","XDC","XLM","XMR","XRP"],"title":"Asset"},"AssetInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"available":{"type":"boolean","title":"Available"}},"type":"object","required":["id","name","available"],"title":"AssetInfo"},"AssetsResponse":{"properties":{"assets":{"items":{"$ref":"#/components/schemas/AssetInfo"},"type":"array","title":"Assets"},"supported_windows":{"items":{"type":"string"},"type":"array","title":"Supported Windows"},"api_version":{"type":"string","title":"Api Version","default":"v1"}},"type":"object","required":["assets","supported_windows"],"title":"AssetsResponse"},"Driver":{"properties":{"category":{"$ref":"#/components/schemas/DriverCategory"},"impact":{"$ref":"#/components/schemas/Impact"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight"},"title":{"type":"string","title":"Title"},"explanation":{"type":"string","title":"Explanation"},"sources":{"items":{"$ref":"#/components/schemas/Source"},"type":"array","minItems":1,"title":"Sources"}},"type":"object","required":["category","impact","weight","title","explanation","sources"],"title":"Driver"},"DriverCategory":{"type":"string","enum":["macro","flows","onchain","regulation","technical","sentiment"],"title":"DriverCategory"},"ErrorCode":{"type":"string","enum":["UNAUTHORIZED","RATE_LIMITED","INVALID_ASSET","INVALID_WINDOW","ASSET_NOT_AVAILABLE","FEATURE_NOT_AVAILABLE","INTERNAL_ERROR","SERVICE_UNAVAILABLE"],"title":"ErrorCode"},"ErrorDetail":{"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","title":"Message"},"hint":{"type":"string","title":"Hint"},"status":{"type":"integer","title":"Status"}},"type":"object","required":["code","message","hint","status"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"type":"object","required":["error"],"title":"ErrorResponse"},"ExplainResponse":{"properties":{"asset":{"$ref":"#/components/schemas/Asset"},"time_window":{"$ref":"#/components/schemas/TimeWindow"},"market_direction":{"$ref":"#/components/schemas/MarketDirection"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence"},"drivers":{"items":{"$ref":"#/components/schemas/Driver"},"type":"array","maxItems":6,"minItems":1,"title":"Drivers"},"total_drivers":{"type":"integer","title":"Total Drivers","description":"Total drivers before plan truncation. 0 = no truncation.","default":0},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan","description":"Caller's plan (free, pro, enterprise). Helps clients render paywalls."},"summary":{"type":"string","title":"Summary"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"cached":{"type":"boolean","title":"Cached"},"cache_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Cache Expires At"},"api_version":{"type":"string","title":"Api Version","default":"v1"}},"type":"object","required":["asset","time_window","market_direction","confidence","drivers","summary","generated_at","cached"],"title":"ExplainResponse","examples":[{"api_version":"v1","asset":"BTC","cache_expires_at":"2026-02-10T19:30:00Z","cached":false,"confidence":0.82,"drivers":[{"category":"macro","explanation":"Higher CPI reduced expectations for near-term rate cuts.","impact":"negative","sources":[{"name":"Reuters","url":"https://reuters.com/article/123"}],"title":"US CPI came above expectations","weight":0.45},{"category":"flows","explanation":"Spot BTC ETFs saw net outflows of $312M.","impact":"negative","sources":[{"name":"SoSoValue","url":"https://sosovalue.com/etf"}],"title":"BTC ETF net outflows","weight":0.35},{"category":"sentiment","explanation":"Market sentiment shifted from neutral to fear.","impact":"negative","sources":[{"name":"Alternative.me","url":"https://alternative.me/crypto/fear-and-greed-index/"}],"title":"Fear & Greed Index dropped to 28","weight":0.2}],"generated_at":"2026-02-10T18:30:00Z","market_direction":"down","summary":"BTC declined mainly due to macro pressure and ETF outflows.","time_window":"24h"}]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"version":{"type":"string","title":"Version","default":"v1"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"}},"type":"object","required":["timestamp"],"title":"HealthResponse"},"Impact":{"type":"string","enum":["positive","negative","neutral"],"title":"Impact"},"MarketDirection":{"type":"string","enum":["up","down","flat"],"title":"MarketDirection"},"PaymentInfo":{"properties":{"method":{"type":"string","title":"Method"},"network":{"type":"string","title":"Network"},"wallet_address":{"type":"string","title":"Wallet Address"},"instructions":{"items":{"type":"string"},"type":"array","title":"Instructions"}},"type":"object","required":["method","network","wallet_address","instructions"],"title":"PaymentInfo"},"PlanInfo":{"properties":{"id":{"type":"string","title":"Id"},"daily_limit":{"type":"integer","title":"Daily Limit"},"assets":{"items":{"type":"string"},"type":"array","title":"Assets"},"max_drivers":{"type":"integer","title":"Max Drivers"},"rescan_limit":{"type":"integer","title":"Rescan Limit"},"price":{"type":"string","title":"Price"}},"type":"object","required":["id","daily_limit","assets","max_drivers","rescan_limit","price"],"title":"PlanInfo"},"PlansResponse":{"properties":{"plans":{"items":{"$ref":"#/components/schemas/PlanInfo"},"type":"array","title":"Plans"},"api_version":{"type":"string","title":"Api Version","default":"v1"}},"type":"object","required":["plans"],"title":"PlansResponse"},"PricingOption":{"properties":{"interval":{"type":"string","title":"Interval"},"price":{"type":"string","title":"Price"},"price_usd":{"type":"number","title":"Price Usd"},"save_percent":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Save Percent"}},"type":"object","required":["interval","price","price_usd"],"title":"PricingOption"},"Source":{"properties":{"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["name","url"],"title":"Source","examples":[{"name":"Reuters","url":"https://reuters.com/article/123"}]},"SubscribePlan":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"pricing":{"items":{"$ref":"#/components/schemas/PricingOption"},"type":"array","title":"Pricing"},"features":{"items":{"type":"string"},"type":"array","title":"Features"},"highlighted":{"type":"boolean","title":"Highlighted","default":false}},"type":"object","required":["id","name","description","pricing","features"],"title":"SubscribePlan"},"SubscribeResponse":{"properties":{"demo_key":{"type":"string","title":"Demo Key"},"plans":{"items":{"$ref":"#/components/schemas/SubscribePlan"},"type":"array","title":"Plans"},"payment":{"$ref":"#/components/schemas/PaymentInfo"},"contact":{"type":"string","title":"Contact"},"api_version":{"type":"string","title":"Api Version","default":"v1"}},"type":"object","required":["demo_key","plans","payment","contact"],"title":"SubscribeResponse"},"TimeWindow":{"type":"string","enum":["24h"],"title":"TimeWindow"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}