---
title: "List HIP-4 outcomes"
method: GET
path: "/v1/hyperliquid/hip4/outcomes"
tags: ["HIP-4 Outcomes - Outcomes"]
---

# List HIP-4 outcomes

`GET /v1/hyperliquid/hip4/outcomes`

## Request

- Base URL: `https://api.0xarchive.io`
- URL: `https://api.0xarchive.io/v1/hyperliquid/hip4/outcomes`
- Auth: API key in header `X-API-Key`

List HIP-4 outcome markets (one row per outcome, both sides combined). Optional `is_settled` filter. Cursor pagination. Response uses `Hip4OutcomeAggregate` and OMITS the `aggregated_oi` field. Use `/outcomes/{outcome_id}` to fetch a single outcome with `aggregated_oi` populated. Data available from May 2026.

## Query parameters

- `is_settled` boolean
- `slug` string
- `cursor` string
- `limit` integer

## Response `200`

List of HIP-4 outcomes (without `aggregated_oi`)

- ApiResponseHip4OutcomeAggregateArray: API response wrapping an array of HIP-4 outcome aggregates (without `aggregated_oi`; use `/outcomes/{outcome_id}` for the detail variant)
  - `success` boolean
  - `data` Hip4OutcomeAggregate[]
    - `outcome_id` integer, required: Numeric outcome identifier
    - `name` string, nullable: Human-readable outcome name (without per-side suffix)
    - `description_raw` string, nullable: Pipe-delimited recurring-market metadata as emitted upstream
    - `class` string, nullable: Outcome class (e.g., `priceBinary`)
    - `underlying` string, nullable: Underlying asset for recurring price-binary outcomes
    - `expiry` string, date-time, nullable: Settlement timestamp (UTC)
    - `target_price` number, nullable: Target price for the binary outcome
    - `period` string, nullable: Cadence of the recurring market (e.g., `1d`, `1h`)
    - `side_specs` Hip4SideSpec[], required: Per-side specs. Typically two elements: side 0 (Yes) and side 1 (No).
      - `side` 0 | 1, required: Side index: 0 = Yes, 1 = No
      - `name` string, required: Human label for this side
      - `coin` string, required: Coin identifier for this side. Returned in `#`-prefixed form. REST paths accept either the bare numeric id (e.g. `0`) or the `#`-prefixed form (e.g. `#0`).
      - `asset_id` integer, required: Public asset ID for this side
    - `is_settled` boolean, required: Whether the outcome has settled
    - `status` string, nullable: Lifecycle status (`live`, `settled`, ...)
    - `source_seen_at` string, date-time, nullable: Last time the outcome was seen upstream
    - `aggregated_oi` Hip4AggregatedOi: Derived OI display fields combining both sides of a HIP-4 outcome. Currency is always `USDH` (Hyperliquid's stablecoin). Only populated on `/outcomes/{outcome_id}` (detail), NOT on `/outcomes` (list).
      - `side0_open_interest_contracts` number, nullable: Latest open-interest contracts for side 0 (Yes)
      - `side1_open_interest_contracts` number, nullable: Latest open-interest contracts for side 1 (No)
      - `outcome_display_open_interest_contracts` number, nullable: Display total: sum of side0 + side1 OI contracts. Use this for outcome-level OI dashboards.
      - `paired_set_supply_contracts` number, nullable: Paired-set supply: minimum of side0 and side1 OI contracts. Represents the count of fully collateralized Yes+No pairs in circulation.
      - `side_supply_parity` boolean, nullable: True when side0 OI equals side1 OI within tolerance. Parity should hold for binary outcomes; a sustained false value indicates ingestion drift.
      - `currency` 'USDH', required: Notional currency. Always `USDH` for HIP-4.
      - `as_of` string, date-time, nullable: Latest timestamp across both sides
      - `side0_as_of` string, date-time, nullable: Timestamp of the side 0 OI sample
      - `side1_as_of` string, date-time, nullable: Timestamp of the side 1 OI sample
  - `meta` ResponseMeta: Response metadata. Every 2xx JSON response carries `meta.request_id`; list payloads add `count`; cursor-paged routes add `has_more` and, when another page follows, `next_cursor`; per-symbol routes add `symbol` and `venue`. Fields that do not apply to a route are omitted.
    - `count` integer: Number of records returned
    - `has_more` boolean: Cursor-paged routes: whether another page follows. `next_cursor` is present exactly when this is `true`. A final page can be empty when the previous page was exactly full; `has_more` is `false` on it.
    - `next_cursor` string: Opaque cursor for the next page, present exactly when `has_more` is `true`. Pass it back unchanged as `cursor` with the same filters. Do not parse or construct it.
    - `request_id` string, uuid, required: Unique request ID for support
    - `symbol` string: Per-symbol routes: the canonical public symbol the response describes (for example `BTC`, `xyz:TSLA`, `HYPE-USDC`, `#0`).
    - `venue` 'hyperliquid' | 'hip3' | 'hip4' | 'spot' | 'lighter' | 'rh-lighter': Per-symbol routes: the venue the response describes.
    - `coverage_from` string, date-time: Earliest coverage for the requested symbol and data type. Present only when the requested window ends before coverage begins.
    - `notice` string: Human-readable advisory about the response. Used when the requested window ends before coverage begins for the symbol, and on CVD responses that are one page of several; may carry other advisories in future.
    - `finalized_through` string, date-time: Two-tier datasets (Lighter trades): data at or before this instant is final; later data is preliminary.
    - `requested_end` string, date-time, nullable: The `end` the request asked for, echoed when it was clamped to `finalized_through`.
    - `clamped_to` string, date-time, nullable: The boundary the request's `end` was clamped to, when clamping occurred.
    - `preliminary_row_count` integer, nullable: Number of preliminary rows in this response, on routes that intentionally serve preliminary data (Lighter `/recent`).

## Other responses

- `400`: Invalid request: a parameter, symbol, interval, cursor or time range failed validation. See `error_code`.
- `401`: Authentication required: the API key is missing or invalid.
- `403`: The request is outside the plan's history window or per-request span, or the key is not allowed to make it.
- `429`: Rate limit, concurrency limit or monthly credits exceeded. See `error_code`.
- `default`: Any other error. The body is an `ErrorResponse`; branch on `error_code`. A 503 (`upstream_unavailable`) carries `Retry-After`.

---

[API](https://skmtc.dev/0xarchive/apis/0xarchive-api-2.md) · [All operations](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/0xarchive/apis/0xarchive-api-2/revisions/27076f55595f?raw)