> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Price Prediction API

> Retrieve deterministic directional scores and volatility-scaled heuristic scenarios built from derivatives and momentum signals.

The Price Prediction endpoint returns deterministic consensus directional scores for curated cached coins and on-demand market asset pages. Each score aggregates derivatives, flow, technical, and regime signals (funding rate, open interest change, perp basis, CVD, long/short ratio, liquidation bias, RSI, EMA cross, positioning pressure, momentum exhaustion, and squeeze risk) into a directional verdict plus optional 7D/30D heuristic scenarios. This is not a trained machine-learning model or a calibrated probability forecast. The number of available signals per coin (`signalsAvailable`) varies based on data coverage.

***

## List all predictions

`GET /v1/price-prediction/data`

Returns directional scores for all supported coins. Omit the `coin` parameter to get the full list.

### Query parameters

**coin** `string`

Ticker or asset ID/slug (e.g., `BTC`, `bitcoin`, `ethereum`, `solana`); a curated coin's ticker resolves to its slug. When omitted, returns cached scores for the curated list. When provided, returns the detailed signal breakdown for that coin, computing on demand when it is not in the cached list.

### Response fields (list mode)

**coins** `array`

Array of coin score objects, each with `coin`, `displayName`, `slug`, `consensusScore`, `direction`, `signals`, `spotPrice`, `marketCap`, `return24h`, `modelConfidence`, `forecasts`, and `scoredAt`. Every return is a decimal fraction; see detail mode below.

**updatedAt** `string`

