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

# TypeScript Types Reference for the @outcome.xyz/hip4 SDK

> All exported TypeScript types from @outcome.xyz/hip4: market shapes, event and outcome types, order params, account state, and market data interfaces.

This page documents all exported TypeScript types from `@outcome.xyz/hip4`. Every type listed here is importable from the main entry point. If you only need types without pulling in any runtime code - for example in a shared type package - use the dedicated types entry point instead.

<Note>
  Import types without any runtime cost using `@outcome.xyz/hip4/types`:

  ```typescript theme={null}
  import type { HIP4Market, MarketType } from "@outcome.xyz/hip4/types";
  ```
</Note>

## Market types

HIP-4 markets are represented as a discriminated union. Every market carries a `type` field you can use to narrow to the correct variant.

### `MarketType`

```typescript theme={null}
type MarketType = "defaultBinary" | "labelledBinary" | "multiOutcome" | "priceBucket";
```

### `HIP4Market`

The top-level discriminated union covering all four market variants:

```typescript theme={null}
type HIP4Market =
  | DefaultBinaryMarket
  | LabelledBinaryMarket
  | MultiOutcomeMarket
  | PriceBucketMarket;
```

### `BaseMarket`

Fields shared across all market types:

| Field | Type | Description |
| - | - | - |
| `type` | `MarketType` | Discriminant for narrowing the union |
| `outcomeId` | `number` | Hyperliquid outcome ID |
| `name` | `string` | Market name as Hyperliquid sends it (e.g. `"template:priceTouch"`). `defaultBinary` markets get a label such as `"BTC > $69070 (1d)"` |
| `parsedName?` | `string` | Readable market name, rendered from Hyperliquid's template registry for template markets (e.g. `"BTC touches 90000 by Nov 1, 00:00 UTC"`). A template question's fallback outcome reads `"Other"`. Other markets repeat `name`. Available from 1.3.0 |
| `description` | `string` | Human-readable market description |
| `sides` | `[MarketSide, MarketSide]` | Both tradeable sides with pre-computed identifiers |
| `raw` | `HLOutcome` | Raw Hyperliquid API response, for escape-hatch access |

### `MarketSide`

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Side label as Hyperliquid sends it (e.g. `"Yes"`, `"Hypurr"`, `"template:Yes"`) |
| `parsedName?` | `string` | Readable side label (`"template:Yes"` reads `"Yes"`). Other sides repeat `name`. Available from 1.3.0 |
| `coinNum` | `number` | Raw coin number: `outcomeId * 10 + sideIndex` |
| `coin` | `string` | Coin string for API calls (e.g. `"#5160"`) |
| `asset` | `number` | Order asset field: `100_000_000 + coinNum` |

### `DefaultBinaryMarket`

Recurring price binary markets with a structured pipe-delimited description. Extends `BaseMarket`.

| Field | Type | Description |
| - | - | - |
| `type` | `"defaultBinary"` | Type discriminant |
| `underlying` | `string` | Underlying asset symbol (e.g. `"BTC"`, `"ETH"`) |
| `targetPrice` | `number` | Strike price |
| `expiry` | `Date` | Expiry timestamp in UTC |
| `period` | `string` | Market period (e.g. `"15m"`, `"1h"`, `"1d"`) |

### `LabelledBinaryMarket`

Standalone binary markets with custom side names. Extends `BaseMarket` with no additional fields.

| Field | Type | Description |
| - | - | - |
| `type` | `"labelledBinary"` | Type discriminant |

### `MultiOutcomeMarket`

Outcomes grouped under a parent question, with a fallback outcome representing "none of the above". Extends `BaseMarket`.

| Field | Type | Description |
| - | - | - |
| `type` | `"multiOutcome"` | Type discriminant |
| `questionId` | `number` | Parent question ID |
| `questionName` | `string` | Parent question name as Hyperliquid sends it |
| `parsedQuestionName?` | `string` | Readable parent question name, rendered like `parsedName`. Available from 1.3.0 |
| `questionDescription` | `string` | Parent question description |
| `isFallback` | `boolean` | `true` if this is the fallback ("Other") outcome |
| `rawQuestion` | `HLQuestion` | Raw parent question from the API |

### `PriceBucketMarket`

Multi-bucket price range markets where each outcome covers a specific price band. Extends `BaseMarket`.

| Field | Type | Description |
| - | - | - |
| `type` | `"priceBucket"` | Type discriminant |
| `underlying` | `string` | Underlying asset symbol |
| `expiry` | `Date` | Expiry timestamp in UTC |
| `priceThresholds` | `number[]` | Sorted ascending price boundaries; N thresholds produce N+1 buckets |
| `period` | `string` | Market period (e.g. `"15m"`) |
| `questionId` | `number` | Parent question ID |
| `questionName` | `string` | Parent question name as Hyperliquid sends it |
| `parsedQuestionName?` | `string` | Readable parent question name, rendered like `parsedName`. Available from 1.3.0 |
| `questionDescription` | `string` | Parent question description (the raw `priceBucket` spec) |
| `isFallback` | `boolean` | `true` if this is the settlement fallback outcome |
| `bucketIndex` | `number` | Index within the question's named outcomes; `-1` for fallback |
| `lowerBound` | `number \| null` | Inclusive lower bound; `null` = unbounded below |
| `upperBound` | `number \| null` | Exclusive upper bound; `null` = unbounded above |
| `rawQuestion` | `HLQuestion` | Raw parent question from the API |

