GDEX: Hyperliquid HIP-4 Outcome Markets
GDEX outcome markets are Hyperliquid HIP-4 outcome markets: each market has
two or more sides; each side is a token that trades at a probability price in
(0, 1), and the winning side settles on Hyperliquid. They are traded with spot
collateral (the market's quoteToken, USDC today) from the managed wallet's
Hyperliquid spot balance.
They are not HIP-3 builder perps, not perps, and not spot tokens. GDEX has
no Polymarket or Kalshi integration.
When to Use
- "What prediction / outcome markets can I trade?" → discover
- Buy or sell one side of an outcome market
- Track a resting order, cancel it, or exit a position fully or partially
- Explain what happens when a market expires or resolves
Prerequisites
@gemachdao/gdex-skill installed and a managed-custody session — see
gdex-authentication. You need apiKey, the control walletAddress
used at sign-in, and sessionPrivateKey. The SDK and the MCP tools build
and encrypt the payload for you; you don't need the backend ABI.
- The managed wallet address (outcome balances and orders live there).
- Quote collateral in the managed wallet's HL spot balance (step 3).
Workflow
1. Discover
const { markets } = await skill.getHlOutcomeMarkets({ state: 'active', query: 'BTC' });
MCP: hl_outcomes (state, query, excludeFallback, limit (default 20), offset, sortBy: "volume" | "expiry", detail, withVolume). It returns compact pages; ask for detail: true only for the markets you will trade.
Each market is normalised:
| Field |
Meaning |
Source |
outcomeId |
Market id |
outcomeMeta.outcomes[].outcome |
title |
Readable question built from the market parameters |
name + description (key:value|…), question parameters |
sides[] |
{ sideIndex, label, rawName, coin, balanceCoin, assetId, exchangeAssetId, price } |
sideSpecs[]. coin = #<token> or #<outcomeId*10+sideIndex>. balanceCoin = +<assetId>. price = allMids[coin]. |
quoteToken |
Collateral currency |
outcomes[].quoteToken |
state |
active · pre_launch (no mids yet) · expired (deadline passed, not yet settled) · settled |
questions[].settledNamedOutcomes, the expiry parameter, allMids |
rules |
Price 0.00001–0.99999, tick 0.00001 (5 dp); whole-contract size; min notional 11 quote; full-position sell exempt; market orders ±5%; reduceOnlyHonoured: false |
GDEX backend + gdex.pro (see Rules) |
settlement |
claimViaGdex: false, resolution source and deadline, and what to do |
see "Expiry and settlement" |
volume24h |
Only with withVolume: { volume, asOf, source, coverage }. coverage is complete, partial or unavailable. A zero that was actually read stays 0; null means no reading. The wait is bounded (default 2.5 s), so a slow feed never blocks discovery. |
Hyperliquid WS activeAssetCtx.dayNtlVlm |
isFallback: true marks the "none of the listed outcomes" leg of a
multi-outcome question.
2. Pick a side
Read sides[].label. Don't assume side 0 is "Yes".
- A match market's sides can be the two team names (
LOS / T1).
- A question can have one market per candidate, each with its own Yes/No.
Select a side with exactly one of these:
coin (e.g. "#143151")
sideIndex
sideLabel (exact label)
The SDK rejects a coin that doesn't belong to outcomeId.
3. Check collateral
const c = await skill.checkHlOutcomeCollateral({
managedAddress, quoteToken: market.quoteToken, size: '120', price: '0.12',
});
// { available, required: 14.4, sufficient: true|false, ... }
MCP: hl_outcome_check_collateral.
- Buys draw on the managed wallet's HL spot balance of
quoteToken
(total − hold), not on the perp account.
- If it's short, move USDC from perp to spot or fund the account. See
gdex-perp-funding.
- If a market is ever quoted in a token other than USDC, swap into it with
hl_swap_collateral first.
4. Place a limit order
const r = await skill.createHlOutcomeOrder({
apiKey, walletAddress /* control */, sessionPrivateKey,
outcomeId: 14315, sideLabel: 'Yes', isBuy: true,
price: '0.12', // probability, at most 5 decimals
size: '120', // whole contracts; 120 × 0.12 = 14.4 ≥ 11
});
// r.status: 'resting' (r.orderId) | 'filled' (r.filledSize, r.avgPrice) | 'rejected' (r.error)
MCP: hl_create_outcome_order.
isBuy: false sells side tokens you hold. It can't short.
isMarket: true takes the book at ±5% of the top level. Omit price
(or pass "0") for market orders.
- Pass
managedAddress on sells. The SDK then checks the real position, and
a sell of the whole position is allowed below the minimum.
5. Track resting and fill state
const s = await skill.getHlOutcomeAccountState({ userAddress: managedAddress, outcomeId: 14315 });
MCP: hl_outcome_account. It returns:
positions[]: size, hold, available, avgEntryPrice, markPrice,
value, unrealizedPnl.
openOrders[]: orderId, price, size, originalSize, filledSize,
and status (resting or partially_filled).
fills[].
historicalOrders[], with Hyperliquid's status, e.g. filled, canceled,
minTradeNtlRejected.
6. Cancel, or exit fully or partially
await skill.cancelHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,
outcomeId: 14315, coin: '#143150', orderId: String(r.orderId) });
// Full exit: omit size (the backend sells everything available).
await skill.closeHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,
outcomeId: 14315, sideLabel: 'Yes', price: '0.15' });
// Partial exit: the sold part AND the remainder must each be worth ≥ 11.
await skill.closeHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,
outcomeId: 14315, sideLabel: 'Yes', price: '0.15', size: '80', managedAddress });
MCP: hl_cancel_outcome_order and hl_close_outcome_order.
orderId is the numeric Hyperliquid oid.
- A close is always a sell of held tokens.
- Any partial fill that happened before a cancel stays in the position.
7. Reconcile
Call hl_outcome_account again. Check that:
- a cancelled order has left
openOrders;
- fills are in
fills;
positions[].available matches what you expect.
If a write's outcome is unknown, check here before you submit anything again.
Rules (and where they come from)
- Price must be in (0, 1). The backend rounds to 5 decimals
(
hyperLiquidOutcomes.ts:85-91). The SDK rejects anything outside
[0.00001, 0.99999] or with more than 5 decimals.
- Size is whole contracts (
OUTCOME_SIZE_DECIMALS = 0,
hyperLiquidOutcomes.ts:69,185-188).
- Minimum order is size × price ≥ 11 quote units. This is gdex.pro's
rule (
HyperliquidOutcomeDetail.tsx:84). Hyperliquid's own floor is 10. A
sell of the full position is exempt. Partial closes must leave both legs at
11 or more.
reduceOnly is ignored: the backend always sends r:false.
- Tick size and minimum order aren't per-market fields in
outcomeMeta.
The rules above apply to every outcome market.
Parameter modes
Every write accepts either the structured fields or a pre-built
computedData on its own. Never mix them.
- Structured fields: the SDK validates against the live market first.
- Pre-built
computedData: posted as is, with no validation.
A mix of the two is rejected with VALIDATION_ERROR before anything is signed
or sent, as are missing structured fields. dex and status are not read by
the backend for outcomes.
Expiry and settlement
expired: the market's deadline has passed, but Hyperliquid hasn't
marked it settled yet. The SDK refuses new orders. You can still try to
exit with hl_close_outcome_order, but it may fail if the book has halted.
settled: the outcome is listed in its question's
settledNamedOutcomes. There is no book.
- Settlement is done on Hyperliquid by the market deployer (the
settleOutcome and settleQuestion permissions in outcomeMeta.deployers).
- GDEX has no claim, redeem or settle endpoint. The backend's outcome
routes are exactly:
outcomes, outcome_account, outcome/create_order,
outcome/cancel_order, outcome/close_order. After resolution there is
nothing to claim through GDEX. Read the managed wallet's HL spot balances
(hl_outcome_account) to see the result.
Backend endpoints
| Method |
Path |
Notes |
GET |
/v1/hl/outcomes |
{ meta: outcomeMeta, mids: allMids }. Ignores query params. outcomeMeta is cached for 60 s. |
GET |
/v1/hl/outcome_account?address=<managed>&outcomeId=<id> |
positions (spot balances +<assetId>), openOrders, fills, historicalOrders |
POST |
/v1/hl/outcome/create_order |
{ computedData } |
POST |
/v1/hl/outcome/cancel_order |
{ computedData } |
POST |
/v1/hl/outcome/close_order |
{ computedData } (always a sell) |
1---2name: gdex-hl-outcomes3description: Hyperliquid HIP-4 outcome markets on GDEX — discover a market, pick a side, check spot collateral, place a limit order, track resting/fill state, cancel or exit (partial/full), and reconcile4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/gdex-hl-outcomes6---78# GDEX: Hyperliquid HIP-4 Outcome Markets910GDEX outcome markets are **Hyperliquid HIP-4 outcome markets**: each market has11two or more sides; each side is a token that trades at a probability price in12(0, 1), and the winning side settles on Hyperliquid. They are traded with spot13collateral (the market's `quoteToken`, USDC today) from the managed wallet's14**Hyperliquid spot balance**.1516They are **not** HIP-3 builder perps, not perps, and not spot tokens. **GDEX has17no Polymarket or Kalshi integration.**1819## When to Use2021- "What prediction / outcome markets can I trade?" → discover22- Buy or sell one side of an outcome market23- Track a resting order, cancel it, or exit a position fully or partially24- Explain what happens when a market expires or resolves2526## Prerequisites2728- `@gemachdao/gdex-skill` installed and a managed-custody session — see29 **gdex-authentication**. You need `apiKey`, the **control** `walletAddress`30 used at sign-in, and `sessionPrivateKey`. The SDK and the MCP tools build31 and encrypt the payload for you; you don't need the backend ABI.32- The **managed** wallet address (outcome balances and orders live there).33- Quote collateral in the managed wallet's **HL spot** balance (step 3).3435## Workflow3637### 1. Discover3839```typescript40const { markets } = await skill.getHlOutcomeMarkets({ state: 'active', query: 'BTC' });41```4243MCP: `hl_outcomes` (`state`, `query`, `excludeFallback`, `limit` (default 20), `offset`, `sortBy: "volume" | "expiry"`, `detail`, `withVolume`). It returns compact pages; ask for `detail: true` only for the markets you will trade.44Each market is normalised:4546| Field | Meaning | Source |47|---|---|---|48| `outcomeId` | Market id | `outcomeMeta.outcomes[].outcome` |49| `title` | Readable question built from the market parameters | `name` + `description` (`key:value\|…`), question parameters |50| `sides[]` | `{ sideIndex, label, rawName, coin, balanceCoin, assetId, exchangeAssetId, price }` | `sideSpecs[]`. `coin` = `#<token>` or `#<outcomeId*10+sideIndex>`. `balanceCoin` = `+<assetId>`. `price` = `allMids[coin]`. |51| `quoteToken` | Collateral currency | `outcomes[].quoteToken` |52| `state` | `active` · `pre_launch` (no mids yet) · `expired` (deadline passed, not yet settled) · `settled` | `questions[].settledNamedOutcomes`, the expiry parameter, `allMids` |53| `rules` | Price 0.00001–0.99999, tick 0.00001 (5 dp); whole-contract size; min notional 11 quote; full-position sell exempt; market orders ±5%; `reduceOnlyHonoured: false` | GDEX backend + gdex.pro (see Rules) |54| `settlement` | `claimViaGdex: false`, resolution source and deadline, and what to do | see "Expiry and settlement" |55| `volume24h` | Only with `withVolume`: `{ volume, asOf, source, coverage }`. `coverage` is `complete`, `partial` or `unavailable`. A zero that was actually read stays `0`; `null` means no reading. The wait is bounded (default 2.5 s), so a slow feed never blocks discovery. | Hyperliquid WS `activeAssetCtx.dayNtlVlm` |5657`isFallback: true` marks the "none of the listed outcomes" leg of a58multi-outcome question.5960### 2. Pick a side6162Read `sides[].label`. **Don't assume side 0 is "Yes".**6364- A match market's sides can be the two team names (`LOS` / `T1`).65- A question can have one market per candidate, each with its own Yes/No.6667Select a side with exactly one of these:6869- `coin` (e.g. `"#143151"`)70- `sideIndex`71- `sideLabel` (exact label)7273The SDK rejects a coin that doesn't belong to `outcomeId`.7475### 3. Check collateral7677```typescript78const c = await skill.checkHlOutcomeCollateral({79 managedAddress, quoteToken: market.quoteToken, size: '120', price: '0.12',80});81// { available, required: 14.4, sufficient: true|false, ... }82```8384MCP: `hl_outcome_check_collateral`.8586- Buys draw on the managed wallet's HL **spot** balance of `quoteToken`87 (`total − hold`), not on the perp account.88- If it's short, move USDC from perp to spot or fund the account. See89 **gdex-perp-funding**.90- If a market is ever quoted in a token other than USDC, swap into it with91 `hl_swap_collateral` first.9293### 4. Place a limit order9495```typescript96const r = await skill.createHlOutcomeOrder({97 apiKey, walletAddress /* control */, sessionPrivateKey,98 outcomeId: 14315, sideLabel: 'Yes', isBuy: true,99 price: '0.12', // probability, at most 5 decimals100 size: '120', // whole contracts; 120 × 0.12 = 14.4 ≥ 11101});102// r.status: 'resting' (r.orderId) | 'filled' (r.filledSize, r.avgPrice) | 'rejected' (r.error)103```104105MCP: `hl_create_outcome_order`.106107- `isBuy: false` sells side tokens you hold. It can't short.108- `isMarket: true` takes the book at ±5% of the top level. Omit `price`109 (or pass `"0"`) for market orders.110- Pass `managedAddress` on sells. The SDK then checks the real position, and111 a sell of the whole position is allowed below the minimum.112113### 5. Track resting and fill state114115```typescript116const s = await skill.getHlOutcomeAccountState({ userAddress: managedAddress, outcomeId: 14315 });117```118119MCP: `hl_outcome_account`. It returns:120121- `positions[]`: `size`, `hold`, `available`, `avgEntryPrice`, `markPrice`,122 `value`, `unrealizedPnl`.123- `openOrders[]`: `orderId`, `price`, `size`, `originalSize`, `filledSize`,124 and `status` (`resting` or `partially_filled`).125- `fills[]`.126- `historicalOrders[]`, with Hyperliquid's status, e.g. `filled`, `canceled`,127 `minTradeNtlRejected`.128129### 6. Cancel, or exit fully or partially130131```typescript132await skill.cancelHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,133 outcomeId: 14315, coin: '#143150', orderId: String(r.orderId) });134135// Full exit: omit size (the backend sells everything available).136await skill.closeHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,137 outcomeId: 14315, sideLabel: 'Yes', price: '0.15' });138139// Partial exit: the sold part AND the remainder must each be worth ≥ 11.140await skill.closeHlOutcomeOrder({ apiKey, walletAddress, sessionPrivateKey,141 outcomeId: 14315, sideLabel: 'Yes', price: '0.15', size: '80', managedAddress });142```143144MCP: `hl_cancel_outcome_order` and `hl_close_outcome_order`.145146- `orderId` is the numeric Hyperliquid oid.147- A close is always a sell of held tokens.148- Any partial fill that happened before a cancel stays in the position.149150### 7. Reconcile151152Call `hl_outcome_account` again. Check that:153154- a cancelled order has left `openOrders`;155- fills are in `fills`;156- `positions[].available` matches what you expect.157158If a write's outcome is unknown, check here before you submit anything again.159160## Rules (and where they come from)161162- **Price** must be in (0, 1). The backend rounds to 5 decimals163 (`hyperLiquidOutcomes.ts:85-91`). The SDK rejects anything outside164 [0.00001, 0.99999] or with more than 5 decimals.165- **Size** is whole contracts (`OUTCOME_SIZE_DECIMALS = 0`,166 `hyperLiquidOutcomes.ts:69,185-188`).167- **Minimum order** is size × price ≥ **11** quote units. This is gdex.pro's168 rule (`HyperliquidOutcomeDetail.tsx:84`). Hyperliquid's own floor is 10. A169 sell of the full position is exempt. Partial closes must leave both legs at170 11 or more.171- **`reduceOnly`** is ignored: the backend always sends `r:false`.172- **Tick size and minimum order** aren't per-market fields in `outcomeMeta`.173 The rules above apply to every outcome market.174175## Parameter modes176177Every write accepts **either** the structured fields **or** a pre-built178`computedData` on its own. Never mix them.179180- **Structured fields:** the SDK validates against the live market first.181- **Pre-built `computedData`:** posted as is, with no validation.182183A mix of the two is rejected with `VALIDATION_ERROR` before anything is signed184or sent, as are missing structured fields. `dex` and `status` are not read by185the backend for outcomes.186187## Expiry and settlement188189- **`expired`:** the market's deadline has passed, but Hyperliquid hasn't190 marked it settled yet. The SDK refuses new orders. You can still try to191 exit with `hl_close_outcome_order`, but it may fail if the book has halted.192- **`settled`:** the outcome is listed in its question's193 `settledNamedOutcomes`. There is no book.194- **Settlement is done on Hyperliquid** by the market deployer (the195 `settleOutcome` and `settleQuestion` permissions in `outcomeMeta.deployers`).196- **GDEX has no claim, redeem or settle endpoint.** The backend's outcome197 routes are exactly: `outcomes`, `outcome_account`, `outcome/create_order`,198 `outcome/cancel_order`, `outcome/close_order`. After resolution there is199 nothing to claim through GDEX. Read the managed wallet's HL spot balances200 (`hl_outcome_account`) to see the result.201202## Backend endpoints203204| Method | Path | Notes |205|--------|------|-------|206| `GET` | `/v1/hl/outcomes` | `{ meta: outcomeMeta, mids: allMids }`. Ignores query params. `outcomeMeta` is cached for 60 s. |207| `GET` | `/v1/hl/outcome_account?address=<managed>&outcomeId=<id>` | positions (spot balances `+<assetId>`), openOrders, fills, historicalOrders |208| `POST` | `/v1/hl/outcome/create_order` | `{ computedData }` |209| `POST` | `/v1/hl/outcome/cancel_order` | `{ computedData }` |210| `POST` | `/v1/hl/outcome/close_order` | `{ computedData }` (always a sell) |