> For the complete documentation index, see [llms.txt](https://docs.bv7x.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bv7x.ai/use-the-signal/read-the-forecast/oracle.md).

# Oracle API

The Oracle API returns the full BV-7X signal including direction, confidence, and attribution. Requires token verification.

***

## Tiers

| Tier        | Requirement | Endpoint                       |
| ----------- | ----------- | ------------------------------ |
| **Basic**   | 500M+ $BV7X | `GET /api/bv7x/oracle`         |
| **Premium** | 1B+ $BV7X   | `GET /api/bv7x/oracle/premium` |

Both endpoints require a bearer token from [wallet verification](/use-the-signal/read-the-forecast/token-verification.md).

***

## Basic Tier

```
GET /api/bv7x/oracle
Authorization: Bearer <token>
```

### Response

```json
{
  "signal": "SELL",
  "confidence": 0.615,
  "direction": "DOWN",
  "horizon": "7d",
  "btcPrice": 66027,
  "regime": "BEAR_TREND",
  "modelVersion": "5.6.7",
  "timestamp": "2026-03-28T21:35:00Z"
}
```

### Fields

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `signal`       | string | `BUY`, `SELL`, or `HOLD`            |
| `confidence`   | number | Calibrated probability (0.50--0.99) |
| `direction`    | string | Expected 7-day move: `UP` or `DOWN` |
| `horizon`      | string | Prediction timeframe                |
| `btcPrice`     | number | BTC/USD at signal time              |
| `regime`       | string | Current market regime               |
| `modelVersion` | string | Model version                       |
| `timestamp`    | string | ISO 8601 timestamp                  |

***

## Premium Tier

```
GET /api/bv7x/oracle/premium
Authorization: Bearer <token>
```

Returns everything in Basic plus additional market context and accuracy metrics.

### Response

```json
{
  "signal": "SELL",
  "confidence": 0.615,
  "direction": "DOWN",
  "horizon": "7d",
  "btcPrice": 66027,
  "regime": "BEAR_TREND",
  "modelVersion": "5.6.7",
  "timestamp": "2026-03-28T21:35:00Z",
  "marketContext": {
    "fearGreed": 45,
    "etfFlows7d": -120000000
  },
  "accuracy": {
    "last30d": 0.68
  }
}
```

### Additional Premium Fields

| Field           | Type   | Description                          |
| --------------- | ------ | ------------------------------------ |
| `marketContext` | object | Key market indicators at signal time |
| `accuracy`      | object | Rolling accuracy metrics             |

***

## Error Responses

| Status | Reason                            |
| ------ | --------------------------------- |
| 401    | Missing or expired bearer token   |
| 403    | Token balance below required tier |
| 429    | Rate limit exceeded               |

***

## Example

```bash
# Basic tier
curl https://bv7x.ai/api/bv7x/oracle \
  -H "Authorization: Bearer eyJhbGci..."

# Premium tier
curl https://bv7x.ai/api/bv7x/oracle/premium \
  -H "Authorization: Bearer eyJhbGci..."
```

***

## Next

* [Public Signal](/use-the-signal/read-the-forecast/signal.md) -- free endpoint with gated direction
* [Copy-Trade](/use-the-signal/trade-the-forecast/copy-trade.md) -- structured trade intent for automation