# Introduction Synth API offers programmatic access to probabilistic price forecasts across **1-hour and 24-hour horizons** for Equities, Commodities and Cryptocurrencies, powered by a decentralized network of machine learning models. The API equips traders, developers, and institutions with predictive intelligence to gain a competitive edge, identify opportunities, and make informed decisions in dynamic markets. ## Synth API Features ### Probabilistic Forecasts, Not Point Predictions Unlike traditional forecasting APIs that return a single price prediction, Synth delivers ensemble forecasts constructed from individual models submitted by the top-performing data scientists on the network. Each model is selected based on live scoring and long-term consistency. Each model consists of 1,000 simulated price paths in each of the two forecast horizons: 1-hour (high-frequency) and 24-hour (low-frequency). The 1-hour forecast is designed for short-term trading, execution timing, and microstructure-aware strategies, while the 24-hour forecast supports broader positioning, risk management, 0DTE options. * **Full probability distributions** — Understand the complete range of possible outcomes * **Confidence intervals** — Quantify uncertainty in your predictions * **Risk-adjusted insights** — Make decisions based on probability, not guesses * **Realistic market dynamics** — Captures volatility clustering, fat tails, and mean reversion ### Powered by The World's Highest Paying Data Science Competition Synth runs on Bittensor **Subnet 50**, where 200+ machine learning models compete to generate the most accurate forecasts: * **Continuous competition** — Data scientists are scored using CRPS (Continuous Ranked Probability Score) * **Quality over quantity** — Only top-performing data scientists contribute to API responses * **No single point of failure** — Decentralized architecture ensures reliability * **Transparent performance** — All data scientists scores are publicly auditable ### Battle-Tested Accuracy All predictions are evaluated against actual outcomes using industry-standard metrics: * **CRPS scoring** — Measures both calibration and sharpness of probabilistic forecasts * **Real-time validation** — Data scientists are continuously scored against benchmark volatility metrics such as GARCH and GBM * **Leaderboard transparency** — Track top performers and their accuracy over time ## Multi-Asset Coverage The API consolidates predictions across multiple asset classes: * **Cryptocurrencies**: BTC, ETH, SOL, HYPE, XRP * **Commodities**: Gold (XAU), Oil (WTIOIL) * **Equities**: S\&P 500 (SPY), NVIDIA (NVDA), GOOGL (GOOGL), TSLA (TSLA), AAPL (AAPL), SPACEX (SPCX) ### Meta-Model Synth miners produce forecasts and are scored by the validator on Bittensor. Then, they are ranked into two leaderboards, for the two time horizons: * **high-frequency leaderboard:** forecasts are 1h forward looking and with 1 minute increment. They are updated every 12 minutes, * **daily leaderboard:** forecasts are 24h long and with 5 minutes increment. They are updated every hour. From those 2 leaderboards, we define meta-leaderboards: aggregation of scores over a period, for better stability and considering forecast quality over time. The default meta-leaderboard are defined as: * **high-frequency meta-leaderboard:** 6-days aggregated scores * **daily meta-leaderboard:** 14-days aggregated scores On the REST API, the query parameter `days` controls the number of days to aggregate. ### Forecast Horizons All endpoints support two prediction horizons, controlled by the `horizon` query parameter: | **1-Hour** | `1h` | 60 seconds | 3,600s (1h) | Scalping, prediction markets, HFT signals | | ----------- | ----- | ------------------- | ------------- | ------------------------------------------------------------ | | **24-Hour** | `24h` | 300 seconds (5 min) | 86,400s (24h) | 0DTE options pricing, LP range optimization, risk management | If `horizon` is omitted, the API defaults to `24h`. The 1-hour horizon uses the top-performing miners from the **high-frequency meta-leaderboard**, while the 24-hour horizon uses the **daily meta-leaderboard** — each optimized for their respective timeframe. Miner real-time performance dashboard can be found here: ## Advanced Analytics & Insights Beyond raw predictions, Synth transforms probabilistic forecasts into actionable intelligence. ### Prediction Market Intelligence * Comparison with Polymarket prediction markets * Cross-market arbitrage opportunities ### Volatility Analysis * Forward-looking and realized volatility metrics * Price distribution percentiles over forecast horizon * Historical volatility context ### Options Pricing * Theoretical call and put prices derived from ensemble forecasts * Multi-strike coverage around current price ### Risk Management * Liquidation probability analysis for leveraged positions * Dynamic stop-loss levels from price distributions * Tail risk assessments ### DeFi Optimization * Optimal liquidity provider (LP) ranges for Uniswap V3 and other CLAMMs * Impermanent loss estimates * Probability of staying within LP bounds ## Use Cases ### Quantitative Trading Build sophisticated trading strategies using probability distributions: * **Market divergence detection** — Identify mis-priced contracts in prediction markets when implied probabilities diverge from Synth forecasts * **Position sizing** — Use Kelly Criterion with probabilistic forecasts * **Risk management** — Set stop-losses at confidence intervals ### Options Trading Price and trade options with theoretical fair values: * **Find mispriced options** — Compare Synth prices vs. market * **Construct spreads** — Optimize bull/bear spreads * **Hedge portfolios** — Calculate optimal hedge ratios ### Risk Management Monitor and manage portfolio risk in real-time: * **Liquidation monitoring** — Track leveraged position risk * **Portfolio VaR** — Calculate value-at-risk across assets * **Tail risk** — Understand extreme outcome probabilities ### AI & Automation Integrate with AI agents and trading bots: * **LLM integration** — Connect to Claude, GPT-4, or other AI models * **Autonomous trading** — Build AI-powered trading systems * **Natural language analysis** — Generate market commentary ### DeFi Strategies Optimize yield farming and liquidity provision: * **LP range optimization** — Set optimal Uniswap V3 ranges * **Impermanent loss forecasting** — Estimate IL before providing liquidity * **Yield comparison** — Compare expected returns across pools ## API Structure ### REST API Get started [here](/getting-started/rest-api). ### Websocket API Get started [here](/websocket-api). ### Main Endpoint Categories Prediction Percentiles — Core probabilistic forecasts * `/insights/prediction-percentiles` — Prediction percentiles (1H & 24H) Insights — Advanced analytics * `/insights/volatility` — Volatility metrics * `/insights/option-pricing` — Options prices * `/insights/liquidation` — Liquidation probabilities * `/insights/lp-bounds` — LP range optimization * `/insights/polymarket/*` — Prediction market comparisons (Polymarket) * `/insights/limitless/*` — Prediction market comparisons (Limitless) ## Support & Community * **Documentation**: You're reading it * **Discord**: [Join our community](https://discord.gg/bittensor) (Scroll down the Bittensor channels to Synth) * **GitHub**: [mode-network/synth-subnet](https://github.com/mode-network/synth-subnet) * **API Specification:** * **Email**: # Getting Started Get up and running with Synth API in minutes. 💡 **Tip:** Some insights have optional `horizon=1h` that can be requested for high frequency 1-hour predictions instead of the default 24-hour horizon. 
curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC&horizon=1h" -H "Authorization: Apikey YOUR_API_KEY"
## What You'll Need {% stepper %} {% step %} ### API Key Get an API key from your [Synth Dashboard](https://dashboard.synthdata.co/). {% endstep %} {% step %} ### Make a Request ```bash curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endstep %} {% step %} ### Parse the Response ```python import requests response = requests.get( "https://api.synthdata.co/insights/prediction-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() current_price = data['current_price'] percentiles = data['forecast_future']['percentiles'] # Get 24h forecast final = percentiles[-1] median = final['0.5'] lower = final['0.05'] upper = final['0.95'] print(f"Current: ${current_price:,.2f}") print(f"24h Median: ${median:,.2f}") print(f"24h 90% CI: ${lower:,.0f} - ${upper:,.0f}") ``` {% endstep %} {% endstepper %} ## Common Parameters | Parameter | Value | Description | | --------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `asset` | `BTC`, `ETH`, `SOL`, `HYPE`, `XRP`, `SPYX`, `XAU`, `WTIOIL` `NVDAX`, `AAPLX`, `GOOGLX`, `TSLAX`, `SPCX` | Asset to forecast | | `horizon` | `1h` `24h` | Forecast horizon, `1h` for high frequency, `24h` for low frequency | | `days` | `14` (default) | Days for meta-leaderboard ranking | | `limit` | `10` (default) | Number of top miners to use | # Authentication The Synth API uses API key authentication. All requests must include your API key in the `Authorization` header. ## Getting an API Key {% stepper %} {% step %} ### Login Go to your [Synth Dashboard](https://dashboard.synthdata.co/) {% endstep %} {% step %} ### Choose a plan Sign up for the Professional or Enterprise plan {% endstep %} {% step %} ### Generate key Generate a new API Key {% endstep %} {% endstepper %} ## Using Your API Key Include your API key in the `Authorization` header: ``` Authorization: Apikey YOUR_API_KEY ``` ### Example {% code title="curl" %} ```bash curl "https://api.synthdata.co/insights/volatility?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ## Security {% hint style="warning" %} * Never commit keys to version control * Use environment variables * Rotate keys regularly {% endhint %} {% code title="python" %} ```python import os api_key = os.environ.get("SYNTH_API_KEY") headers = {"Authorization": f"Apikey {api_key}"} ``` {% endcode %} # Credits and Pricing Synth API uses a monthly API subscription with credit based usage system. ## API Plans | Plan | API Credits | Requests/Day | Supported Assets | Time Horizon | User Type | | | | ----------------------------------- | --------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------- | - | - | | Standard $49 monthly | 100 one time credits | No ability to buy more credits | `BTC`, `ETH`, `SOL`, `XRP`, `HYPE`, `XAU`, `WTIOIL`, `SPYX`, `NVDAX`, `AAPLX`, `GOOGLX`, `TSLAX`, `SPCX` | `1h` `24h` | Traders | | | | Professional $199 monthly | 20000 credits monthly | Ability to buy more credits | `BTC`, `ETH`, `SOL`, `XRP`, `HYPE`, `XAU`, `WTIOIL`, `SPYX`, `NVDAX`, `AAPLX`, `GOOGLX`, `TSLAX`, `SPCX` | `1h` `24h` | Developers, Traders, Funds | | | | Professional unlimited $499 monthly | Unlimited | No ability to buy more credits | `BTC`, `ETH`, `SOL`, `XRP`, `HYPE`, `XAU`, `WTIOIL`, `SPYX`, `NVDAX`, `AAPLX`, `GOOGLX`, `TSLAX`, `SPCX` | `1h` `24h` | Developers, Traders, Funds | | | | Enterprise | Unlimited | Custom | Custom upon request | Custom upon request | Institutions | | | ## Rate Limits | Plan | Requests/Second | | ------------ | --------------- | | Standard | 10 | | Professional | 10 | | Enterprise | Custom | ## Endpoint Credit Cost For simplicity each API call to the Synth REST API is priced at 1 credit, and each Websocket message sent by server is priced at 1 credit. ## Pricing Details Visit for more information on our plans and their features ## FAQs **What happens if I run out of credits?** You can purchase additional credit blocks at any time to ensure your service is not interrupted. **How do I purchase more credits?** In your dashboard you will be able to make card payments for purchasing credits. We’ll use the same card you used for your subscription to process credit purchases. **How many credits does the Enterprise plan receive?** The Enterprise plan is a custom plan built for customers looking for specific use cases. **How do I track my credit usage?** You can track your credit usage on the dashboard. # Assets ## Cryptocurrencies | Symbol | Name | Price Oracle | | -------- | -------- | ------------------------------------------------------------- | | **BTC** | Bitcoin | | | **ETH** | Ethereum | | | **SOL** | Solana | | | **HYPE** | HYPE | | | **XRP** | XRP | | ## Commodities | Symbol | Name | Price Oracle | | ---------- | ---- | ------------------------------------------------------------- | | **XAU** | Gold | | | **WTIOIL** | Oil | | ## Equities (Tokenized 24/7 Asset)
SymbolNamePrice Oracle
SPYS&P 500 (xStock)https://insights.pyth.network/price-feeds/Crypto.SPYX%2FUSD
NVDANVIDIA (xStock)https://insights.pyth.network/price-feeds/Crypto.NVDAX%2FUSD
TSLATesla (xStock)https://insights.pyth.network/price-feeds/Crypto.TSLAX%2FUSD
AAPLApple (xStock)https://insights.pyth.network/price-feeds/Crypto.AAPLX%2FUSD
GOOGLGoogle (xStock)https://insights.pyth.network/price-feeds/Crypto.GOOGLX%2FUSD
SPCXSpaceX (xSTOCK)https://app.pyth.com/explore/Pyth.HL.SPCX%2FUSDC?returnUrl=%2Fexplore%3Fsearch%3Dspcx%26state%3Dstable
# REST API ### Base URL {% code title="Base URL" %} ``` https://api.synthdata.co ``` {% endcode %} ### Authentication {% hint style="info" %} All requests require an API key in the header: ``` Authorization: Apikey YOUR_API_KEY ``` {% endhint %} ### Make a Request ```bash curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` # Error Handling Handle errors gracefully when using Synth API. ## HTTP Status Codes | Code | Meaning | Action | | ---- | ---------------- | ------------------------------------- | | 200 | Success | Process response | | 400 | Bad Request | Check authentication header | | 401 | Unauthorized | Check API key | | 402 | Payment Required | Check subscription or billing status | | 404 | Not Found | Check parameters or data availability | | 429 | Rate Limited | Retry after delay | | 500 | Server Error | Retry later | ## Error Response Format Errors return JSON with a `message` field: ```json {"message": "Unauthorized"} ``` ```json {"message": "missing key in request header"} ``` Some endpoints return a plain string for data errors: ``` "No prediction available" ``` ## Best Practices {% code title="example.py" %} ```python import requests import time def fetch_percentiles(asset): response = requests.get( "https://api.synthdata.co/insights/prediction-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": asset} ) if response.status_code == 200: return response.json() elif response.status_code == 401: raise Exception("Invalid API key") elif response.status_code == 404: raise Exception(f"No data available for {asset}") elif response.status_code == 429: time.sleep(60) return fetch_percentiles(asset) # Retry else: response.raise_for_status() ``` {% endcode %} # Error Handling (old) Handle errors gracefully when using Synth API. ## HTTP Status Codes | Code | Meaning | Action | | ---- | ------------ | ------------------------------------- | | 200 | Success | Process response | | 400 | Bad Request | Check authentication header | | 401 | Unauthorized | Check API key | | 404 | Not Found | Check parameters or data availability | | 429 | Rate Limited | Retry after delay | | 500 | Server Error | Retry later | ## Error Response Format Errors return JSON with a `message` field: ```json {"message": "Unauthorized"} ``` ```json {"message": "missing key in request header"} ``` Some endpoints return a plain string for data errors: ```json "No prediction available" ``` ## Common Errors
Missing Authorization Header — Status: 400 ```json {"message": "missing key in request header"} ``` {% hint style="info" %} Solution: Add the `Authorization: Apikey YOUR_API_KEY` header. {% endhint %}
Invalid API Key — Status: 401 ```json {"message": "Unauthorized"} ``` {% hint style="info" %} Solution: Verify your API key in the dashboard. {% endhint %}
No Data Available — Status: 404 ```json "No prediction available" ``` {% hint style="info" %} Solution: Check that: * Asset is valid (`BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX`) * Required parameters are provided * For `/v2/prediction/latest`: miner UIDs are valid {% endhint %}
## Best Practices {% code title="example.py" %} ```python import requests import time def fetch_predictions(asset): response = requests.get( "https://api.synthdata.co/v2/prediction/best", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": asset, "time_increment": 300, "time_length": 86400} ) if response.status_code == 200: return response.json() elif response.status_code == 401: raise Exception("Invalid API key") elif response.status_code == 404: raise Exception(f"No data available for {asset}") elif response.status_code == 429: time.sleep(60) return fetch_predictions(asset) # Retry else: response.raise_for_status() ``` {% endcode %} # Glossary **API Key** - Token for authentication **CRPS** - Continuous Ranked Probability Score (lower is better) **Ensemble** - Collection of 1,000 simulated price paths **Miner** - Network participant generating predictions **Percentile** - Price level below which X% of predictions fall **time\_increment** - Seconds between price points (300 or 60) **time\_length** - Total forecast duration (86400 or 3600) **Volatility** - Measure of price variation # MCP All Synth MCP tools support both 1-hour and 24-hour forecast horizons. When using tools like `get-prediction-percentiles`, `get-insights-volatility`, or `get-insights-option-pricing`, you can specify the horizon by passing `horizon=1h` or `horizon=24h` (default). MCP allows AI agents to integrate seamlessly to external data sources and tools. Synth API MCP is a remote MCP server at . There are 2 authentications methods: * OAuth (coming soon) * API Key To authenticate the MCP with your API key, you need to add custom headers: * header key: Authorization * header value: Bearer \ ### Connect with Claude Desktop Download the Desktop Extension: [synth.mcpb](https://github.com/mode-network/synth-mcp/releases/download/v0.0.10/synth.mcpb). To add the extension double click on the file and Claude Desktop will ask you to install, and input your API key. ### Connect with Claude Code CLI Claude Code provides a CLI to use the agentic coding tool of Anthropic. Read more [here](https://code.claude.com/docs/en/overview#terminal). To add the SynthData MCP server, type the command: ```shellscript claude mcp add --transport http synthdata https://mcp.synthdata.co/v1/mcp/apikey/json --header "Authorization: Bearer " ``` ### Connect with mcp-remote mcp-remote is a tool that allows you to install a remote MCP server for a local MCP client. It creates a local STDIO MCP to proxies to the remote HTTP Stream Synth MCP. Read more [here](https://www.npmjs.com/package/mcp-remote). Type the command to add the Synth MCP: ```shellscript npx -y mcp-remote https://mcp.synthdata.co/v1/mcp/apikey/json --header "Authorization: Bearer " --allow-http ``` ### Connect with Vercel AI SDK Vercel AI SDK supports connecting to remote MCP servers. Read more [here](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools). ```typescript const mcpClient = await createMCPClient({ transport: { type: "http", url: "https://mcp.synthdata.co/v1/mcp/apikey/json", headers: { Authorization: `Bearer ${process.env.SYNTH_API_KEY}` }, }, }); const tools = await mcpClient.tools(); const result = streamText({ model: gateway(modelId), tools, system: "You are an agent working with SynthData's MCP.", messages: convertToModelMessages(messages), onError: (e) => { console.error("Error while streaming.", e); }, }); ``` ### Connect with OpenAI OpenAI platform allows you to connect to MCP server: 1. go to the Open AI Platform: 2. on the tools configuration, click "Add" 3. chose "MCP server" 4. click on "+ Server" button 5. input the url: 6. chose a label: synth 7. on authentication, select "Custom headers" 8. type "Authorization" in the header input 9. type "Bearer \" in the value input, change with your API key that you create here [https://dashboard.synthdata.co/api-keys](https://dashboard.synthdata.co/api-keys/) 10. Click on "Connect" You can now prompt the LLM and ask for Synth Insights. # Websocket API All insights are available in websocket. They are refreshed every 15 or 35 seconds depending on the asset. Websocket server will push the new version at each refresh. An API credit is then consume at each server push. ### Base URL {% code title="Base URL" %} ``` wss://api.synthdata.co/ws ``` {% endcode %} ### Authentication {% hint style="info" %} All requests require an API key in the query parameters: ``` apikey=YOUR_API_KEY ``` {% endhint %} ### Example ```html Synth WebSocket API