## Event types

Events are the top-level grouping for prediction markets.

### `PredictionEvent`

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Event ID (`"q<n>"` for questions, `"o<n>"` for standalone outcomes) |
| `title` | `string` | Title as Hyperliquid sends it (e.g. `"template:priceTouch"`) |
| `parsedTitle?` | `string` | Readable title, rendered from Hyperliquid's template registry for template events. Other events repeat `title`. Available from 1.3.0 |
| `description` | `string` | Full description |
| `category` | `string` | Category slug (`"custom"` or `"recurring"`) |
| `markets` | `PredictionMarket[]` | Markets belonging to this event |
| `totalVolume` | `string` | Total trading volume across all markets. Always `"0"` in the HIP-4 adapter |
| `endDate` | `string` | Expiry date string; populated for recurring markets, empty otherwise |
| `status` | `PredictionEventStatus` | Current lifecycle status |
| `imageUrl?` | `string` | Optional cover image URL. Not set by the HIP-4 adapter |
| `resolutionSource?` | `string` | Optional link to resolution criteria. Not set by the HIP-4 adapter |

### `PredictionMarket`

A single question within an event containing tradeable outcome tokens.

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Market ID (the outcome ID as a string) |
| `eventId` | `string` | Parent event ID |
| `question` | `string` | Market question text as Hyperliquid sends it |
| `parsedQuestion?` | `string` | Readable question text, rendered like `PredictionEvent.parsedTitle`. Available from 1.3.0 |
| `outcomes` | `PredictionOutcome[]` | Tradeable sides |
| `volume` | `string` | Trading volume. Always `"0"` in the HIP-4 adapter |
| `liquidity` | `string` | Current liquidity. Always `"0"` in the HIP-4 adapter |
| `isNegRisk?` | `boolean` | Whether the market uses negative-risk (multi-outcome) pricing. Not set by the HIP-4 adapter |

### `PredictionOutcome`

One tradeable side of a prediction market.

| Field | Type | Description |
| - | - | - |
| `name` | `string` | Side name as Hyperliquid sends it (e.g. `"Yes"`, `"template:Yes"`) |
| `parsedName?` | `string` | Readable side name (`"template:Yes"` reads `"Yes"`). Available from 1.3.0 |
| `tokenId` | `string` | Side coin identifier (e.g. `"#5160"`) |
| `price` | `string` | Current mid-price (0 to 1 range) |

### `PredictionCategory`

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Category identifier |
| `name` | `string` | Display name |
| `slug` | `string` | URL-safe slug |

The SDK defines two built-in categories: `"custom"` (manually created markets) and `"recurring"` (automated recurring markets).

### `PredictionEventStatus`

```typescript theme={null}
type PredictionEventStatus = "active" | "pending_resolution" | "resolved" | "cancelled";
```

The HIP-4 adapter currently sets only `"active"` and `"resolved"`.

## Trading types

### `PredictionOrderParams`

Parameters for placing an order via `hip4.trading.placeOrder`.

