Hip4Outcome Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Hip4Outcome",
  "description": "HIP-4 per-side instrument metadata. One row per `#N` coin. Each outcome has two sides: side 0 (Yes) and side 1 (No). Public asset_id formula: `100_000_000 + 10*outcome_id + side`. Coin format: `#<10*outcome_id + side>`.",
  "type": "object",
  "required": [
    "asset_id",
    "coin",
    "outcome_id",
    "side",
    "symbol"
  ],
  "properties": {
    "asset_id": {
      "description": "Public asset ID. Formula: `100_000_000 + 10*outcome_id + side`.",
      "type": "integer",
      "format": "int64",
      "example": 100000000
    },
    "builder_address": {
      "description": "Builder wallet address that deployed the outcome",
      "type": "string",
      "nullable": true,
      "example": "0x0000000000000000000000000000000000000000"
    },
    "coin": {
      "description": "Coin identifier. Returned in `#`-prefixed form. REST paths accept either the bare numeric id (e.g. `0`) or the `#`-prefixed form (e.g. `#0`). Format: `10*outcome_id + side`.",
      "type": "string",
      "example": "#0"
    },
    "description": {
      "description": "Pipe-delimited recurring-market metadata",
      "type": "string",
      "nullable": true,
      "example": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d"
    },
    "display_title": {
      "description": "Per-side human-readable title, deterministic from parsed metadata.",
      "type": "string",
      "nullable": true,
      "example": "BTC above 78,213 on May 3 at 06:00 UTC? — Yes"
    },
    "first_seen_at": {
      "description": "When this outcome side was first observed by 0xArchive (UTC)",
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "example": "2026-05-02T07:47:00Z"
    },
    "is_settled": {
      "description": "Whether the outcome has settled. Once settled, live tracking ends for the market, but historical data remains queryable.",
      "type": "boolean",
      "example": false
    },
    "last_updated_at": {
      "description": "Timestamp when the side metadata was last updated",
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "example": "2026-05-02T20:25:00Z"
    },
    "name": {
      "description": "Human-readable per-side market name",
      "type": "string",
      "nullable": true,
      "example": "BTC ≥ 78213 by 2026-05-03 06:00 UTC — Yes"
    },
    "outcome_id": {
      "description": "Numeric outcome identifier",
      "type": "integer",
      "format": "int64",
      "example": 0
    },
    "recurring_class": {
      "description": "Recurring market class (e.g., `priceBinary`)",
      "type": "string",
      "nullable": true,
      "example": "priceBinary"
    },
    "recurring_expiry": {
      "description": "Settlement timestamp (UTC)",
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "example": "2026-05-03T06:00:00Z"
    },
    "recurring_period": {
      "description": "Cadence of the recurring market (e.g., `1d`, `1h`)",
      "type": "string",
      "nullable": true,
      "example": "1d"
    },
    "recurring_target_px": {
      "description": "Target price for the binary outcome",
      "type": "number",
      "nullable": true,
      "example": 78213
    },
    "recurring_underlying": {
      "description": "Underlying asset for recurring price-binary outcomes",
      "type": "string",
      "nullable": true,
      "example": "BTC"
    },
    "settlement_at": {
      "description": "Settlement timestamp (UTC). Omitted while unsettled.",
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "example": "2026-05-03T06:00:05.149Z"
    },
    "settlement_value": {
      "description": "Settlement value once the outcome settles (0.0 or 1.0 for binary outcomes). Omitted while unsettled.",
      "type": "number",
      "nullable": true,
      "example": 0
    },
    "side": {
      "description": "Side index: 0 = Yes, 1 = No",
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "example": 0
    },
    "side_name": {
      "description": "Human label for this side (typically `Yes` or `No`)",
      "type": "string",
      "nullable": true,
      "example": "Yes"
    },
    "slug": {
      "description": "Per-side URL slug mirroring Hyperliquid's pattern.",
      "type": "string",
      "nullable": true,
      "example": "btc-above-78213-yes-may-03-0600"
    },
    "symbol": {
      "description": "Same value as `coin`. Provided for consistency with other venues.",
      "type": "string",
      "example": "#0"
    }
  }
}