``` # REST API REST API for real-time and historical market forecasts (liquidation risk, LP ranges, volatility, option pricing, price distributions) and prediction market comparisons against Polymarket and Limitless. ## Content [Authentication](#authentication) [Insights Endpoints](#insights-endpoints) [Polymarket Insights](#polymarket-insights) [Limitless Insights](#limitless-insights) [Leaderboard Endpoints](#leaderboard-endpoints) [Meta-Leaderboard Endpoints](#meta-leaderboard-endpoints) ## Authentication **Insights endpoints** require an API key in the `Authorization` header: ``` Authorization: Apikey MY_API_KEY ``` Credits are consumed per request. Requests are rate-limited.\ Read [here](/getting-started/authentication) how to get your API key. **Leaderboard and meta-leaderboard endpoints** are public (no authentication required), but are rate-limited. ## Insights Endpoints ### Common input parameters All `/insights/*` endpoints accept the same three query parameters: | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset` | string | No | Asset symbol to query. If omitted, defaults to `BTC`. See each endpoint for the supported assets list. Note: `SPY`, `NVDA`, `GOOGL`, `TSLA`, `AAPL` are silently remapped to their cross-listed variants (`SPYX`, `NVDAX`, `GOOGLX`, `TSLAX`, `AAPLX`). | | `horizon` | string | No | Forecast time window. `"1h"` for next-hour, `"24h"` for next-day. Each endpoint documents its default. | | `start_time` | string | No | ISO 8601 timestamp (e.g. `2024-01-02T15:04:05Z`). If provided, returns historical data from that point in time. If omitted, returns the latest available data. | ### GET /insights/liquidation Provides the probability of long and short position liquidations at various price levels over 6, 12, 18, and 24 hour windows. Useful for assessing leverage risk, setting stop-loss levels, and managing margin exposure. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "data": [ { "price_change": "5%", "long_liquidation_probability": { "6": 0.12, "12": 0.18, "18": 0.23, "24": 0.27 }, "short_liquidation_probability": { "6": 0.03, "12": 0.05, "18": 0.07, "24": 0.09 } } ] } ``` | Field | Type | Description | | -------------------------------------- | ------------ | ------------------------------------------------------------------------------------ | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `data` | array | One entry per price-change scenario | | `data[].price_change` | string | Hypothetical price move relative to current, e.g. `"-5%"` or `"+10%"` | | `data[].long_liquidation_probability` | object | Probability that a long position is liquidated if the price moves by `price_change` | | `data[].short_liquidation_probability` | object | Probability that a short position is liquidated if the price moves by `price_change` | | `data[].*_probability."6"` | float \[0,1] | Probability of liquidation within 6 hours | | `data[].*_probability."12"` | float \[0,1] | Probability of liquidation within 12 hours | | `data[].*_probability."18"` | float \[0,1] | Probability of liquidation within 18 hours | | `data[].*_probability."24"` | float \[0,1] | Probability of liquidation within 24 hours | ### GET /insights/lp-bounds Returns price interval analysis for concentrated liquidity positioning. For each price interval, the response includes the probability of price staying within the range, expected time in-range, and estimated impermanent loss. Useful for AMM LP range selection, options strike placement, and range-bound strategies. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "data": [ { "interval": { "full_width": "10%", "lower_bound": 92625.0, "upper_bound": 102375.0 }, "expected_time_in_interval": 0.72, "expected_impermanent_loss": 0.0031, "probability_to_stay_in_interval": { "24": 0.68 } } ] } ``` | Field | Type | Description | | --------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `data` | array | One entry per price interval | | `data[].interval.full_width` | string | Total width of the interval as a percentage, e.g. `"10%"` means ±5% around current price | | `data[].interval.lower_bound` | float | Lower price boundary of the interval | | `data[].interval.upper_bound` | float | Upper price boundary of the interval | | `data[].expected_time_in_interval` | float \[0,1] | Expected fraction of the 24h horizon that price spends inside this interval | | `data[].expected_impermanent_loss` | float | Expected impermanent loss as a fraction for an LP position held within this interval over the horizon | | `data[].probability_to_stay_in_interval."24"` | float \[0,1] | Probability that price stays within the interval for the full 24h horizon without touching either boundary | ### GET /insights/lp-probabilities Returns the probability that an asset's price will be above or below specific price targets at the end of the 24h horizon. Covers 11 upside and 11 downside price levels relative to current price. Useful for directional bet pricing, options delta estimation, and Polymarket up/down contract calibration. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "data": { "24h": { "probability_above": { "100000": 0.42, "105000": 0.21 }, "probability_below": { "95000": 0.38, "90000": 0.18 } } } } ``` | Field | Type | Description | | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `data."24h".probability_above` | object | Keys are price levels (as strings); values are the probability \[0,1] that the asset price ends **above** that level at horizon end | | `data."24h".probability_below` | object | Keys are price levels (as strings); values are the probability \[0,1] that the asset price ends **below** that level at horizon end | ### GET /insights/option-pricing Returns theoretical option prices computed from SynthData's ensemble volatility forecasts. Covers call and put prices across a range of strike prices. Use to compare against market-quoted premiums to find mispriced options. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "expiry_time": "2024-01-03T00:00:00Z", "call_options": { "95000": 3200.0, "100000": 1100.0 }, "put_options": { "95000": 750.0, "100000": 2200.0 } } ``` | Field | Type | Description | | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `expiry_time` | ISO 8601 | Option expiry timestamp used for pricing | | `call_options` | object | Keys are strike prices (as strings); values are the theoretical call option price in the asset's quote currency | | `put_options` | object | Keys are strike prices (as strings); values are the theoretical put option price in the asset's quote currency | ### GET /insights/volatility Returns SynthData's volatility forecasts alongside historical realized volatility. Useful for vol-targeting strategies, premium calibration, and regime detection. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "realized": { "prices": [ { "price": 96000.0, "returns": 0.0031 }, { "price": 97500.0, "returns": null } ], "volatility": [0.021, null], "average_volatility": 0.021 }, "forecast_past": { "volatility": [0.019, 0.022], "average_volatility": 0.0205 }, "forecast_future": { "volatility": [0.023, 0.025], "average_volatility": 0.024 } } ``` | Field | Type | Description | | ------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `realized.prices` | array | Historical price observations leading up to forecast time | | `realized.prices[].price` | float | Asset price at this observation | | `realized.prices[].returns` | float or null | Log return between this and the previous observation; null for the most recent point where the next price is not yet known | | `realized.volatility` | array of float or null | Rolling realized volatility for each observation period; null when not yet computable (e.g. at the latest point) | | `realized.average_volatility` | float | Average realized volatility across the observation window | | `forecast_past.volatility` | array of float | Model-predicted volatility for time periods that have already elapsed (backtested values) | | `forecast_past.average_volatility` | float | Average of `forecast_past.volatility` | | `forecast_future.volatility` | array of float | Model-predicted volatility for upcoming time periods | | `forecast_future.average_volatility` | float | Average of `forecast_future.volatility` | ### GET /insights/volatility-percentiles Returns the full volatility distribution split into percentile buckets, for both the historical (past) and upcoming (future) forecast windows, alongside realized price observations. Useful for understanding the range and asymmetry of expected volatility. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "realized": { "prices": [ { "price": 96000.0, "returns": 0.0031 }, { "price": 97500.0, "returns": null } ] }, "forecast_past": { "percentiles": [ { "0.005": 0.009, "0.05": 0.012, "0.2": 0.016, "0.35": 0.019, "0.5": 0.021, "0.65": 0.024, "0.8": 0.028, "0.95": 0.035, "0.995": 0.047 } ] }, "forecast_future": { "percentiles": [ { "0.005": 0.010, "0.05": 0.013, "0.2": 0.017, "0.35": 0.020, "0.5": 0.023, "0.65": 0.026, "0.8": 0.030, "0.95": 0.038, "0.995": 0.052 } ] } } ``` | Field | Type | Description | | ----------------------------- | ------------- | ------------------------------------------------------------------ | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price used for the calculation | | `realized.prices` | array | Historical price observations leading up to forecast time | | `realized.prices[].price` | float | Asset price at this observation | | `realized.prices[].returns` | float or null | Log return from previous observation; null for the latest point | | `forecast_past.percentiles` | array | One object per historical time step | | `forecast_future.percentiles` | array | One object per upcoming forecast time step | | `percentiles[]."0.005"` | float | Volatility at the 0.5th percentile — extreme low-vol scenario | | `percentiles[]."0.05"` | float | Volatility at the 5th percentile | | `percentiles[]."0.2"` | float | Volatility at the 20th percentile | | `percentiles[]."0.35"` | float | Volatility at the 35th percentile | | `percentiles[]."0.5"` | float | Median (50th percentile) volatility — central estimate | | `percentiles[]."0.65"` | float | Volatility at the 65th percentile | | `percentiles[]."0.8"` | float | Volatility at the 80th percentile | | `percentiles[]."0.95"` | float | Volatility at the 95th percentile | | `percentiles[]."0.995"` | float | Volatility at the 99.5th percentile — extreme high-vol scenario | ### GET /insights/prediction-percentiles Returns the full price distribution at the end of the forecast horizon, expressed as percentiles derived from the ensemble of the top 10 miners' predictions. Each percentile gives a predicted price level, giving you the complete probability distribution of expected price movements. Useful for position sizing, setting price targets, and tail-risk assessment. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "current_price": 97500.0, "forecast_future": { "percentiles": [ { "0.005": 88200.0, "0.05": 91000.0, "0.2": 94500.0, "0.35": 96200.0, "0.5": 97800.0, "0.65": 99400.0, "0.8": 101500.0, "0.95": 105000.0, "0.995": 112000.0 } ] } } ``` | Field | Type | Description | | ----------------------------- | ----- | ----------------------------------------------------------------------------- | | `current_price` | float | Asset spot price at the time of forecast | | `forecast_future.percentiles` | array | One object per forecast time step | | `percentiles[]."0.005"` | float | Predicted asset **price** at the 0.5th percentile — extreme downside scenario | | `percentiles[]."0.05"` | float | Predicted price at the 5th percentile | | `percentiles[]."0.2"` | float | Predicted price at the 20th percentile | | `percentiles[]."0.35"` | float | Predicted price at the 35th percentile | | `percentiles[]."0.5"` | float | Median (50th percentile) predicted price — central estimate | | `percentiles[]."0.65"` | float | Predicted price at the 65th percentile | | `percentiles[]."0.8"` | float | Predicted price at the 80th percentile | | `percentiles[]."0.95"` | float | Predicted price at the 95th percentile | | `percentiles[]."0.995"` | float | Predicted price at the 99.5th percentile — extreme upside scenario | ## Polymarket Insights These endpoints combine SynthData's probability forecasts with live Polymarket market data, making it easy to compare model estimates against market-implied probabilities. ### GET /insights/polymarket/up-down/daily Synth vs Polymarket probabilities for **daily** Up/Down contracts — whether the asset closes higher or lower than its opening price by end of UTC day. **Supported assets:** BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, SPCX, XRP, HYPE, WTIOIL\ **Default horizon:** 24h **Response** ```json { "forecast_start_time": "2024-01-02T15:04:05Z", "current_price": 97500.0, "current_time": "2024-01-02T15:10:00Z", "start_price": 96800.0, "slug": "will-btc-go-up-jan-02", "event_creation_time": "2024-01-02T00:00:00Z", "event_start_time": "2024-01-02T00:00:00Z", "event_end_time": "2024-01-03T00:00:00Z", "synth_probability_up": 0.61, "synth_outcome": "UP", "polymarket_probability_up": 0.58, "polymarket_outcome": "UP", "market_probability_up": 0.59, "market_outcome": "UP", "current_outcome": "UP", "best_bid_price": 0.57, "best_bid_size": 250.0, "best_ask_price": 0.59, "best_ask_size": 180.0, "polymarket_last_trade_price": 0.58, "polymarket_last_trade_time": "2024-01-02T15:08:00Z", "polymarket_last_trade_outcome": "UP" } ``` | Field | Type | Description | | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_price` | float | Asset spot price at query time | | `current_time` | ISO 8601 | Wall-clock time of the data snapshot | | `start_price` | float | Asset price at the start of the event period — the reference for determining up/down at resolution | | `slug` | string | Polymarket market identifier slug | | `event_creation_time` | ISO 8601 | When the Polymarket market was created | | `event_start_time` | ISO 8601 | Start of the event window | | `event_end_time` | ISO 8601 | End of the event window — when the market resolves | | `synth_probability_up` | float \[0,1] | SynthData's estimated probability that the asset price ends higher than `start_price` | | `synth_outcome` | string | SynthData's predicted outcome based on its probability: `"UP"` or `"DOWN"` | | `polymarket_probability_up` | float \[0,1] | Polymarket's implied probability derived from the last trade | | `polymarket_outcome` | string | Polymarket's current consensus outcome: `"UP"` or `"DOWN"` | | `market_probability_up` | float \[0,1] | Same as `polymarket_probability_up` (for retrocompatibility) | | `market_outcome` | string | Same as `polymarket_outcome` (for retrocompatibility) | | `current_outcome` | string | What the outcome would be if the event resolved right now, based on `current_price` vs `start_price`: `"UP"` or `"DOWN"` | | `best_bid_price` | float | Best bid price in the Polymarket order book (probability units, 0–1) | | `best_bid_size` | float | Dollar size available at the best bid | | `best_ask_price` | float | Best ask price in the Polymarket order book (probability units, 0–1) | | `best_ask_size` | float | Dollar size available at the best ask | | `polymarket_last_trade_price` | float | Price of the most recent trade executed on Polymarket | | `polymarket_last_trade_time` | ISO 8601 | Timestamp of the most recent Polymarket trade | | `polymarket_last_trade_outcome` | string | Outcome side of the most recent trade: `"UP"` or `"DOWN"` | ### GET /insights/polymarket/up-down/hourly Synth vs Polymarket probabilities for **hourly** Up/Down contracts. Same response structure as `/insights/polymarket/up-down/daily`. **Supported assets:** BTC, ETH, SOL, HYPE\ **Default horizon:** 1h **Response** — same fields as `/insights/polymarket/up-down/daily` above, with `event_start_time` / `event_end_time` spanning one hour. ### GET /insights/polymarket/up-down/15min Synth vs Polymarket probabilities for **15-minute** Up/Down contracts. Same response structure as `/insights/polymarket/up-down/daily`. **Supported assets:** BTC, ETH, SOL, HYPE\ **Default horizon:** 1h **Response** — same fields as `/insights/polymarket/up-down/daily` above, with `event_start_time` / `event_end_time` spanning 15 minutes. ### GET /insights/polymarket/up-down/5min Synth vs Polymarket probabilities for **5-minute** Up/Down contracts. Same response structure as `/insights/polymarket/up-down/daily`. **Supported assets:** BTC, ETH, SOL, HYPE\ **Default horizon:** 1h **Response** — same fields as `/insights/polymarket/up-down/daily` above, with `event_start_time` / `event_end_time` spanning 5 minutes. ### GET /insights/polymarket/range/daily Returns Synth vs Polymarket probabilities for **daily price range** contracts — whether the asset's closing price falls within a specific numeric range. **Supported assets:** BTC, ETH, SOL, NVDA, GOOGL, TSLA, AAPL, XRP\ **Default horizon:** 24h **Response** — array, one object per range market currently active for the requested asset: ```json [ { "forecast_start_time": "2024-01-02T15:04:05Z", "current_time": "2024-01-02T15:10:00Z", "current_price": 97500.0, "slug": "btc-price-range-jan-02-95k-100k", "title": "Will BTC be between $95k–$100k?", "cmp_type": "range", "ref_prices": [95000.0, 100000.0], "event_creation_time": "2024-01-02T00:00:00Z", "event_start_time": "2024-01-02T00:00:00Z", "event_end_time": "2024-01-03T00:00:00Z", "synth_probability": 0.44, "synth_outcome": 1, "polymarket_probability": 0.41, "polymarket_outcome": 1, "current_outcome": 1, "best_bid_price": 0.40, "best_bid_size": 120.0, "best_ask_price": 0.42, "best_ask_size": 95.0, "polymarket_last_trade_price": 0.41, "polymarket_last_trade_time": "2024-01-02T15:07:00Z", "polymarket_last_trade_outcome": 1 } ] ``` | Field | Type | Description | | ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_time` | ISO 8601 | Wall-clock time of the data snapshot | | `current_price` | float | Asset spot price at query time | | `slug` | string | Polymarket market identifier slug | | `title` | string | Human-readable market question as shown on Polymarket | | `cmp_type` | string | Contract semantics: `"range"` (price between two values), `"above"` (price above a threshold), or `"hit"` (price touches a level at any point during the window) | | `ref_prices` | array of float | Reference price(s) defining the range or threshold. Two values for `"range"`, one value for `"above"` and `"hit"` | | `event_creation_time` | ISO 8601 | When the Polymarket market was created | | `event_start_time` | ISO 8601 | Start of the event window | | `event_end_time` | ISO 8601 | End of the event window — when the market resolves | | `synth_probability` | float \[0,1] | SynthData's estimated probability that the market resolves YES | | `synth_outcome` | int | SynthData's predicted outcome: `1` = YES, `0` = NO | | `polymarket_probability` | float \[0,1] | Polymarket's implied YES probability derived from the last trade | | `polymarket_outcome` | int | Polymarket's current consensus outcome: `1` = YES, `0` = NO | | `current_outcome` | int | What the outcome would be if the market resolved right now: `1` = YES, `0` = NO | | `best_bid_price` | float or null | Best bid in the Polymarket order book (probability units); null if no active order book | | `best_bid_size` | float or null | Dollar size at the best bid; null if no active order book | | `best_ask_price` | float or null | Best ask in the Polymarket order book (probability units); null if no active order book | | `best_ask_size` | float or null | Dollar size at the best ask; null if no active order book | | `polymarket_last_trade_price` | float | Price of the most recent trade on Polymarket | | `polymarket_last_trade_time` | ISO 8601 | Timestamp of the most recent Polymarket trade | | `polymarket_last_trade_outcome` | int | Outcome side of the most recent trade: `1` = YES, `0` = NO | ### GET /insights/polymarket/above/daily Returns Synth vs Polymarket probabilities for daily **"asset above $X"** threshold contracts. The response is an array with the same fields as `/insights/polymarket/range`. `cmp_type` will always be `"above"` and `ref_prices` contains a single threshold value. **Supported assets:** BTC, ETH\ **Default horizon:** 24h ### GET /insights/polymarket/hit/daily Returns Synth vs Polymarket probabilities for daily **"will asset hit $X"** contracts. The market resolves YES if the asset touches the target price at **any point** during the event window (path-dependent, not just at expiry). The response is an array with the same fields as `/insights/polymarket/range`. `cmp_type` will always be `"hit"`. **Supported assets:** BTC, ETH, XRP\ **Default horizon:** 24h ## Limitless Insights These endpoints combine SynthData's probability forecasts with live Limitless prediction market data. ### GET /insights/limitless/daily Synth vs Limitless probabilities for **daily** up/down contracts. **Supported assets:** BTC, ETH, SOL, XAU, HYPE, XRP\ **Default horizon:** 24h **Response** — array, one object per Limitless market active for the requested asset: ```json [ { "forecast_start_time": "2024-01-02T15:04:05Z", "current_time": "2024-01-02T15:10:00Z", "current_price": 97500.0, "start_price": 96800.0, "slug": "btc-up-jan-02", "event_creation_time": "2024-01-02T00:00:00Z", "event_end_time": "2024-01-03T00:00:00Z", "event_outcome_prices": [0.0, 1.0], "synth_probability_up": 0.61, "synth_outcome": "UP", "market_probability_up": 0.58, "market_outcome": "UP", "best_bid_price": 0.57, "best_ask_price": 0.59 } ] ``` | Field | Type | Description | | ----------------------- | -------------- | -------------------------------------------------------------------------------------------------- | | `forecast_start_time` | ISO 8601 | Start time of the Monte Carlo simulation used for this calculation | | `current_time` | ISO 8601 | Wall-clock time of the data snapshot | | `current_price` | float | Asset spot price at query time | | `start_price` | float | Asset price at the start of the event period — the reference for determining up/down at resolution | | `slug` | string | Limitless market identifier slug | | `event_creation_time` | ISO 8601 | When the Limitless market was created | | `event_end_time` | ISO 8601 | End of the event window — when the market resolves | | `event_outcome_prices` | array of float | Settlement payout prices for each possible outcome (e.g. `[0.0, 1.0]` for binary NO/YES) | | `synth_probability_up` | float \[0,1] | SynthData's estimated probability that the asset price ends higher than `start_price` | | `synth_outcome` | string | SynthData's predicted outcome: `"UP"` or `"DOWN"` | | `market_probability_up` | float or null | Limitless market's implied probability; null if no market data is available | | `market_outcome` | string | Limitless market consensus outcome: `"UP"` or `"DOWN"` | | `best_bid_price` | float or null | Best bid price on Limitless (probability units, 0–1); null if no active order book | | `best_ask_price` | float or null | Best ask price on Limitless (probability units, 0–1); null if no active order book | ### GET /insights/limitless/hourly Synth vs Limitless probabilities for **hourly** contracts. Same response structure as `/insights/limitless/daily`. **Supported assets:** BTC, ETH, SOL, XAU\ **Default horizon:** 1h **Response** — same fields as `/insights/limitless/daily` above, with `event_end_time` one hour after `event_creation_time`. ### GET /insights/limitless/15min Synth vs Limitless probabilities for **15-minute** contracts. Same response structure as `/insights/limitless/daily`. **Supported assets:** BTC, ETH, SOL\ **Default horizon:** 1h **Response** — same fields as `/insights/limitless/daily` above, with `event_end_time` 15 minutes after `event_creation_time`. ## Leaderboard Endpoints The leaderboard ranks miners on the Bittensor subnet by their prediction performance. Two API versions exist: V1 (legacy) and V2 (current). ### GET /leaderboard/latest *(V1, legacy)* Returns the current leaderboard snapshot with full on-chain metrics. **Auth:** None\ **Query parameters:** None **Response** — array, one object per miner: ```json [ { "updated_at": "2024-01-02T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "incentive": 0.0031, "emission": 0.00012, "stake": 10500.0, "rank": 0.98, "pruning_score": 0.87 } ] ``` | Field | Type | Description | | --------------- | ------------ | --------------------------------------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of the last data update recorded for this miner | | `neuron_uid` | int | Miner's UID on the Bittensor subnet — unique slot identifier | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner is registered under | | `incentive` | float \[0,1] | Bittensor incentive score — proportion of total subnet incentive flowing to this miner | | `emission` | float | TAO token emission rate for this miner per block | | `stake` | float | Amount of TAO staked on this miner by nominators | | `rank` | float \[0,1] | Bittensor rank score — relative standing on the subnet | | `pruning_score` | float \[0,1] | Pruning score; miners with consistently low scores are eligible to be replaced by new registrations | ### GET /leaderboard/historical *(V1, legacy)* Returns historical leaderboard snapshots between two timestamps. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------------------------- | | `start_time` | string | Yes | ISO 8601 timestamp to start from (e.g. `2025-02-03T10:19:04Z`) | | `end_time` | string | Yes | ISO 8601 timestamp to end at | **Response** — array of snapshots in the requested window. Each item has the same fields as `/leaderboard/latest`: ```json [ { "updated_at": "2024-01-02T12:00:00Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "incentive": 0.0029, "emission": 0.00011, "stake": 10200.0, "rank": 0.97, "pruning_score": 0.85 } ] ``` | Field | Type | Description | | --------------- | ------------ | --------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of this historical snapshot | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner was registered under at this point in time | | `incentive` | float \[0,1] | Bittensor incentive score at this snapshot | | `emission` | float | TAO emission rate at this snapshot | | `stake` | float | TAO staked on this miner at this snapshot | | `rank` | float \[0,1] | Bittensor rank score at this snapshot | | `pruning_score` | float \[0,1] | Pruning score at this snapshot | ### GET /v2/leaderboard/latest Returns the current leaderboard with prediction-reward-focused metrics. Supports filtering by prompt type (24h vs 1h horizon). **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- | | `prompt_name` | string | No | `"low"` | `"low"` for the 24h prediction prompt; `"high"` for the 1h prediction prompt | **Response** — array, one object per miner: ```json [ { "updated_at": "2024-01-02T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "rewards": 0.0041 } ] ``` | Field | Type | Description | | ------------ | -------- | -------------------------------------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of the last data update recorded for this miner | | `neuron_uid` | int | Miner's UID on the Bittensor subnet — unique slot identifier | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner is registered under | | `rewards` | float | Prediction reward score for the selected prompt type — higher means better forecasting performance | ### GET /v2/leaderboard/historical Returns historical V2 leaderboard snapshots between two timestamps, filtered by prompt type. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | ------- | ---------------------------------------------- | | `start_time` | string | Yes | — | ISO 8601 timestamp to start from | | `end_time` | string | Yes | — | ISO 8601 timestamp to end at | | `prompt_name` | string | No | `"low"` | `"low"` for 24h prompt; `"high"` for 1h prompt | **Response** — array of snapshots in the requested window. Each item has the same fields as `/v2/leaderboard/latest`: ```json [ { "updated_at": "2024-01-02T12:00:00Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "rewards": 0.0038 } ] ``` | Field | Type | Description | | ------------ | -------- | --------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of this historical snapshot | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner was registered under at this point in time | | `rewards` | float | Prediction reward score at this snapshot for the selected prompt type | ## Meta-Leaderboard Endpoints The meta-leaderboard aggregates miner performance over a rolling window of days rather than a single snapshot. This smooths out noise and provides a more stable ranking. ### GET /meta-leaderboard/latest *(V1, legacy)* Returns the current meta-leaderboard, aggregating on-chain metrics over the past N days. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | --------- | ---- | -------- | ------- | ------------------------------------- | | `days` | int | No | `14` | Number of past days to aggregate over | **Response** — array, one object per miner. Same fields as `/leaderboard/latest`: ```json [ { "updated_at": "2024-01-02T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "incentive": 0.0031, "emission": 0.00012, "stake": 10500.0, "rank": 0.98, "pruning_score": 0.87 } ] ``` | Field | Type | Description | | --------------- | ------------ | ----------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of the last data update for this miner | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner is registered under | | `incentive` | float \[0,1] | Aggregated Bittensor incentive score over the `days` window | | `emission` | float | Aggregated TAO emission over the `days` window | | `stake` | float | TAO staked on this miner | | `rank` | float \[0,1] | Aggregated rank score over the `days` window | | `pruning_score` | float \[0,1] | Aggregated pruning score over the `days` window | ### GET /meta-leaderboard/historical *(V1, legacy)* Returns historical meta-leaderboard snapshots starting from a given point in time. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | ------------ | ------ | -------- | ------- | ------------------------------------------------- | | `start_time` | string | Yes | — | ISO 8601 timestamp to start from | | `days` | int | No | `14` | Number of days of aggregation window per snapshot | **Response** — array of historical snapshots. Each item has the same fields as `/meta-leaderboard/latest`: ```json [ { "updated_at": "2024-01-01T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "incentive": 0.0028, "emission": 0.00010, "stake": 10100.0, "rank": 0.96, "pruning_score": 0.84 } ] ``` | Field | Type | Description | | --------------- | ------------ | ------------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of this historical snapshot | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner was registered under at this point in time | | `incentive` | float \[0,1] | Aggregated incentive score over the `days` window ending at this snapshot | | `emission` | float | Aggregated emission over the `days` window ending at this snapshot | | `stake` | float | TAO staked at this snapshot | | `rank` | float \[0,1] | Aggregated rank over the `days` window ending at this snapshot | | `pruning_score` | float \[0,1] | Aggregated pruning score over the `days` window ending at this snapshot | ### GET /v2/meta-leaderboard/latest Returns the current V2 meta-leaderboard, aggregating prediction rewards over a rolling window. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `days` | int | No | `14` (or `6` when `prompt_name="high"`) | Number of past days to aggregate over. Defaults to 6 for the 1h prompt because its history is shorter. | | `prompt_name` | string | No | `"low"` | `"low"` for 24h prediction prompt; `"high"` for 1h prediction prompt | **Response** — array, one object per miner: ```json [ { "updated_at": "2024-01-02T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "rewards": 0.0041 } ] ``` | Field | Type | Description | | ------------ | -------- | -------------------------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of the last data update for this miner | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner is registered under | | `rewards` | float | Aggregated prediction reward score over the `days` window for the selected prompt type | ### GET /v2/meta-leaderboard/historical Returns historical V2 meta-leaderboard snapshots starting from a given point in time. **Auth:** None\ **Query parameters:** | Parameter | Type | Required | Default | Description | | ------------- | ------ | -------- | --------------------------------------- | ---------------------------------------------- | | `start_time` | string | Yes | — | ISO 8601 timestamp to start from | | `days` | int | No | `14` (or `6` when `prompt_name="high"`) | Aggregation window in days per snapshot | | `prompt_name` | string | No | `"low"` | `"low"` for 24h prompt; `"high"` for 1h prompt | **Response** — array of historical snapshots. Each item has the same fields as `/v2/meta-leaderboard/latest`: ```json [ { "updated_at": "2024-01-01T15:04:05Z", "neuron_uid": 42, "coldkey": "5GrwvaEF5L8zXAVGmSHFPewbkMCKuDsQKBLRsR5L9v9G", "ip_address": "1.2.3.4", "rewards": 0.0035 } ] ``` | Field | Type | Description | | ------------ | -------- | --------------------------------------------------------------------------------- | | `updated_at` | ISO 8601 | Timestamp of this historical snapshot | | `neuron_uid` | int | Miner's UID on the Bittensor subnet | | `coldkey` | string | Miner's Bittensor coldkey (SS58 wallet address) | | `ip_address` | string | IP address the miner was registered under at this point in time | | `rewards` | float | Aggregated prediction reward score over the `days` window ending at this snapshot | # Prediction Percentiles Get price distribution percentiles over the forecast horizon. ``` GET /insights/prediction-percentiles ``` ## Parameters | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- | | asset | string | Yes | — | Asset symbol: `BTC`, `ETH`, `SOL`, `HYPE`, `XRP`,`XAU`, `WTIOIL`, `SPY`, `NVDA`, `TSLA`, `AAPL`, `GOOGL` | | horizon | string | no | low | Forecast horizon: `1h` for 1-hour, `24h` for 24-hour. | | days | integer | No | 14 | Number of days to aggregate for the meta-leaderboard ranking | | limit | integer | No | 10 | Number of top miners from the meta-leaderboard to use for analysis | ## Headers | Header | Required | Description | | ------------- | -------- | ---------------------------------------- | | Authorization | Yes | API key in format: `Apikey YOUR_API_KEY` | {% hint style="info" %} Include your API key in the Authorization header exactly as shown: `Apikey YOUR_API_KEY`. {% endhint %} ## Example Requests {% code title="curl" %} ```bash curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} **Example Request (1-Hour Horizon)** ```bash curl "https://api.synthdata.co/insights/prediction-percentiles?asset=BTC&horizon=1h" \ -H "Authorization: Apikey YOUR_API_KEY" ``` ## Response {% code title="response.json" %} ```json { "current_price": 88996.66, "forecast_future": { "percentiles": [ { "0.005": 88996.66, "0.05": 88996.66, "0.2": 88996.66, "0.35": 88996.66, "0.5": 88996.66, "0.65": 88996.66, "0.8": 88996.66, "0.95": 88996.66, "0.995": 88996.66 }, { "0.005": 88631.35, "0.05": 88765.15, "0.2": 88879.70, "0.35": 88943.39, "0.5": 88998.23, "0.65": 89055.24, "0.8": 89122.30, "0.95": 89236.58, "0.995": 89359.79 } ] }, "forecast_past": { "percentiles": [...] }, "realized": { "prices": [...], "percentiles": [...] } } ``` {% endcode %} ## Field Descriptions | Field | Description | | ---------------------------- | -------------------------------------------------------------------------------------- | | current\_price | Current asset price | | forecast\_future.percentiles | Array of percentile objects, one per 5-minute time step (289 total for 24h, 61 for 1h) | | 0.005, 0.05, etc. | Price at that percentile (0.5 = median, 0.95 = 95th percentile) | | forecast\_past.percentiles | Historical percentile predictions | | realized.prices | Actual historical prices with returns | | realized.percentiles | Realized price percentiles | ## Response Codes | Code | Description | | ---- | ----------------------------------------- | | 200 | Success - returns percentile data | | 400 | Bad Request - invalid parameters | | 401 | Unauthorized - invalid or missing API key | | 500 | Internal Server Error | # Insights {% hint style="info" %} Advanced analytics derived from predictions. Requires Professional or Enterprise plan. {% endhint %} ## Parameters All endpoints support: * `asset` query parameter: BTC, ETH, XAU, SOL, SPY, NVDA, GOOGL, TSLA, AAPL, XRP, HYPE, WTIOIL * two prediction horizons, controlled by the `horizon` query parameter: `1h` , `24h`, * default value is 24h, unless for polymarket hourly and 15 minutes insights. * REST endpoint also support a `start_time` query parameter to fetch historical insights ## REST and Websocket API All endpoints are available via the [REST API](/#rest-api) (`https://api.synthdata.co`) and the [Websocket API](/#websocket-api) (`wss://api.synthdata.co/ws`). ## Insights ### Volatility Forecast and realized volatility metrics. Endpoints: * `/insights/volatility` * `/insights/prediction-percentiles` [View Volatility Documentation](/insights/volatility) ### Trading Liquidity provision optimization and prediction market comparisons. Endpoints: * `/insights/lp-bounds` * `/insights/lp-probabilities` [View Trading Documentation](#trading) ### Polymarket Compare Synth predictions against Polymarket prices. Endpoints: * `/insights/polymarket/up-down/daily` * `/insights/polymarket/up-down/hourly` * `/insights/polymarket/up-down/15min` * `/insights/polymarket/range` [View Polymarket Documentation](/insights/polymarket) ### Limitless Compare Synth predictions against Limitless prices. Endpoints: * `/insights/limitless/daily` * assets: `BTC`, `ETH`, `SOL`, `XRP`, `HYPE`, `XAU` * `/insights/limitless/hourly` * assets: `BTC`, `ETH`, `SOL`, `XAU` * `/insights/limitless/15min` * assets: `BTC`, `ETH`, `SOL` [View Limitless Documentation](https://docs.synthdata.co/insights/limitless) ### Options Theoretical option pricing from Monte Carlo simulations. Endpoints: * `/insights/option-pricing` [View Options Documentation](/insights/options) ### Risk Management Liquidation probabilities and position risk analysis. Endpoints: * `/insights/liquidation` [View Risk Management Documentation](/insights/risk-management) ### Historical Insights Accessing the historical data can be usefull to backtest strategies. Specify the start\_time parameter on the REST API Insights endpoints: ```bash curl -L 'https://api.synthdata.co/insights/limitless/hourly?asset=BTC&start_time=2026-03-28' \ -H 'Authorization: Apikey YOUR_API_KEY' ``` ### Quick Example {% code title="curl" %} ```bash curl "https://api.synthdata.co/insights/volatility?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} # Volatility GET /insights/volatility ### Parameters | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------- | | `asset` | string | Yes | — | Asset symbol: `BTC`, `ETH`, `SOL`, `HYPE`, `XRP`, `XAU`, `WTIOIL`, `SPYX`, `NVDAX`, `GOOGL`, `TSLA`, `AAPL` | | `horizon` | string | No | 24H | `1h` for short term volatility forecast and `24h` for longer term | | `days` | integer | No | 14 | Number of days to aggregate for the meta-leaderboard ranking | | `limit` | integer | No | 10 | Number of top miners from the meta-leaderboard to use for analysis | ### Headers | Header | Required | Description | | --------------- | -------- | ---------------------------------------- | | `Authorization` | Yes | API key in format: `Apikey YOUR_API_KEY` | ### Response The endpoint returns a comprehensive volatility analysis object containing current price, forecasted volatility (both forward and backward-looking), and realized historical volatility with price/return data. #### Response Schema ```json { "current_price": number, "forecast_future": { "average_volatility": number, "volatility": number[] }, "forecast_past": { "average_volatility": number, "volatility": number[] }, "realized": { "average_volatility": number, "prices": [ { "price": number, "returns": number } ], "volatility": number[] } } ``` #### Field Descriptions | Field | Type | Description | | ------------------------------------ | --------- | -------------------------------------------------------------- | | `current_price` | number | Current asset price at time of request | | `forecast_future.average_volatility` | number | Mean of forward-looking volatility predictions | | `forecast_future.volatility` | number\[] | Array of predicted future volatility values | | `forecast_past.average_volatility` | number | Mean of backward-looking volatility analysis | | `forecast_past.volatility` | number\[] | Array of historical volatility predictions | | `realized.average_volatility` | number | Mean realized volatility over the observation period | | `realized.prices` | array | Historical price observations with computed returns | | `realized.prices[].price` | number | Asset price at observation time | | `realized.prices[].returns` | number | Return from previous observation | | `realized.volatility` | number\[] | Realized volatility values corresponding to price observations | ### Example Request {% code title="curl" %} ```bash curl "https://api.synthdata.co/insights/volatility?asset=BTC&days=14&limit=10" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ### Example Response {% code title="Response (application/json)" %} ```json { "current_price": 89081.11, "forecast_future": { "average_volatility": 34.99, "volatility": [49.07, 48.54, 48.61, 48.46, 50.86, 52.03, ...] }, "forecast_past": { "average_volatility": 36.63, "volatility": [54.84, 51.18, 50.89, 50.99, 45.77, 42.86, ...] }, "realized": { "average_volatility": 40.66, "prices": [ {"price": 89750.75, "returns": -0.000105}, {"price": 89741.30, "returns": 0.000275}, {"price": 89766.00, "returns": 0.001540}, ... ], "volatility": [30.17, 55.97, 83.24, 84.78, 137.25, ...] } } ``` {% endcode %} ### Response Codes | Code | Description | | ----- | ----------------------------------------- | | `200` | Success - returns volatility data | | `400` | Bad Request - invalid parameters | | `401` | Unauthorized - invalid or missing API key | | `500` | Internal Server Error | ### Use Cases * Options Pricing: Use `forecast_future.average_volatility` as volatility input for pricing models * Position Sizing: Scale position sizes inversely with `realized.average_volatility` for risk management * Regime Detection: Compare `forecast_future` vs `realized` volatility to detect market regime changes * Volatility Trading: Identify mean-reversion opportunities when forecast significantly deviates from realized * Backtesting: Use `realized.prices` array to reconstruct historical price paths for strategy validation # Risk Management Manage portfolio and position risk. ## Monitor Liquidation Risk {% code title="monitor\_liquidation\_risk.py" %} ```python import requests response = requests.get( "https://api.synthdata.co/insights/liquidation", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() current_price = data['current_price'] for level in data['data']: price_change = level['price_change'] long_prob_24h = level['long_liquidation_probability']['24'] short_prob_24h = level['short_liquidation_probability']['24'] print(f"{price_change} move - Long liq: {long_prob_24h:.1%}, Short liq: {short_prob_24h:.1%}") ``` {% endcode %} ## Dynamic Stop-Loss {% code title="dynamic\_stop\_loss.py" %} ```python import requests response = requests.get( "https://api.synthdata.co/insights/prediction-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() current_price = data['current_price'] percentiles = data['forecast_future']['percentiles'] # Set stop-loss at 5th percentile of 24h forecast stop_loss = percentiles[-1]['0.05'] ``` {% endcode %} ## Portfolio VaR {% code title="portfolio\_var.py" %} ```python import requests positions = [ {"asset": "BTC", "entry": 88000, "value": 10000}, {"asset": "ETH", "entry": 3000, "value": 5000} ] total_value = sum(p['value'] for p in positions) portfolio_var = 0 for position in positions: response = requests.get( "https://api.synthdata.co/insights/prediction-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": position['asset']} ) data = response.json() worst_case = data['forecast_future']['percentiles'][-1]['0.05'] pnl = (worst_case - position['entry']) / position['entry'] portfolio_var += position['value'] * pnl var_5 = total_value + portfolio_var ``` {% endcode %} # Options Use Synth API for options pricing and trading. ## Get Option Prices {% code title="get\_option\_prices.py" %} ```python import requests response = requests.get( "https://api.synthdata.co/insights/option-pricing", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() current_price = data['current_price'] call_options = data['call_options'] # {"84000": 4813.78, "84500": 4313.81, ...} put_options = data['put_options'] # {"84000": 0.0, "84500": 0.03, ...} expiry = data['expiry_time'] # "2026-01-23 08:00:00Z" ``` {% endcode %} ## Find Mispriced Options {% code title="find\_mispriced\_options.py" %} ```python for strike, synth_call in call_options.items(): market_call = get_market_price(strike) if synth_call > 0: edge = (market_call - synth_call) / synth_call if edge > 0.05: print(f"SELL {strike} call - {edge:.1%} edge") elif edge < -0.05: print(f"BUY {strike} call - {abs(edge):.1%} edge") ``` {% endcode %} ## Bull Call Spread {% code title="bull\_call\_spread.py" %} ```python # Buy ATM call, sell OTM call strikes = sorted([int(k) for k in call_options.keys()]) # Find ATM (closest to current price) atm_strike = min(strikes, key=lambda x: abs(x - current_price)) # Find OTM (5% above current price) otm_strike = min([s for s in strikes if s > current_price * 1.05], default=strikes[-1]) cost = call_options[str(atm_strike)] - call_options[str(otm_strike)] max_profit = (otm_strike - atm_strike) - cost ``` {% endcode %} # Trading Build trading strategies using probabilistic forecasts. ### Directional Trading {% code title="directional\_signal.py" %} ```python import requests def get_signal(asset, threshold=0.55): response = requests.get( "https://api.synthdata.co/insights/prediction-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": asset} ) data = response.json() current_price = data['current_price'] final = data['forecast_future']['percentiles'][-1] median = final['0.5'] p35 = final['0.35'] p65 = final['0.65'] if median > current_price and p35 > current_price: return "LONG" elif median < current_price and p65 < current_price: return "SHORT" else: return "NEUTRAL" ``` {% endcode %} ### Position Sizing {% code title="kelly\_size.py" %} ```python def kelly_size(prob_win, avg_win, avg_loss, max_kelly=0.25): win_loss_ratio = avg_win / avg_loss kelly = (prob_win * win_loss_ratio - (1 - prob_win)) / win_loss_ratio return max(0, min(kelly, max_kelly)) ``` {% endcode %} *** ## LP Bounds Optimal liquidity provider ranges with impermanent loss estimates. Endpoint: ``` GET /insights/lp-bounds ``` ### Response {% code title="lp-bounds-response.json" %} ```json { "current_price": 88997.48, "data": [ { "interval": { "full_width": "1.0%", "lower_bound": 88552.49, "upper_bound": 89442.47 }, "probability_to_stay_in_interval": {"24": 0.0}, "expected_time_in_interval": 71.99, "expected_impermanent_loss": 0.0064 }, { "interval": { "full_width": "3.0%", "lower_bound": 87662.52, "upper_bound": 90332.44 }, "probability_to_stay_in_interval": {"24": 0.2135}, "expected_time_in_interval": 732.20, "expected_impermanent_loss": 0.0046 } ] } ``` {% endcode %} ### Example {% code title="example\_lp\_bounds.py" %} ```python response = requests.get( "https://api.synthdata.co/insights/lp-bounds", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) for level in response.json()['data']: width = level['interval']['full_width'] prob = level['probability_to_stay_in_interval']['24'] il = level['expected_impermanent_loss'] print(f"{width} range: {prob:.1%} stay probability, {il:.2%} expected IL") ``` {% endcode %} *** ## LP Probabilities Price distribution probabilities for LP range decisions. Endpoint: ``` GET /insights/lp-probabilities ``` ### Response {% code title="lp-probabilities-response.json" %} ```json { "current_price": 87289.63, "data": { "24h": { "probability_above": { "81304.50": 0.9999, "82663.77": 0.9975, "84023.04": 0.9747, "85382.32": 0.8615, "86741.59": 0.6062, "88100.86": 0.3095, "89460.14": 0.1138, "90819.41": 0.0323, "92178.69": 0.0079, "93537.96": 0.0016, "94897.23": 0.0 }, "probability_below": { "81304.50": 0.0, "82663.77": 0.0025, "84023.04": 0.0253, "85382.32": 0.1385, "86741.59": 0.3938, "88100.86": 0.6905, "89460.14": 0.8862, "90819.41": 0.9677, "92178.69": 0.9921, "93537.96": 0.9984, "94897.23": 0.9999 } } } } ``` {% endcode %} ### Example {% code title="example\_lp\_bounds\_chart.py" %} ```python response = requests.get( "https://api.synthdata.co/insights/lp-probabilities", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json()['data']['24h'] for price, prob in data['probability_above'].items(): print(f"P(price > ${float(price):,.0f}) = {prob:.1%}") ``` {% endcode %} *** # Polymarket Compare Synth predictions against Polymarket prices. ### Daily Up/Down Forecast Horizon: `24h` Endpoint: ``` GET /insights/polymarket/up-down/daily ``` Example Request curl ``` curl "https://api.synthdata.co/insights/polymarket/up-down/daily?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json { "slug": "bitcoin-up-or-down-on-february-27", "start_price": 66806.69, "current_time": "2026-02-27T15:16:37+00:00", "current_price": 66102.10, "current_outcome": "Down", "synth_probability_up": 0.1078, "synth_outcome": "Down", "polymarket_probability_up": 0.125, "polymarket_outcome": "Down", "event_start_time": "2026-02-26T17:00:00+00:00", "event_end_time": "2026-02-27T17:00:00+00:00", "event_creation_time": "2026-02-25T17:09:48+00:00", "best_bid_price": 0.12, "best_ask_price": 0.13, "best_bid_size": 5.0, "best_ask_size": 456.0, "polymarket_last_trade_time": "2026-02-27T15:14:01+00:00", "polymarket_last_trade_price": 0.89, "polymarket_last_trade_outcome": "Down" } ``` ### Hourly Up/Down Forecast Horizon: `1h` Endpoint: ``` GET /insights/polymarket/up-down/hourly ``` Example Request curl ``` curl "https://api.synthdata.co/insights/polymarket/up-down/hourly?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json { "slug": "bitcoin-up-or-down-february-27-10am-et", "start_price": 66176.05, "current_time": "2026-02-27T15:16:43+00:00", "current_price": 66102.10, "current_outcome": "Down", "synth_probability_up": 0.3925, "synth_outcome": "Down", "polymarket_probability_up": 0.635, "polymarket_outcome": "Up", "event_start_time": "2026-02-27T15:00:00+00:00", "event_end_time": "2026-02-27T16:00:00+00:00", "event_creation_time": "2026-02-25T15:02:38+00:00", "best_bid_price": 0.63, "best_ask_price": 0.64, "best_bid_size": 82.01, "best_ask_size": 135.0, "polymarket_last_trade_time": "2026-02-27T15:15:37+00:00", "polymarket_last_trade_price": 0.32, "polymarket_last_trade_outcome": "Down" } ``` ### 15-Minute Up/Down Forecast Horizon: `1h` Assets: `BTC`, `ETH`, `SOL` Endpoint: ``` GET /insights/polymarket/up-down/15min ``` Example Request curl ``` curl "https://api.synthdata.co/insights/polymarket/up-down/15min?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json { "slug": "btc-updown-15m-1772204400", "start_price": 66176.05, "current_time": "2026-02-27T15:04:21+00:00", "current_price": 65936.60, "current_outcome": "Down", "synth_probability_up": 0.0969, "synth_outcome": "Down", "polymarket_probability_up": 0.475, "polymarket_outcome": "Down", "event_start_time": "2026-02-27T15:00:00+00:00", "event_end_time": "2026-02-27T15:15:00+00:00", "best_bid_price": 0.47, "best_ask_price": 0.48, "best_bid_size": 218.0, "best_ask_size": 445.47, "polymarket_last_trade_time": "2026-02-27T14:59:57+00:00", "polymarket_last_trade_price": 0.4582015, "polymarket_last_trade_outcome": "Down" } ``` ## Price Range Forecast Horizon: `24h` Endpoint: ``` GET /insights/polymarket/range ``` Response: {% code title="response.json" %} ```json [ { "title": "[90, 0, 92, 0]", "ref_prices": [90, 0, 92, 0], "current_price": 88862.66, "synth_probability": 0.0, "polymarket_probability": 0.053, "event_end_time": "2026-01-22T17:00:00+00:00" } ] ``` {% endcode %} ## Example: Find Arbitrage {% code title="example.py" %} ```python import requests response = requests.get( "https://api.synthdata.co/insights/polymarket/up-down/daily", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() synth = data['synth_probability_up'] poly = data['polymarket_probability_up'] edge = synth - poly if abs(edge) > 0.05: if edge > 0: print(f"BUY 'Up' on Polymarket - Synth says {synth:.1%} vs market {poly:.1%}") else: print(f"BUY 'Down' on Polymarket - Synth says {1-synth:.1%} vs market {1-poly:.1%}") ``` {% endcode %} # Limitless Compare Synth predictions against Limitless prices. Assets: `BTC`, `ETH`, `SOL` #### Daily Up/Down Forecast Horizon: `24h` Endpoint: ``` GET /insights/limitless/daily ``` Example Request ```curl curl "https://api.synthdata.co/insights/limitless/daily?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json [ { "slug": "btc-above-dollar7051116-on-mar-20-1000-utc-1773914406897", "start_price": 70511.16, "current_time": "2026-03-19T16:36:34.334162+00:00", "current_price": 69340.04, "synth_probability_up": 0.1734, "synth_outcome": "Down", "market_probability_up": 0.2455, "market_outcome": "Down", "event_outcome_prices": [0.2455, 0.7545], "best_bid_price": 0.216, "best_ask_price": 0.275, "event_creation_time": "2026-03-19T10:00:06.896000+00:00", "event_end_time": "2026-03-20T10:00:00+00:00", "forecast_start_time": "2026-03-19T16:09:00+00:00" } ] ``` #### Hourly Up/Down Forecast Horizon: `1h` Returns multiple active contracts at different strike prices for the current hour. Endpoint: ``` GET /insights/limitless/hourly ``` Example Request ```curl curl "https://api.synthdata.co/insights/limitless/hourly?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json [ { "slug": "btc-above-dollar6940517-on-mar-19-1700-utc-1773936002266", "start_price": 69405.17, "current_time": "2026-03-19T16:36:51.881403+00:00", "current_price": 69340.04, "synth_probability_up": 0.3989, "synth_outcome": "Down", "market_probability_up": 0.395, "market_outcome": "Down", "event_outcome_prices": [0.395, 0.605], "best_bid_price": 0.365, "best_ask_price": 0.425, "event_creation_time": "2026-03-19T16:00:02.264000+00:00", "event_end_time": "2026-03-19T17:00:00+00:00", "forecast_start_time": "2026-03-19T16:20:00+00:00" }, { "slug": "btc-above-dollar6878467-on-mar-19-1700-utc-1773936211556", "start_price": 68784.67, "current_time": "2026-03-19T16:36:51.881403+00:00", "current_price": 69340.04, "synth_probability_up": 0.9717, "synth_outcome": "Up", "market_probability_up": 0.945, "market_outcome": "Up", "event_outcome_prices": [0.945, 0.055], "best_bid_price": 0.94, "best_ask_price": 0.95, "event_creation_time": "2026-03-19T16:03:31.553000+00:00", "event_end_time": "2026-03-19T17:00:00+00:00", "forecast_start_time": "2026-03-19T16:20:00+00:00" } ] ``` #### 15-Minute Up/Down Forecast Horizon: `1h` Endpoint: ``` GET /insights/limitless/15min ``` Example Request ```curl curl "https://api.synthdata.co/insights/limitless/15min?asset=BTC" \ -H "Authorization: Apikey YOUR_API_KEY" ``` Response: ```json [ { "slug": "btc-above-dollar6953341-on-mar-19-1645-utc-1773937812484", "start_price": 69533.41, "current_time": "2026-03-19T16:36:51.881973+00:00", "current_price": 69340.04, "synth_probability_up": 0.1228, "synth_outcome": "Down", "market_probability_up": 0.1025, "market_outcome": "Down", "event_outcome_prices": [0.1025, 0.8975], "best_bid_price": 0.07, "best_ask_price": 0.135, "event_creation_time": "2026-03-19T16:30:12.481000+00:00", "event_end_time": "2026-03-19T16:45:00+00:00", "forecast_start_time": "2026-03-19T16:20:00+00:00" } ] ``` ### Example: Find Arbitrage ```python import requests response = requests.get( "https://api.synthdata.co/insights/limitless/hourly", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) for contract in response.json(): synth = contract['synth_probability_up'] market = contract['market_probability_up'] edge = synth - market if abs(edge) > 0.05: if edge > 0: print(f"BUY 'Up' on Limitless - Synth says {synth:.1%} vs market {market:.1%}") else: print(f"BUY 'Down' on Limitless - Synth says {1-synth:.1%} vs market {1-market:.1%}") ``` # Volatility (old) Calculate current, historical, and forward-looking volatility metrics based on aggregated miner predictions. ``` GET /insights/volatility ``` ### Parameters | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ------------------------------------------------------------------ | | `asset` | string | Yes | — | Asset symbol: `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | | `days` | integer | No | 14 | Number of days to aggregate for the meta-leaderboard ranking | | `limit` | integer | No | 10 | Number of top miners from the meta-leaderboard to use for analysis | ### Headers | Header | Required | Description | | --------------- | -------- | ---------------------------------------- | | `Authorization` | Yes | API key in format: `Apikey YOUR_API_KEY` | ### Response The endpoint returns a comprehensive volatility analysis object containing current price, forecasted volatility (both forward and backward-looking), and realized historical volatility with price/return data. #### Response Schema ```json { "current_price": number, "forecast_future": { "average_volatility": number, "volatility": number[] }, "forecast_past": { "average_volatility": number, "volatility": number[] }, "realized": { "average_volatility": number, "prices": [ { "price": number, "returns": number } ], "volatility": number[] } } ``` #### Field Descriptions | Field | Type | Description | | ------------------------------------ | --------- | -------------------------------------------------------------- | | `current_price` | number | Current asset price at time of request | | `forecast_future.average_volatility` | number | Mean of forward-looking volatility predictions | | `forecast_future.volatility` | number\[] | Array of predicted future volatility values | | `forecast_past.average_volatility` | number | Mean of backward-looking volatility analysis | | `forecast_past.volatility` | number\[] | Array of historical volatility predictions | | `realized.average_volatility` | number | Mean realized volatility over the observation period | | `realized.prices` | array | Historical price observations with computed returns | | `realized.prices[].price` | number | Asset price at observation time | | `realized.prices[].returns` | number | Return from previous observation | | `realized.volatility` | number\[] | Realized volatility values corresponding to price observations | ### Example Request {% code title="curl" %} ```bash curl "https://api.synthdata.co/insights/volatility?asset=BTC&days=14&limit=10" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ### Example Response ```json { "current_price": 89081.11, "forecast_future": { "average_volatility": 34.99, "volatility": [49.07, 48.54, 48.61, 48.46, 50.86, 52.03, ...] }, "forecast_past": { "average_volatility": 36.63, "volatility": [54.84, 51.18, 50.89, 50.99, 45.77, 42.86, ...] }, "realized": { "average_volatility": 40.66, "prices": [ {"price": 89750.75, "returns": -0.000105}, {"price": 89741.30, "returns": 0.000275}, {"price": 89766.00, "returns": 0.001540}, ... ], "volatility": [30.17, 55.97, 83.24, 84.78, 137.25, ...] } } ``` ### Response Codes | Code | Description | | ----- | ----------------------------------------- | | `200` | Success - returns volatility data | | `400` | Bad Request - invalid parameters | | `401` | Unauthorized - invalid or missing API key | | `500` | Internal Server Error | *** ## Volatility Percentiles Get price distribution percentiles over the forecast horizon. ``` GET /insights/volatility-percentiles ``` ### Parameters | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ------------------------------------------------------------------ | | `asset` | string | Yes | — | Asset symbol: `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | | `days` | integer | No | 14 | Number of days to aggregate for the meta-leaderboard ranking | | `limit` | integer | No | 10 | Number of top miners from the meta-leaderboard to use for analysis | ### Response ```json { "current_price": 88996.66, "forecast_future": { "percentiles": [ { "0.005": 88996.66, "0.05": 88996.66, "0.2": 88996.66, "0.35": 88996.66, "0.5": 88996.66, "0.65": 88996.66, "0.8": 88996.66, "0.95": 88996.66, "0.995": 88996.66 }, { "0.005": 88631.35, "0.05": 88765.15, "0.2": 88879.70, "0.35": 88943.39, "0.5": 88998.23, "0.65": 89055.24, "0.8": 89122.30, "0.95": 89236.58, "0.995": 89359.79 } ] }, "forecast_past": { "percentiles": [...] }, "realized": { "prices": [...], "percentiles": [...] } } ``` #### Field Descriptions | Field | Description | | ----------------------------- | --------------------------------------------------------------- | | `current_price` | Current asset price | | `forecast_future.percentiles` | Array of percentile objects, one per time step | | `0.005`, `0.05`, etc. | Price at that percentile (0.5 = median, 0.95 = 95th percentile) | ### Example {% code title="python" %} ```python response = requests.get( "https://api.synthdata.co/insights/volatility-percentiles", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC"} ) data = response.json() percentiles = data['forecast_future']['percentiles'] # Get 95% confidence interval at final time step final = percentiles[-1] lower_bound = final['0.05'] # 5th percentile upper_bound = final['0.95'] # 95th percentile print(f"24h 90% CI: ${lower_bound:,.0f} - ${upper_bound:,.0f}") ``` {% endcode %} *** ### Use Cases * Options Pricing: Use `forecast_future.average_volatility` as volatility input for pricing models * Position Sizing: Scale position sizes inversely with `realized.average_volatility` for risk management * Regime Detection: Compare `forecast_future` vs `realized` volatility to detect market regime changes * Volatility Trading: Identify mean-reversion opportunities when forecast significantly deviates from realized * Backtesting: Use `realized.prices` array to reconstruct historical price paths for strategy validation # Endpoints Overview ## Base URL ``` https://api.synthdata.co ``` All endpoints require the following header: ``` Authorization: Apikey YOUR_API_KEY ``` **Forecast Horizons:** All insight endpoints accept an optional `horizon` query parameter: `1h` , `24h`. ## Prediction Percentiles Get probabilistic price forecasts. | Endpoint | Description | | -------------------------------------- | --------------------------------------------------------------- | | `GET /insights/prediction-percentiles` | Price percentiles (5th, 50th, 95th, etc.) at 5-minute intervals | ## Leaderboard Discover top-performing miners. | Endpoint | Description | | ---------------------------- | ---------------------- | | `GET /v2/leaderboard/latest` | Current miner rankings | Example request: {% code title="curl" %} ```bash curl "https://api.synthdata.co/v2/leaderboard/latest?asset=BTC&days=14&limit=10" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ## Insights Advanced analytics derived from predictions. | Endpoint | Description | | ----------------------------------------- | ----------------------------- | | `GET /insights/volatility` | Volatility metrics | | `GET /insights/option-pricing` | Theoretical option prices | | `GET /insights/liquidation` | Liquidation probabilities | | `GET /insights/lp-bounds` | LP range optimization | | `GET /insights/lp-probabilities` | Price level probabilities | | `GET /insights/polymarket/up-down/daily` | Daily up/down comparison | | `GET /insights/polymarket/up-down/hourly` | Hourly up/down comparison | | `GET /insights/polymarket/up-down/15min` | 15 minutes up/down comparison | | `GET /insights/polymarket/range` | Polymarket range comparison | | `GET /insights/limitless/daily` | Limitless above comparison | | `GET /insights/limitless/hourly` | Limitless above comparison | | `GET /insights/limitless/`15min | Limitless above comparison | ## Price Predictions Full prediction paths for advanced use cases. Contact for more information. | Endpoint | Description | | ----------------------------------------- | ------------------------------------------- | | `GET /v2/prediction/best` | Full prediction paths from top-ranked miner | | `GET /v2/prediction/latest` | Full prediction paths from specific miners | | `GET /v2/prediction/historical` | Historical predictions | | `GET /v2/prediction/metamodel` | Metamodel prediction | | `GET /v2/prediction/metamodel/historical` | Historical predictions of the metamodel | # Predictions ## Meta-model Historical The endpoint `GET /v2/prediction/metamodel/historical` returns the 10,000 paths of the variance-based weighted meta-model (not based on the meta-leaderboard but on miner contributions, cf ) ### Usage The main usage is to backtest strategies. 1. Fetch the prompts `GET /validation/prompts` : it returns the start time of the prediction one which we can perform a backtest 2. Fetch the historical meta-model `GET /v2/prediction/metamodel/historical` ### Endpoint definition `GET /validation/prompts` | Parameter | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------- | | `time_increment` | int | The increment of time between prompts in seconds (e.g., 300 for 24h horizon and 60 for 1h horizon). | | `time_length` | int | The time length of the predictions in seconds (e.g., 86400 for the 24h horizon and 3600 for the 1h horizon). | | `asset` | string | The asset for which the data is being requested (BTC, ETH, SOL, HYPE, XRP, XAU, SPY, NVDA, GOOGL, TSLA, AAPL). | | `from` | string | The start date for the data in ISO format (e.g., 2026-03-02). | | `to` | string | The end date for the data in ISO format (e.g., 2026-03-31). | `GET /v2/prediction/metamodel/historical` | Parameter | Type | Description | | ------------ | ------ | -------------------------------------------------------------------------------------------------------- | | asset | string | The asset identifier, such as XAU for gold. | | prompt\_name | string | The name of the prompt frequency to use, such as 'low' for the 24h horizon and 'high" for the 1h horizon | | start\_time | string | The starting time for the prediction in ISO format (e.g., 2026-04-10). | ## Prediction Historical Returns historical predictions for backtesting. ``` GET /v2/prediction/historical ``` ### Parameters | Parameter | Type | Description | | --------------- | ------ | ------------------------------------------------------- | | asset | string | The asset identifier. | | miner | int | The ID of the miner. | | start\_time | string | The starting time in ISO format (e.g., 2026-03-09). | | time\_increment | int | The time increment in seconds (e.g., 60). | | time\_length | int | The duration of the prediction in seconds (e.g., 3600). | Example: `curl -L 'https://api.synthdata.co/v2/prediction/historical?asset=BTC&miner=198&miner=200&miner=39&start_time=2026-03-09&time_increment=60&time_length=3600' -H 'Authorization: Apikey ...'` ### Usage Typical usage is to fetch the historical meta-leaderboard and then the historical predictions of the top miners. `curl -L 'https://api.synthdata.co/v2/meta-leaderboard/historical?start_time=2026-01-09T00%3A00%3A00Z&prompt_name=high'` # Getting Started (old) Get up and running with Synth API in minutes. ## What You'll Need {% stepper %} {% step %} ### API Key Get an API key from your [Synth Dashboard](https://dashboard.synthdata.co/). {% endstep %} {% step %} ### Make a Request ```bash curl "https://api.synthdata.co/v2/prediction/best?asset=BTC&time_increment=300&time_length=86400" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endstep %} {% step %} ### Parse the Response ```python import requests import numpy as np response = requests.get( "https://api.synthdata.co/v2/prediction/best", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={ "asset": "BTC", "time_increment": 300, "time_length": 86400 } ) data = response.json()[0] paths = data['predictions'] # Calculate probability current_price = paths[0][0] final_prices = [path[-1] for path in paths] prob_up = sum(1 for p in final_prices if p > current_price) / len(final_prices) print(f"Current: ${current_price:,.2f}") print(f"24h Median: ${np.median(final_prices):,.2f}") print(f"Prob up: {prob_up:.1%}") ``` {% endstep %} {% endstepper %} ## Common Parameters | Parameter | Value | Description | | ---------------- | ------------------------------------------- | ------------------------ | | `asset` | `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | Asset to forecast | | `time_increment` | `300` | 5-minute intervals | | `time_length` | `86400` | 24-hour forecast horizon | # Rate limits Synth API enforces rate limits based on your subscription plan. ## Limits by Plan | Plan | Requests/Minute | Requests/Day | | ------------ | --------------- | ------------ | | Professional | 20 | 1,000 | | Enterprise | Custom | Custom | ## Response Headers Every response includes rate limit information: ```http X-RateLimit-Limit: 120 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1738329660 ``` ## Handling Rate Limits When you exceed the limit, you'll receive `429 Too Many Requests`: ```json { "error": "Rate limit exceeded", "message": "Please try again in 42 seconds", "retry_after": 42 } ``` ### Retry Logic {% code title="example.py" %} ```python import time import requests def make_request_with_retry(url, headers): response = requests.get(url, headers=headers) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 60)) time.sleep(retry_after) return make_request_with_retry(url, headers) return response.json() ``` {% endcode %} ## Best Practices * Cache responses — Predictions don't change frequently. * Batch requests — Use the `limit` parameter to get multiple miners. * Monitor usage — Check headers on every response. * Implement backoff — Use exponential backoff for retries. ## Next Steps * [View pricing](broken://pages/3d911d70dd3c6fe8e8e6640a6805234fe8bdf2fe) * [Handle errors](broken://pages/881681ff5db1046d1ddbd1f8bc1ecc181dca7c8a) # Copy of Rate limits Synth API enforces rate limits based on your subscription plan. ## Limits by Plan | Plan | Requests/Second | Requests/Month | | ------------ | --------------- | -------------- | | Standard | 10 | 50 One time | | Professional | 10 | 500 | | Enterprise | Custom | Custom | ## Response Headers Every response includes rate limit information: ```http X-RateLimit-Limit: 120 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1738329660 ``` ## Handling Rate Limits When you exceed the limit, you'll receive `429 Too Many Requests`: ```json { "error": "Rate limit exceeded", "message": "Please try again in 42 seconds", "retry_after": 42 } ``` ### Retry Logic {% code title="example.py" %} ```python import time import requests def make_request_with_retry(url, headers): response = requests.get(url, headers=headers) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 60)) time.sleep(retry_after) return make_request_with_retry(url, headers) return response.json() ``` {% endcode %} ## Best Practices * Cache responses — Predictions don't change frequently. * Batch requests — Use the `limit` parameter to get multiple miners. * Monitor usage — Check headers on every response. * Implement backoff — Use exponential backoff for retries. ## Next Steps * [View pricing](broken://pages/3d911d70dd3c6fe8e8e6640a6805234fe8bdf2fe) * [Handle errors](broken://pages/881681ff5db1046d1ddbd1f8bc1ecc181dca7c8a) # Endpoints Overview ## Base URL ``` https://api.synthdata.co ``` {% hint style="info" %} All endpoints require the following header: ``` Authorization: Apikey YOUR_API_KEY ``` {% endhint %} ## Predictions Get probabilistic price forecasts from miners. | Endpoint | Description | | ------------------------------- | -------------------------------------------- | | `GET /v2/prediction/best` | Predictions from top-ranked miner (simplest) | | `GET /v2/prediction/latest` | Predictions from specific miners | | `GET /v2/prediction/historical` | Historical predictions | ## Leaderboard Discover top-performing miners. | Endpoint | Description | | ---------------------------- | ---------------------- | | `GET /v2/leaderboard/latest` | Current miner rankings | Example request: ```bash curl "https://api.synthdata.co/v2/leaderboard/latest?asset=BTC&days=14&limit=10" \ -H "Authorization: Apikey YOUR_API_KEY" ``` ## Insights Advanced analytics derived from predictions. | Endpoint | Description | | ----------------------------------------- | ------------------------------ | | `GET /insights/volatility` | Volatility metrics | | `GET /insights/volatility-percentiles` | Price distribution percentiles | | `GET /insights/option-pricing` | Theoretical option prices | | `GET /insights/liquidation` | Liquidation probabilities | | `GET /insights/lp-bounds` | LP range optimization | | `GET /insights/lp-bounds-chart` | Price level probabilities | | `GET /insights/polymarket/range` | Polymarket range comparison | | `GET /insights/polymarket/up-down/hourly` | Hourly up/down comparison | | `GET /insights/polymarket/up-down/daily` | Daily up/down comparison | # Predictions Best Get predictions from the current top-ranked miner. This is the simplest endpoint - no miner selection required. ``` GET /v2/prediction/best ``` ## Parameters | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------- | | `asset` | string | Yes | `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | | `time_increment` | integer | Yes | `300` (5min intervals) | | `time_length` | integer | Yes | `86400` (24h forecast) | ## Request Example {% code title="curl" %} ```bash curl "https://api.synthdata.co/v2/prediction/best?asset=BTC&time_increment=300&time_length=86400" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ## Response ```json [ { "miner_uid": 2, "start_time": 1769097780, "predictions": [ [88975.00, 89012.45, 88934.21, ..., 87633.98], [88975.00, 89102.33, 89245.67, ..., 90256.12], ... ] } ] ``` | Field | Description | | ------------- | ------------------------------------------------------------------------- | | `miner_uid` | ID of the top-performing miner | | `start_time` | Unix timestamp when prediction was generated | | `predictions` | Array of 1,000 price paths, each with 289 points (24h at 5-min intervals) | ## Example: Quick Price Forecast {% code title="example.py" %} ```python import requests import numpy as np response = requests.get( "https://api.synthdata.co/v2/prediction/best", headers={"Authorization": "Apikey YOUR_API_KEY"}, params={"asset": "BTC", "time_increment": 300, "time_length": 86400} ) data = response.json()[0] paths = data['predictions'] current_price = paths[0][0] final_prices = [path[-1] for path in paths] print(f"Current: ${current_price:,.0f}") print(f"24h Median: ${np.median(final_prices):,.0f}") print(f"24h 5th percentile: ${np.percentile(final_prices, 5):,.0f}") print(f"24h 95th percentile: ${np.percentile(final_prices, 95):,.0f}") print(f"Prob up: {sum(1 for p in final_prices if p > current_price) / len(final_prices):.1%}") ``` {% endcode %} # Predictions Historical Get predictions from a specific past date. ``` GET /v2/prediction/historical ``` ## Parameters | Parameter | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------------------------- | | `miner` | array\[int] | Yes | Miner UIDs to fetch (use repeated params: `miner=2&miner=82`) | | `asset` | string | Yes | `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | | `start_time` | string | Yes | ISO 8601 datetime (e.g., `2025-01-15T00:00:00Z`) | | `time_increment` | integer | Yes | `300` (5min intervals) | | `time_length` | integer | Yes | `86400` (24h forecast) | ## Request Example ```bash curl "https://api.synthdata.co/v2/prediction/historical?miner=2&asset=BTC&start_time=2025-01-15T00:00:00Z&time_increment=300&time_length=86400" \ -H "Authorization: Apikey YOUR_API_KEY" ``` ## Response (example) {% code title="response.json" %} ```json [ { "miner_uid": 2, "start_time": 1736899200, "predictions": [ [97234.56, 97456.78, 97389.12, ..., 98123.45], [97234.56, 97567.89, 97612.34, ..., 96789.01], ... ] } ] ``` {% endcode %} | Field | Description | | ------------- | -------------------------------- | | `miner_uid` | Miner identifier | | `start_time` | Unix timestamp of the prediction | | `predictions` | Array of 1,000 price paths | ## Use Cases * Backtesting trading strategies * Analyzing miner prediction accuracy * Historical volatility analysis # Predictions Latest Get the most recent predictions from specific miners. ``` GET /v2/prediction/latest ``` ## Parameters | Parameter | Type | Required | Description | | ---------------- | ----------- | -------- | ------------------------------------------------------------- | | `miner` | array\[int] | Yes | Miner UIDs to fetch (use repeated params: `miner=2&miner=82`) | | `asset` | string | Yes | `BTC`, `ETH`, `SOL`, `XAU`, `SPYX`, `NVDAX` | | `time_increment` | integer | Yes | `300` (5min intervals) | | `time_length` | integer | Yes | `86400` (24h forecast) | {% hint style="info" %} To discover miner UIDs, first call `/v2/leaderboard/latest` to get top-performing miners. {% endhint %} ## Request Example {% code title="curl (get leaderboard)" %} ```bash # First, get top miner UIDs from leaderboard curl "https://api.synthdata.co/v2/leaderboard/latest?asset=BTC&days=14&limit=5" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} {% code title="curl (predictions)" %} ```bash # Then fetch predictions for those miners curl "https://api.synthdata.co/v2/prediction/latest?asset=BTC&time_increment=300&time_length=86400&miner=2&miner=82" \ -H "Authorization: Apikey YOUR_API_KEY" ``` {% endcode %} ## Response ```json [ { "miner_uid": 2, "start_time": 1769097780, "predictions": [ [88975.00, 89012.45, 88934.21, ..., 87633.98], [88975.00, 89102.33, 89245.67, ..., 90256.12], ... ] }, { "miner_uid": 82, "start_time": 1769097780, "predictions": [...] } ] ``` | Field | Description | | ------------- | ------------------------------------------------------------------------- | | `miner_uid` | Miner identifier | | `start_time` | Unix timestamp when prediction was generated | | `predictions` | Array of 1,000 price paths, each with 289 points (24h at 5-min intervals) | ## Example: Aggregate and Compute Statistics {% stepper %} {% step %} ### Get top miner UIDs Use the leaderboard endpoint to identify top miners and extract their UIDs. {% code title="python: get leaderboard" %} ```python import requests headers = {"Authorization": "Apikey YOUR_API_KEY"} leaderboard = requests.get( "https://api.synthdata.co/v2/leaderboard/latest", headers=headers, params={"asset": "BTC", "days": 14, "limit": 5} ).json() miner_uids = [m['neuron_uid'] for m in leaderboard[:5]] ``` {% endcode %} {% endstep %} {% step %} ### Fetch predictions and compute statistics Request predictions for the selected miners, aggregate paths, and compute summary statistics. {% code title="python: fetch predictions & stats" %} ```python import requests import numpy as np headers = {"Authorization": "Apikey YOUR_API_KEY"} response = requests.get( "https://api.synthdata.co/v2/prediction/latest", headers=headers, params={ "asset": "BTC", "time_increment": 300, "time_length": 86400, "miner": miner_uids # requests library handles array params } ) predictions = response.json() # Aggregate paths from all miners all_paths = [] for miner in predictions: all_paths.extend(miner['predictions']) # Calculate statistics final_prices = [path[-1] for path in all_paths] current_price = all_paths[0][0] print(f"Paths aggregated: {len(all_paths)}") print(f"Current price: ${current_price:,.2f}") print(f"Median forecast: ${np.median(final_prices):,.2f}") print(f"Prob up: {sum(1 for p in final_prices if p > current_price) / len(final_prices):.1%}") ``` {% endcode %} {% endstep %} {% endstepper %}