| Field | Type | Required | Description |
| - | - | - | - |
| `marketId` | `string` | Yes | Outcome ID string (e.g. `"516"`) |
| `outcome` | `string` | Yes | Side coin (e.g. `"#5160"`) |
| `side` | `"buy" \| "sell"` | Yes | Trade direction |
| `type` | `"market" \| "limit"` | Yes | Order type |
| `price` | `string` | For limit | Limit price in the 0 to 1 range (e.g. `"0.65"`) |
| `amount` | `string` | Yes | Number of shares as a string |
| `timeInForce` | `"GTC" \| "GTD" \| "FOK" \| "FAK" \| "ALO"` | No | Default: `"GTC"` for limit orders. `"GTD"` and `"FOK"` aren't supported and throw |
| `expiration` | `string` | No | Not used by the HIP-4 adapter (GTD isn't supported) |
| `markPx` | `number` | No | Mark price; enables min-shares validation when provided |
| `builderAddress` | `string` | No | Builder address that receives builder fees |
| `builderFee` | `number` | No | Fee in tenths of a basis point (100 = 0.1%, max 1000) |
| `skipMinNotionalCheck` | `boolean` | No | Skip the \$1 minimum (or `minOrderNotional`) and min-shares checks; use for position-closing flows |

### `PredictionOrderResult`

Returned by `hip4.trading.placeOrder` and `hip4.trading.modifyOrder`. Rejections come back in this object instead of being thrown, so always check `success`.

| Field | Type | Description |
| - | - | - |
| `success` | `boolean` | Whether the order was accepted |
| `orderId?` | `string` | Order ID for filled or resting orders |
| `status?` | `string` | Exchange status string (`"filled"`, `"resting"`, `"error"`, `"unknown"`) |
| `shares?` | `string` | Filled size (for filled orders) |
| `error?` | `string` | Rejection reason (when `success` is `false`). A whole-request rejection reads `"Exchange returned non-ok status"` |
| `raw?` | `string` | Hyperliquid's own message for a whole-request rejection (e.g. `"User or API Wallet 0x... does not exist."`), when it sends one. Available from 1.3.0 |

### `PredictionBatchOrderResult`

Returned by `hip4.trading.placeOrders` (batch). Results are index-matched to the input params array.

| Field | Type | Description |
| - | - | - |
| `success` | `boolean` | `true` only when every individual order succeeded |
| `results` | `PredictionOrderResult[]` | Per-order results in input order |

### `PredictionCancelParams`

Parameters for cancelling a resting order via `hip4.trading.cancelOrder`.

| Field | Type | Description |
| - | - | - |
| `marketId` | `string` | The outcome ID string |
| `orderId` | `string` | The order ID to cancel |
| `outcome?` | `string` | Side coin (e.g. `"#5160"`); used to resolve the correct asset ID. Defaults to side 0 if omitted |

## Account types

### `PredictionPosition`

An open position in a prediction market outcome, derived from spot balances.

| Field | Type | Description |
| - | - | - |
| `marketId` | `string` | Outcome ID |
| `eventTitle` | `string` | Title of the parent event |
| `parsedEventTitle?` | `string` | Readable title of the parent event. Available from 1.3.0 |
| `marketQuestion` | `string` | Question text of the parent market |
| `parsedMarketQuestion?` | `string` | Readable question text of the parent market. Available from 1.3.0 |
| `outcome` | `string` | Balance coin as Hyperliquid reports it (e.g. `"+90"`) |
| `outcomeName` | `string` | Side name from `sideSpecs` (e.g. `"Hypurr"`, `"Yes"`, `"template:Yes"`) |
| `parsedOutcomeName?` | `string` | Readable side name (`"template:Yes"` reads `"Yes"`). Available from 1.3.0 |
| `shares` | `string` | Number of shares held |
| `avgCost` | `string` | Average entry cost per share (entry notional / shares) |
| `currentPrice` | `string` | The side's live mid-price (the `#<coin>` mid for the `+<coin>` balance), or `"0"` when it has none |
| `unrealizedPnl` | `string` | Unrealized profit/loss in USDC at `currentPrice` |
| `potentialPayout` | `string` | Maximum payout if the outcome resolves in your favor |
| `eventStatus` | `"active" \| "pending_resolution" \| "resolved"` | Event lifecycle state. Always `"active"` in the HIP-4 adapter |

### `PredictionActivity`

A historical account activity record.

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Activity record ID |
| `type` | `"trade" \| "redeem" \| "deposit" \| "withdrawal"` | Activity type. The HIP-4 adapter only returns `"trade"` |
| `marketId?` | `string` | Outcome ID (for trade and redeem entries) |
| `outcome?` | `string` | Side coin (for trade entries) |
| `side?` | `"buy" \| "sell"` | Trade direction (for trade entries) |
| `price?` | `string` | Fill price (for trade entries) |
| `size?` | `string` | Fill size (for trade entries) |
| `amount?` | `string` | USDC amount (for deposit and withdrawal entries) |
| `timestamp` | `number` | Unix timestamp in milliseconds |

### `PredictionAuthState`

The current authentication state of the trading adapter.

| Field | Type | Description |
| - | - | - |
| `status` | `"disconnected" \| "pending_approval" \| "ready"` | Auth lifecycle state (`initAuth` goes straight to `"ready"`) |
| `address?` | `string` | The user's wallet address, set after `initAuth` |

## Market data types

### `PredictionOrderBook`

| Field | Type | Description |
| - | - | - |
| `marketId` | `string` | Outcome ID |
| `bids` | `PredictionOrderBookLevel[]` | Buy-side price levels, best bid first |
| `asks` | `PredictionOrderBookLevel[]` | Sell-side price levels, best ask first |
| `timestamp` | `number` | Snapshot timestamp in milliseconds |

### `PredictionOrderBookLevel`

| Field | Type | Description |
| - | - | - |
| `price` | `string` | Price level |
| `size` | `string` | Aggregate size at this level |

### `PredictionPrice`

| Field | Type | Description |
| - | - | - |
| `marketId` | `string` | Outcome ID |
| `outcomes` | `Array<{ name: string; parsedName?: string; price: string; midpoint: string }>` | Current prices for both sides, with side names from `sideSpecs`. `parsedName` is the readable side name (`"template:Yes"` reads `"Yes"`), available from 1.3.0 |
| `timestamp` | `number` | Price snapshot timestamp in milliseconds |

### `PredictionTrade`

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Trade ID |
| `marketId` | `string` | Outcome ID |
| `outcome` | `string` | Side coin name |
| `side` | `"buy" \| "sell"` | Trade direction |
| `price` | `string` | Fill price |
| `size` | `string` | Fill size |
| `timestamp` | `number` | Fill timestamp in milliseconds |


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