> 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/reference/data-types.md).

# Data Types

Schema definitions for the primary data structures returned by BV-7X APIs.

***

## Signal Response

Returned by `/api/bv7x/oracle` and `/api/bv7x/openclaw/signal`.

```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"
}
```

| Field          | Type           | Values                         | Description                                      |
| -------------- | -------------- | ------------------------------ | ------------------------------------------------ |
| `signal`       | string         | `BUY`, `SELL`, `HOLD`, `GATED` | Prediction direction. `GATED` on public endpoint |
| `confidence`   | number \| null | 0.50--0.99                     | Calibrated probability. Null when gated          |
| `direction`    | string \| null | `UP`, `DOWN`                   | Expected 7-day BTC move. Null when gated         |
| `horizon`      | string         | `7d`                           | Prediction timeframe                             |
| `btcPrice`     | number         | --                             | BTC/USD at signal time                           |
| `regime`       | string         | See regimes                    | Current market regime                            |
| `modelVersion` | string         | --                             | Signal model version identifier                  |
| `timestamp`    | string         | ISO 8601                       | When the signal was computed                     |

***

## Trade Intent

Returned by `/api/bv7x/copy-trade/next` (Premium tier).

```json
{
  "trade": {
    "direction": "SELL",
    "confidence": 0.615,
    "horizon": "7d",
    "btcPrice": 66027,
    "regime": "BEAR_TREND",
    "sizing": {
      "kellyFraction": 0.046,
      "suggestedSize": "4.6%",
      "maxLeverage": "3x"
    },
    "polymarket": {
      "market": "Will BTC be above $66,000 on April 4?",
      "tokenId": "0xabc...",
      "side": "NO",
      "currentOdds": 0.42
    },
    "trackRecord": {
      "accuracy30d": 0.68,
      "currentStreak": 3
    }
  },
  "validUntil": "2026-03-29T21:35:00Z",
  "timestamp": "2026-03-28T21:37:00Z"
}
```

| Field                          | Type   | Description                            |
| ------------------------------ | ------ | -------------------------------------- |
| `trade.direction`              | string | `BUY` or `SELL`                        |
| `trade.confidence`             | number | Model confidence                       |
| `trade.sizing.kellyFraction`   | number | Optimal bet size (fraction of capital) |
| `trade.sizing.suggestedSize`   | string | Human-readable size                    |
| `trade.sizing.maxLeverage`     | string | Upper leverage bound                   |
| `trade.polymarket.market`      | string | Polymarket market title                |
| `trade.polymarket.tokenId`     | string | Token ID for programmatic trading      |
| `trade.polymarket.side`        | string | `YES` or `NO`                          |
| `trade.polymarket.currentOdds` | number | Current market odds                    |
| `trade.trackRecord`            | object | Accuracy metrics                       |
| `validUntil`                   | string | When this intent expires (next signal) |

***

## Attestation Record

Returned by `/api/bv7x/onchain-oracle/verify/:uid` and in history arrays.

```json
{
  "uid": "0xabc123...",
  "verified": true,
  "onChain": true,
  "date": "2026-03-28",
  "type": "prediction",
  "signal": "SELL",
  "direction": "DOWN",
  "confidence": 0.615,
  "btcPrice": 66027,
  "attester": "0xd8B71d23e1a8da9867497C0E757A1143B94C3e1e",
  "txHash": "0xdef456...",
  "easscanUrl": "https://base.easscan.org/attestation/view/0xabc123..."
}
```

| Field        | Type    | Description                                   |
| ------------ | ------- | --------------------------------------------- |
| `uid`        | string  | Unique attestation identifier                 |
| `verified`   | boolean | Whether the attestation data matches on-chain |
| `onChain`    | boolean | Whether it was found on Base                  |
| `date`       | string  | Prediction date (YYYY-MM-DD)                  |
| `type`       | string  | `prediction` or `resolution`                  |
| `signal`     | string  | BUY, SELL, or HOLD                            |
| `direction`  | string  | UP or DOWN                                    |
| `confidence` | number  | Model confidence at prediction time           |
| `btcPrice`   | number  | BTC/USD at attestation time                   |
| `attester`   | string  | Ethereum address that created the attestation |
| `txHash`     | string  | Transaction hash on Base                      |
| `easscanUrl` | string  | Direct link to EASScan                        |

***

## Webhook Event

Delivered to registered webhook URLs.

```json
{
  "event": "signal.new",
  "data": {
    "signal": "SELL",
    "confidence": 0.615,
    "direction": "DOWN",
    "btcPrice": 66027,
    "regime": "BEAR_TREND",
    "horizon": "7d"
  },
  "timestamp": "2026-03-28T21:35:00Z",
  "deliveryId": "del_xyz789"
}
```

| Field        | Type   | Description                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `event`      | string | Event type (see [Webhooks](/use-the-signal/read-the-forecast/webhooks.md)) |
| `data`       | object | Event-specific payload                                                     |
| `timestamp`  | string | When the event occurred                                                    |
| `deliveryId` | string | Unique delivery identifier for idempotency                                 |

### Event Types

| Event                 | Data Contents                                   |
| --------------------- | ----------------------------------------------- |
| `signal.new`          | Signal direction, confidence, BTC price, regime |
| `signal.resolved`     | Date, direction, outcome, BTC prices            |
| `wager.placed`        | Market, side, amount, odds                      |
| `wager.settled`       | Market, outcome, payout                         |
| `attestation.created` | UID, type, signal, txHash                       |
| `regime.changed`      | Previous regime, new regime                     |

***

## Regime Values

Used in signal responses, trade intents, and regime API.

| Value           | Description                              |
| --------------- | ---------------------------------------- |
| `CRISIS`        | Severe drawdown, capitulation-level fear |
| `BEAR_TREND`    | Sustained downtrend                      |
| `BEAR_RECOVERY` | Early recovery from bear market          |
| `CHOP`          | Sideways, range-bound                    |
| `BULL_TREND`    | Established uptrend                      |
| `EUPHORIA`      | Late-stage rally, extreme greed          |
| `DEFAULT`       | No strong classification                 |

***

## Next

* [All Endpoints](/use-the-signal/reference/endpoints.md) -- endpoint reference
* [Changelog](/use-the-signal/reference/changelog.md) -- model version history