ISO 8601 timestamp for the complete cached list. A partial half-sync preserves the prior aggregate timestamp while refreshed coins expose newer `scoredAt` values. `null` if no complete snapshot exists.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/price-prediction/data \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/price-prediction/data',
  {
    headers: { Authorization: 'Bearer sk_live_your_key_here' },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/price-prediction/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json title="Response (signals[] truncated to one entry; list mode returns the same per-coin shape as detail mode below)" theme={null}
{
  "data": {
    "coins": [
      {
        "coin": "BTC",
        "displayName": "Bitcoin",
        "slug": "bitcoin",
        "consensusScore": 64,
        "direction": "bullish",
        "signals": [
          {
            "name": "funding",
            "label": "Funding Rate",
            "rawValue": 0.0006,
            "rawDisplay": "0.0600%",
            "subScore": 20,
            "conviction": 20,
            "bias": "bullish",
            "tooltip": "Average funding rate across exchanges"
          }
        ],
        "signalsAvailable": 6,
        "exchangesUsed": ["Binance", "Bybit", "OKX"],
        "spotPrice": 95200,
        "marketCap": 1870000000000,
        "return24h": 0.0215,
        "modelConfidence": 67,
        "scoredAt": "2026-03-28T12:00:00Z"
      }
    ],
    "updatedAt": "2026-03-28T12:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T12:00:05Z",
    "elapsed_ms": 12
  }
}
```

***

## Get single coin

`GET /v1/price-prediction/data?coin=bitcoin`

Pass a ticker or coin slug to get the full signal breakdown for a specific asset. Returns a `404 resource_not_found` error, whose detail lists valid slugs, when the coin is not recognized or has no publishable score, and `503 service_unavailable` with `Retry-After` when its live score cannot be computed.

### Response fields (detail mode)

**coin** `object`

Full coin score object with all signal details, or `null` if not found.

**coin.consensusScore** `number`

Final consensus score. Range: `0` (strong bearish) to `100` (strong bullish), with `40-60` treated as neutral.

**coin.direction** `string`

One of `strong_bullish`, `bullish`, `neutral`, `bearish`, `strong_bearish`, or `insufficient_data`.

**coin.signals** `array`

Array of signal objects, each with `name`, `label`, `rawValue`, `rawDisplay`, `subScore`, `conviction`, `bias`, and `tooltip`.

**coin.exchangesUsed** `array`

List of exchange identifiers that contributed data to this score.

**coin.return24h** `number`

24-hour price return as a decimal fraction: `0.0215` means +2.15%. Taken from the CoinGecko snapshot when the coin was scored. `null` when unavailable.

**coin.return7d** `number`

7-day price return as a decimal fraction: `0.0875` means +8.75%. Computed from hourly closes.

**coin.return30d** `number`

30-day price return as a decimal fraction: `0.0564` means +5.64%. Computed from hourly closes, like `return7d`.

**coin.distanceFrom7dHigh** `number`

Latest close relative to the highest hourly close of the last 7 days, as a decimal fraction: `-0.0426` means 4.26% below that high. Zero or negative.

**coin.distanceFrom7dLow** `number`

Latest close relative to the lowest hourly close of the last 7 days, as a decimal fraction: `0.1245` means 12.45% above that low. Zero or positive.

**coin.modelConfidence** `number`

Legacy field name for signal breadth, conviction, and agreement from `0` to `100`. It is not a probability or statistical model confidence. Conflicting signals reduce the value even when the direction is non-neutral.

**coin.forecasts** `array`

Optional 7D and 30D deterministic heuristic scenarios. `expectedPrice` (legacy name) is a signal-weighted midpoint, not a price target; `expectedReturn` is that midpoint as a return from the spot price, a decimal fraction (`0.038` means +3.8%). `lowPrice` and `highPrice` are an 80% range: the 10th and 90th percentiles of a lognormal centred on `expectedPrice` at the coin's 30-day realized daily volatility (`expectedPrice × exp(∓1.2816 × volatility × √days)`). The range assumes lognormal moves and is not backtested; fat tails leave it more often than one time in five. `confidence` is the coin's `modelConfidence` (signal breadth and agreement), not a probability. The array is empty unless a current spot price, at least two signals, and observed realized volatility are available.

**updatedAt** `string`

ISO 8601 timestamp of the last scoring run.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/price-prediction/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d coin=bitcoin
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/price-prediction/data?coin=bitcoin',
  {
    headers: { Authorization: 'Bearer sk_live_your_key_here' },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/price-prediction/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"coin": "bitcoin"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "coin": {
      "coin": "BTC",
      "displayName": "Bitcoin",
      "slug": "bitcoin",
      "consensusScore": 64,
      "direction": "bullish",
      "signals": [
        {
          "name": "funding",
          "label": "Funding Rate",
          "rawValue": 0.0006,
          "rawDisplay": "0.0600%",
          "subScore": 20,
          "conviction": 20,
          "bias": "bullish",
          "tooltip": "Average funding rate across exchanges"
        },
        {
          "name": "oi",
          "label": "Open Interest",
          "rawValue": 0.06,
          "rawDisplay": "+6.0%",
          "subScore": 20,
          "conviction": 20,
          "bias": "bullish",
          "tooltip": "24h change in aggregate open interest"
        },
        {
          "name": "ls",
          "label": "Long/Short Ratio",
          "rawValue": 0.88,
          "rawDisplay": "0.88",
          "subScore": 18,
          "conviction": 18,
          "bias": "bullish",
          "tooltip": "Ratio of long to short positions"
        },
        {
          "name": "liquidation",
          "label": "Liquidations",
          "rawValue": -0.35,
          "rawDisplay": "33% long",
          "subScore": 35,
          "conviction": 35,
          "bias": "bullish",
          "tooltip": "Proportion of long vs short liquidations"
        },
        {
          "name": "rsi",
          "label": "RSI (14, 1h)",
          "rawValue": 42,
          "rawDisplay": "42.0",
          "subScore": 16,
          "conviction": 16,
          "bias": "bullish",
          "tooltip": "Relative Strength Index over the last 14 hourly closes, not the daily RSI. Contrarian: overbought (>70) = bearish, oversold (<30) = bullish."
        },
        {
          "name": "ema",
          "label": "EMA 12/26 (1h)",
          "rawValue": 1.85,
          "rawDisplay": "+1.85%",
          "subScore": 37,
          "conviction": 37,
          "bias": "bullish",
          "tooltip": "Gap between the 12- and 26-period EMAs of hourly closes, as a share of price. Positive gap = bullish momentum, negative gap = bearish momentum."
        },
        {
          "name": "positioning",
          "label": "Positioning Pressure",
          "rawValue": 0.62,
          "rawDisplay": "+62%",
          "subScore": 62,
          "conviction": 62,
          "bias": "bullish",
          "tooltip": "Composite read of price direction, open-interest expansion, CVD, basis, and EMA"
        }
      ],
      "signalsAvailable": 7,
      "exchangesUsed": ["Binance", "Bybit", "OKX", "Deribit"],
      "spotPrice": 95200,
      "marketCap": 1870000000000,
      "return24h": 0.0215,
      "modelConfidence": 67,
      "forecasts": [
        {
          "days": 7,
          "expectedReturn": 0.038,
          "expectedPrice": 98817.6,
          "lowPrice": 89260.2,
          "highPrice": 109398.3,
          "confidence": 67
        },
        {
          "days": 30,
          "expectedReturn": 0.079,
          "expectedPrice": 102720.8,
          "lowPrice": 83215.5,
          "highPrice": 126798.0,
          "confidence": 67
        }
      ],
      "scoredAt": "2026-03-28T12:00:00Z"
    },
    "updatedAt": "2026-03-28T12:00:00Z"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T12:00:05Z",
    "elapsed_ms": 12
  }
}
```

[Read the error reference](https://docs.sharpe.ai/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.