{"openapi":"3.1.0","info":{"title":"NythosX Market Data API","version":"1","description":"Derived market analytics for AI agents, paid per request in USDC via x402: complete trade setups, signal bias with invalidation, support/resistance, regime, target-hit probabilities and webhook price triggers, with a free, publicly graded track record. Crypto (BTC, ETH, SOL, BNB, XRP, ADA, LTC, XDC), US stocks (NVDA, MSFT, AMZN, AAPL) and USD/PHP. Informational analytics generated by rules and statistics, not investment advice. Past accuracy does not guarantee future results. You are responsible for your own decisions.","x-guidance":"Market analytics for agents, paid per call in USDC via x402. Pick a symbol (BTC, SOL, ETH, BNB, LTC, ADA, XRP, XDC, NVDA, MSFT, AMZN, AAPL, USDPHP). Start with GET /api/v1/trade-plan?symbol=BTC&tf=4h: bias, regime, levels, entry/stop/target and the probability of reaching the target before the stop in one call. Single pieces: /api/v1/advisor (signal bias), /api/v1/levels, /api/v1/regime, /api/v1/probability?symbol=&target=. POST /api/v1/triggers for a signed webhook when a price is crossed. Free: GET /api/v1/track-record (graded accuracy of every bias, check it before relying on signals) and GET /api/v1/snapshot?symbol=BTC|ETH. Every response is an envelope {schema_version, generated_at, source_timestamp, data, disclaimer}. Free samples at /api/v1/sample?endpoint=. Failed calls are not charged.","contact":{"url":"https://market.nythosx.com","email":"support@nythosx.com"}},"servers":[{"url":"https://market.nythosx.com"}],"paths":{"/api/v1/advisor":{"get":{"operationId":"advisor","summary":"Signal bias with setup levels and invalidation","description":"Rules-based bias (bullish/lean_bullish/neutral/lean_bearish/bearish) with score, confidence, setup, weighted factors, invalidation. tf sets candle size and lookback (5m=1H to 1w=1Y): shorter is faster but noisier, longer is slower but higher-conviction. Accuracy free at /api/v1/track-record. Quick direction + one setup; get_trade_plan ($0.03) adds target-before-stop odds, get_market_regime ($0.005) is trend/volatility only. Price: $0.01 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"bias":"lean_bullish","score":2.75,"confidence":"medium","price":81450.2,"headline":"Lean bullish bias: 4 bullish vs 1 bearish factors on the 7D view.","setup":{"direction":"long","entry":80900,"stop":79200,"target":84500,"rr":2.1},"invalidation":["A daily close below 79,200 breaks the current structure."],"watch":["A close above 84,500 would be bullish."],"factors":[{"label":"Trend is up","detail":"Price is above its 20-candle average.","weight":2}],"indicators":{"rsi":47.2,"atrPct":1.4,"trend":"up","support":80900,"resistance":84500}}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Instrument symbol, case-insensitive. Must be one of the enum values below; an unsupported symbol returns 400 before any payment is charged.","schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}},{"name":"tf","in":"query","required":false,"description":"Candle timeframe. Sets both the candle size and the lookback window analyzed: 5m=1H, 1h=24H, 4h=7D, 1d=30D, 1w=1Y.","schema":{"type":"string","enum":["5m","1h","4h","1d","1w"],"default":"4h"}}]}},"/api/v1/trade-plan":{"get":{"operationId":"tradePlan","summary":"Complete trade setup in one call","description":"Bundles signal bias, regime, levels, setup (entry, stop, target, R:R), odds of target-before-stop and of touching target within 7 days, time-to-target, invalidation, and track record. tf sets candle size and lookback (5m=1H to 1w=1Y); shorter is faster but noisier. Neutral bias returns odds of hitting resistance before support. For one piece only, call get_signal_bias ($0.01) or get_market_regime ($0.005) — cheaper. Price: $0.03 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"bias":"bearish","confidence":"high","score":-4.5,"price":2387.4,"headline":"Bearish bias: 1 bullish vs 5 bearish factors on the 7D view.","regime":{"trend":"down","volatility":"high","rsi":38.5,"atrPct":2.9},"levels":{"nearestSupport":{"price":2310,"kind":"swing_low","strength":3,"touches":3},"nearestResistance":{"price":2480,"kind":"hvn","strength":2,"touches":4}},"setup":{"direction":"short","entry":2387.4,"stop":2502,"target":2310,"rr":0.7,"targetBeforeStopPct":59.6,"touchTarget7dPct":61.2,"daysToTargetEstimate":2.4},"range":null,"invalidation":["A daily close above 2,480 flips the setup."],"trackRecord":{"symbol":"ETH","samples":47,"hitRatePct":40.4,"independentSamples":19,"url":"https://market.nythosx.com/api/v1/track-record?symbol=ETH"}}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Instrument symbol, case-insensitive. Must be one of the enum values below; an unsupported symbol returns 400 before any payment is charged.","schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}},{"name":"tf","in":"query","required":false,"description":"Candle timeframe. Sets both the candle size and the lookback window analyzed: 5m=1H, 1h=24H, 4h=7D, 1d=30D, 1w=1Y.","schema":{"type":"string","enum":["5m","1h","4h","1d","1w"],"default":"4h"}}]}},"/api/v1/levels":{"get":{"operationId":"levels","summary":"Support and resistance map","description":"Up to five support and five resistance levels from clustered daily swing pivots, high-volume nodes and round numbers, each with kind, strength (1-5) and touch count, plus the nearest level on each side. Computed from the last 30 daily candles (cached 15 minutes). Use nearestSupport/nearestResistance as stop-loss/take-profit anchors for a position already open; higher strength and touch count mean a more reliable level. Price: $0.005 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"current":2387.4,"nearestSupport":{"price":2310,"kind":"swing_low","strength":3,"touches":3},"nearestResistance":{"price":2480,"kind":"hvn","strength":2,"touches":4},"support":[],"resistance":[]}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Instrument symbol, case-insensitive. Must be one of the enum values below; an unsupported symbol returns 400 before any payment is charged.","schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}}]}},"/api/v1/regime":{"get":{"operationId":"regime","summary":"Trend and volatility regime","description":"Market regime from the last 24 hours of hourly candles (cached 5 minutes): trend (up / down / range, EMA50 vs EMA200), volatility bucket (low / normal / high / extreme by ATR%), RSI, EMAs. Use this for risk sizing or entry timing (e.g. avoid new entries while volatility is 'extreme') alongside get_signal_bias for direction and get_support_resistance for levels — on its own it gives context, not a trade direction. symbol uses the same trend/volatility thresholds for every instrument, so regime readings are directly comparable across symbols (e.g. BTC 'high' and SOL 'high' mean the same ATR% bucket). Price: $0.005 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"trend":"down","volatility":"high","rsi":38.5,"atrPct":2.9,"ema50":101.2,"ema200":108.7,"lastClose":99.8}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Instrument symbol, case-insensitive. Must be one of the enum values below; an unsupported symbol returns 400 before any payment is charged.","schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}}]}},"/api/v1/probability":{"get":{"operationId":"probability","summary":"Probability of reaching a target price","description":"Probability that the price closes beyond a target within 1, 7 and 30 days, and the approximate probability of touching it, from 14-day ATR volatility (normal approximation; touch ~ 2x close-beyond by the reflection principle). symbol must be one of the supported list (see list_symbols) and target must be a positive number, or the call returns 400 and is not charged; if volatility can't be computed from recent candles it returns 502 and is not charged. Price: $0.005 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"current":81450.2,"target":90000,"movePct":10.5,"dailyVolPct":2.6,"closeBeyondPct":{"d1":0,"d7":2.9,"d30":9.4},"touchPct":{"d1":0,"d7":5.8,"d30":18.8},"daysEstimate":16.3}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"parameters":[{"name":"symbol","in":"query","required":true,"description":"Instrument symbol, case-insensitive. Must be one of the enum values below; an unsupported symbol returns 400 before any payment is charged.","schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}},{"name":"target","in":"query","required":true,"description":"Target price in the instrument's quote currency","schema":{"type":"number"}}]}},"/api/v1/triggers":{"post":{"operationId":"triggers","summary":"Arm a price trigger with webhook delivery","description":"Arms a single-fire price trigger. NythosX checks the price every minute and POSTs a JSON event to your HTTPS webhook on the first crossing: {event:\"trigger.fired\", id, symbol, direction, price, fired_price, fired_at}, signed with HMAC-SHA256 (header X-NythosX-Signature: sha256=<hex> over the raw body, key = returned secret). Retries up to 5 times (8s timeout per attempt, until your endpoint returns 2xx); after 5 failed attempts delivery is marked failed — check status free with get_trigger_status (REST: GET /api/v1/triggers/status?id=) to see delivery_attempts/last_error. Expires after ttl_hours (default 168, max 720); cancel any time before it fires, free, with disarm_price_trigger (REST: POST /api/v1/triggers/cancel with {id, secret}) — the arm fee is not refunded, it paid for the monitoring already done. Price: $0.02 USDC per call via x402.","tags":["Market data"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}],"network":"eip155:8453","asset":"USDC"},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]},"example":{"schema_version":"1","data":{"id":"trg_3f9a2c...","secret":"whsec_...","symbol":"BTC","direction":"below","price":78000,"current":81450.2,"expires_at":"2026-10-27T08:00:00.000Z","status_url":"https://market.nythosx.com/api/v1/triggers/status?id=trg_3f9a2c..."}}}}},"400":{"description":"Invalid input. Sent with a payment, it is rejected before the payment is verified (not charged)."},"402":{"description":"Payment required. PAYMENT-REQUIRED header holds base64 JSON x402 v2 requirements; retry with PAYMENT-SIGNATURE."},"502":{"description":"Upstream data unavailable. Payment is not settled."},"503":{"description":"Payment facilitator unavailable. Retry after the Retry-After header."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","direction","price","webhook_url"],"properties":{"symbol":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]},"direction":{"type":"string","enum":["above","below"]},"price":{"type":"number","exclusiveMinimum":0},"webhook_url":{"type":"string","format":"uri","description":"Public HTTPS URL"},"ttl_hours":{"type":"integer","minimum":1,"maximum":720,"default":168}}},"example":{"symbol":"BTC","direction":"below","price":78000,"webhook_url":"https://example.com/hooks/nythosx","ttl_hours":168}}}}}},"/api/v1/triggers/status":{"get":{"operationId":"triggerStatus","summary":"Trigger status (free)","security":[],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trigger state"},"404":{"description":"Unknown trigger"}}}},"/api/v1/triggers/cancel":{"post":{"operationId":"cancelTrigger","summary":"Cancel an armed trigger before it fires (free)","security":[],"description":"Requires both id and secret (returned once when the trigger was armed) as proof of ownership. No-op charge: cancelling does not refund the $0.02 arm fee, which paid for the monitoring already done. Fails 409 if already fired or already cancelled.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","secret"],"properties":{"id":{"type":"string"},"secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Cancelled"},"404":{"description":"Unknown id/secret pair"},"409":{"description":"Already fired or already cancelled"}}}},"/api/v1/sample":{"get":{"operationId":"sample","summary":"Free sample response for a paid endpoint (fixed inputs, cached)","security":[],"parameters":[{"name":"endpoint","in":"query","required":true,"schema":{"type":"string","enum":["advisor","trade-plan","levels","regime","probability"]}}],"responses":{"200":{"description":"Sample"}}}},"/api/v1/track-record":{"get":{"operationId":"trackRecord","summary":"Graded accuracy of every published bias (free)","security":[],"description":"Hit rate and average return by confidence, by bias and by symbol, Wilson 95% intervals, Brier score and independentSamples.","parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","enum":["BTC","SOL","ETH","BNB","LTC","ADA","XRP","XDC","NVDA","MSFT","AMZN","AAPL","USDPHP"]}}],"responses":{"200":{"description":"Track record","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]}}}},"404":{"description":"Nothing graded yet"}}}},"/api/v1/snapshot":{"get":{"operationId":"snapshot","summary":"Free regime and nearest levels for BTC and ETH","security":[],"parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","enum":["BTC","ETH"]}}],"responses":{"200":{"description":"Snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"type":"string"},"endpoint":{"type":"string"},"symbol":{"type":["string","null"]},"generated_at":{"type":"string","format":"date-time"},"source_timestamp":{"type":["string","null"],"format":"date-time"},"data":{"type":"object"},"disclaimer":{"type":"string"}},"required":["schema_version","endpoint","generated_at","data","disclaimer"]}}}}}}},"/api/catalog":{"get":{"operationId":"catalog","summary":"Machine-readable catalog (free)","security":[],"responses":{"200":{"description":"Catalog"}}}}}}