From 2d914c66dd9cc28aa4881cad3cb7d571e7c25d25 Mon Sep 17 00:00:00 2001 From: Ake <10195782+akegaviar@users.noreply.github.com> Date: Wed, 24 Jun 2026 15:04:00 +0800 Subject: [PATCH] docs(hyperliquid): add 4 missing HL method pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create reference pages (page + OpenAPI spec + nav) for methods present in the official Hyperliquid docs and the @nktkas/hyperliquid SDK but missing from our reference. Examples verified live against the public endpoint. info (Chainstack-served, Case A): - approvedBuilders — builders a user has approved (user param) - perpConciseAnnotations — per-asset category/displayName/keywords - settledOutcome — outcome-market spec + settlement (outcome param) exchange (signing action, public-only): - userOutcome — split/merge/negate outcome-market shares (4 operations) info examples: hyperliquid-python-sdk (info.post) + @nktkas/hyperliquid, both run live and return the documented data. userOutcome: signature-checked against the SDKs (never executed — it moves funds). --- docs.json | 4 + .../exchange_user_outcome.json | 154 ++++++++++++++++++ .../info_approved_builders.json | 69 ++++++++ .../info_perp_concise_annotations.json | 64 ++++++++ .../hypercore_info/info_settled_outcome.json | 115 +++++++++++++ .../hyperliquid-exchange-user-outcome.mdx | 132 +++++++++++++++ .../hyperliquid-info-approved-builders.mdx | 90 ++++++++++ ...erliquid-info-perp-concise-annotations.mdx | 92 +++++++++++ .../hyperliquid-info-settled-outcome.mdx | 107 ++++++++++++ 9 files changed, 827 insertions(+) create mode 100644 openapi/hyperliquid_node_api/hypercore_exchange/exchange_user_outcome.json create mode 100644 openapi/hyperliquid_node_api/hypercore_info/info_approved_builders.json create mode 100644 openapi/hyperliquid_node_api/hypercore_info/info_perp_concise_annotations.json create mode 100644 openapi/hyperliquid_node_api/hypercore_info/info_settled_outcome.json create mode 100644 reference/hyperliquid-exchange-user-outcome.mdx create mode 100644 reference/hyperliquid-info-approved-builders.mdx create mode 100644 reference/hyperliquid-info-perp-concise-annotations.mdx create mode 100644 reference/hyperliquid-info-settled-outcome.mdx diff --git a/docs.json b/docs.json index 236b7aed..80e21c5a 100644 --- a/docs.json +++ b/docs.json @@ -2128,6 +2128,9 @@ "reference/hyperliquid-info-spot-pair-deploy-auction-status", "reference/hyperliquid-info-margin-table", "reference/hyperliquid-info-aligned-quote-token-info", + "reference/hyperliquid-info-approved-builders", + "reference/hyperliquid-info-perp-concise-annotations", + "reference/hyperliquid-info-settled-outcome", "reference/hyperliquid-exchange-place-order", "reference/hyperliquid-exchange-cancel-order", "reference/hyperliquid-exchange-cancel-order-by-cloid", @@ -2142,6 +2145,7 @@ "reference/hyperliquid-exchange-spot-perp-transfer", "reference/hyperliquid-exchange-twap-order", "reference/hyperliquid-exchange-twap-cancel", + "reference/hyperliquid-exchange-user-outcome", "reference/hyperliquid-exchange-approve-agent", "reference/hyperliquid-exchange-approve-builder-fee", "reference/hyperliquid-exchange-set-referrer", diff --git a/openapi/hyperliquid_node_api/hypercore_exchange/exchange_user_outcome.json b/openapi/hyperliquid_node_api/hypercore_exchange/exchange_user_outcome.json new file mode 100644 index 00000000..e8161e9c --- /dev/null +++ b/openapi/hyperliquid_node_api/hypercore_exchange/exchange_user_outcome.json @@ -0,0 +1,154 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Hyperliquid Exchange API", + "version": "1.0.0", + "description": "API for trading operations on Hyperliquid exchange requiring authentication. ⚠️ WARNING: These endpoints require EIP-712 signatures for authentication. The example values provided will NOT work without proper cryptographic signing. You must implement EIP-712 signing to use these endpoints successfully." + }, + "servers": [ + { + "url": "https://api.hyperliquid.xyz" + } + ], + "paths": { + "/exchange": { + "post": { + "tags": [ + "hyperliquid exchange" + ], + "summary": "User outcome (split / merge / negate outcome shares)", + "operationId": "userOutcome", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "action": { + "type": "object", + "description": "User outcome action. Provide exactly one of splitOutcome, mergeOutcome, mergeQuestion, or negateOutcome alongside the type.", + "properties": { + "type": { + "type": "string", + "default": "userOutcome", + "enum": [ + "userOutcome" + ], + "description": "Action type" + }, + "splitOutcome": { + "type": "object", + "description": "Split X quote tokens into X Yes and X No shares of an outcome.", + "properties": { + "outcome": { + "type": "integer", + "description": "Outcome identifier." + }, + "amount": { + "type": "string", + "description": "Amount of quote tokens to split." + } + } + } + }, + "required": [ + "type" + ] + }, + "nonce": { + "type": "integer", + "description": "Current timestamp in milliseconds" + }, + "signature": { + "type": "object", + "description": "EIP-712 signature of the action with r, s, v components", + "properties": { + "r": { + "type": "string", + "description": "ECDSA signature r component (hex string)", + "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + }, + "s": { + "type": "string", + "description": "ECDSA signature s component (hex string)", + "example": "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321" + }, + "v": { + "type": "integer", + "description": "ECDSA recovery id (27 or 28)", + "example": 27 + } + }, + "required": [ + "r", + "s", + "v" + ] + }, + "expiresAfter": { + "type": "integer", + "description": "Timestamp in milliseconds after which the request is rejected (optional)" + } + }, + "required": [ + "action", + "nonce", + "signature" + ] + }, + "example": { + "action": { + "type": "userOutcome", + "splitOutcome": { + "outcome": 0, + "amount": "1" + } + }, + "nonce": 1705234567890, + "signature": { + "r": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "s": "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321", + "v": 27 + } + } + } + } + }, + "responses": { + "200": { + "description": "User outcome result", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "Request status" + }, + "response": { + "type": "object", + "properties": { + "type": { + "type": "string", + "default": "default" + } + } + } + }, + "example": { + "status": "ok", + "response": { + "type": "default" + } + } + } + } + } + } + } + } + } + } +} diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_approved_builders.json b/openapi/hyperliquid_node_api/hypercore_info/info_approved_builders.json new file mode 100644 index 00000000..0f63431d --- /dev/null +++ b/openapi/hyperliquid_node_api/hypercore_info/info_approved_builders.json @@ -0,0 +1,69 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Hyperliquid Node API", + "version": "1.0.0", + "description": "This is an API for interacting with Chainstack Hyperliquid node." + }, + "servers": [ + { + "url": "https://hyperliquid-mainnet.core.chainstack.com" + } + ], + "paths": { + "/4f8d8f4040bdacd1577bff8058438274/info": { + "post": { + "tags": [ + "hyperliquid operations" + ], + "summary": "info (approvedBuilders)", + "operationId": "infoApprovedBuilders", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Request type", + "default": "approvedBuilders", + "enum": [ + "approvedBuilders" + ] + }, + "user": { + "type": "string", + "description": "User address in 42-character hexadecimal format.", + "default": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568" + } + }, + "required": [ + "type", + "user" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Array of approved builder addresses", + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of builder addresses the user has approved.", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } +} diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_perp_concise_annotations.json b/openapi/hyperliquid_node_api/hypercore_info/info_perp_concise_annotations.json new file mode 100644 index 00000000..afe64038 --- /dev/null +++ b/openapi/hyperliquid_node_api/hypercore_info/info_perp_concise_annotations.json @@ -0,0 +1,64 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Hyperliquid Node API", + "version": "1.0.0", + "description": "This is an API for interacting with Chainstack Hyperliquid node." + }, + "servers": [ + { + "url": "https://hyperliquid-mainnet.core.chainstack.com" + } + ], + "paths": { + "/4f8d8f4040bdacd1577bff8058438274/info": { + "post": { + "tags": [ + "hyperliquid operations" + ], + "summary": "info (perpConciseAnnotations)", + "operationId": "infoPerpConciseAnnotations", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Request type", + "default": "perpConciseAnnotations", + "enum": [ + "perpConciseAnnotations" + ] + } + }, + "required": [ + "type" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Concise annotations for all perpetual assets", + "content": { + "application/json": { + "schema": { + "type": "array", + "description": "Array of [coin, annotation] tuples. Each annotation has a category and optional displayName and keywords.", + "items": { + "type": "array", + "items": {} + } + } + } + } + } + } + } + } + } +} diff --git a/openapi/hyperliquid_node_api/hypercore_info/info_settled_outcome.json b/openapi/hyperliquid_node_api/hypercore_info/info_settled_outcome.json new file mode 100644 index 00000000..3ee547a7 --- /dev/null +++ b/openapi/hyperliquid_node_api/hypercore_info/info_settled_outcome.json @@ -0,0 +1,115 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Hyperliquid Node API", + "version": "1.0.0", + "description": "This is an API for interacting with Chainstack Hyperliquid node." + }, + "servers": [ + { + "url": "https://hyperliquid-mainnet.core.chainstack.com" + } + ], + "paths": { + "/4f8d8f4040bdacd1577bff8058438274/info": { + "post": { + "tags": [ + "hyperliquid operations" + ], + "summary": "info (settledOutcome)", + "operationId": "infoSettledOutcome", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "Request type", + "default": "settledOutcome", + "enum": [ + "settledOutcome" + ] + }, + "outcome": { + "type": "integer", + "description": "Outcome identifier.", + "default": 0 + } + }, + "required": [ + "type", + "outcome" + ] + } + } + } + }, + "responses": { + "200": { + "description": "Information about a settled outcome, or null if the outcome is not settled", + "content": { + "application/json": { + "schema": { + "type": "object", + "nullable": true, + "properties": { + "spec": { + "type": "object", + "description": "Outcome specification.", + "properties": { + "outcome": { + "type": "integer", + "description": "Outcome identifier." + }, + "name": { + "type": "string", + "description": "Name of the outcome." + }, + "description": { + "type": "string", + "description": "Description of the outcome." + }, + "sideSpecs": { + "type": "array", + "description": "Side specifications for this outcome.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the side." + }, + "token": { + "type": "integer", + "description": "Token identifier for this side." + } + } + } + }, + "quoteToken": { + "type": "string", + "description": "Quote token for this outcome." + } + } + }, + "settleFraction": { + "type": "string", + "description": "Settlement fraction." + }, + "details": { + "type": "string", + "description": "Settlement details." + } + } + } + } + } + } + } + } + } + } +} diff --git a/reference/hyperliquid-exchange-user-outcome.mdx b/reference/hyperliquid-exchange-user-outcome.mdx new file mode 100644 index 00000000..0c6f99ab --- /dev/null +++ b/reference/hyperliquid-exchange-user-outcome.mdx @@ -0,0 +1,132 @@ +--- +title: User outcome | Hyperliquid exchange +openapi: /openapi/hyperliquid_node_api/hypercore_exchange/exchange_user_outcome.json post /exchange +description: "Split or merge outcome-market shares to convert between quote tokens and Yes/No shares on Hyperliquid. On Hyperliquid exchange." +--- + + +You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet. See [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. + + + +This endpoint requires signature authentication. See our comprehensive [Authentication via Signatures guide](/docs/hyperliquid-authentication-guide) for implementation details. + + +The `userOutcome` action manually splits or merges outcome-market shares to convert between quote tokens and Yes/No shares. Outcome markets are binary (Yes/No) prediction markets on Hyperliquid. A single `userOutcome` action carries exactly one of four operations: `splitOutcome`, `mergeOutcome`, `mergeQuestion`, or `negateOutcome`. + + + +**Get your own node endpoint today** + +[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required. + +You can sign up with your GitHub, X, Google, or Microsoft account. + + + +## Parameters + +### Required parameters + +* `action` (object, required) — The user outcome action. Set `type` to `"userOutcome"` and include exactly one of the following operations: + * `splitOutcome` — Split `X` quote tokens into `X` Yes and `X` No shares of an outcome. Fields: `outcome` (number), `amount` (string, e.g. `"123.0"`). + * `mergeOutcome` — Merge `X` Yes and `X` No shares of an outcome into `X` quote tokens. Fields: `outcome` (number), `amount` (string or `null`, where `null` means the maximum available). + * `mergeQuestion` — Merge `X` Yes shares from each outcome associated to the same question into `X` quote tokens. Fields: `question` (number), `amount` (string or `null`, where `null` means the maximum available). + * `negateOutcome` — Convert `X` No shares from an outcome associated with a question into `X` Yes shares of every other outcome associated with the question. Fields: `question` (number), `outcome` (number), `amount` (string). +* `nonce` (number, required) — Current timestamp in milliseconds (must be recent). +* `signature` (object, required) — EIP-712 signature of the action. + +### Optional parameters + +* `expiresAfter` (number, optional) — Timestamp in milliseconds after which the request is rejected. + +## Returns + +Returns an object with the action status: + +* `status` — `"ok"` if the request was processed. +* `response` — Contains operation details: + * `type` — `"default"`. + +## Example request + + + +```shell cURL +# Split outcome: split 1 quote token into 1 Yes and 1 No share of outcome 0 +curl -X POST https://api.hyperliquid.xyz/exchange \ + -H "Content-Type: application/json" \ + -d '{ + "action": { + "type": "userOutcome", + "splitOutcome": {"outcome": 0, "amount": "1"} + }, + "nonce": 1234567890123, + "signature": {...} + }' +``` + +```python Python (hyperliquid-python-sdk) +# Note: the official hyperliquid-python-sdk does not expose a userOutcome +# helper yet, so build and post the signed action directly. +from hyperliquid.exchange import Exchange +from hyperliquid.utils import constants +from hyperliquid.utils.signing import sign_l1_action, get_timestamp_ms +import eth_account + +# Public Hyperliquid mainnet endpoint +wallet = eth_account.Account.from_key("0x...") # your private key +exchange = Exchange(wallet, constants.MAINNET_API_URL) + +timestamp = get_timestamp_ms() +action = { + "type": "userOutcome", + "splitOutcome": {"outcome": 0, "amount": "1"}, +} +signature = sign_l1_action( + wallet, + action, + None, # vault_address + timestamp, + None, # expires_after + exchange.base_url == constants.MAINNET_API_URL, +) +result = exchange._post_action(action, signature, timestamp) +print(result) +``` + +```typescript TypeScript (@nktkas/hyperliquid) +import { ExchangeClient, HttpTransport } from "@nktkas/hyperliquid"; +import { privateKeyToAccount } from "viem/accounts"; + +// Public Hyperliquid mainnet endpoint (default transport) +const wallet = privateKeyToAccount("0x..."); // viem or ethers account +const transport = new HttpTransport(); +const exchange = new ExchangeClient({ transport, wallet }); + +// Split 1 quote token into 1 Yes and 1 No share of outcome 0 +const result = await exchange.userOutcome({ + splitOutcome: { outcome: 0, amount: "1" }, +}); + +console.log(result); +``` + + + +## Response example + +```json +{ + "status": "ok", + "response": { + "type": "default" + } +} +``` + +## Use cases + +* **Provide outcome liquidity** — Split quote tokens into Yes and No shares to make markets on both sides +* **Redeem shares** — Merge matched Yes and No shares back into quote tokens +* **Manage positions across a question** — Merge or negate shares across the outcomes of a single question diff --git a/reference/hyperliquid-info-approved-builders.mdx b/reference/hyperliquid-info-approved-builders.mdx new file mode 100644 index 00000000..78d02fbc --- /dev/null +++ b/reference/hyperliquid-info-approved-builders.mdx @@ -0,0 +1,90 @@ +--- +title: approvedBuilders | Hyperliquid info +openapi: /openapi/hyperliquid_node_api/hypercore_info/info_approved_builders.json post /4f8d8f4040bdacd1577bff8058438274/info +description: "The info endpoint with type: \"approvedBuilders\" lists the builder addresses a user has approved to attach builder fees to their orders." +--- + + +This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. + + +The `info` endpoint with `type: "approvedBuilders"` returns the list of builder addresses a user has approved. When a user approves a builder, that builder can attach a builder fee to the user's orders. Use this method to check which builders a given address has authorized. + + + +**Get your own node endpoint today** + +[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required. + +You can sign up with your GitHub, X, Google, or Microsoft account. + + + +## Parameters + +### Request body + +* `type` (string, required) — The request type. Must be `"approvedBuilders"`. +* `user` (string, required) — Address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000. + +## Response + +Returns an array of builder addresses that the user has approved. The array is empty if the user has not approved any builders. + +## Example request + + + +```shell Shell +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{"type": "approvedBuilders", "user": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568"}' \ + https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info +``` + +```python Python (hyperliquid-python-sdk) +from hyperliquid.info import Info + +# skip_ws=True avoids opening a WebSocket connection for this REST call +info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True) + +# The SDK has no dedicated approvedBuilders helper, so post the request directly. +approved_builders = info.post("/info", { + "type": "approvedBuilders", + "user": "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568", +}) +print(approved_builders) +``` + +```typescript TypeScript (@nktkas/hyperliquid) +import { HttpTransport, InfoClient } from "@nktkas/hyperliquid"; + +// apiUrl points the transport at a custom server (your Chainstack endpoint) +const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" }); +const info = new InfoClient({ transport }); + +const approvedBuilders = await info.approvedBuilders({ + user: "0x1442ad477ded1b0028b57621aa7b6f7eadb8f568", +}); +console.log(approvedBuilders); +``` + + + + +**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production. + + +## Example response + +```json +["0x1cc34f6af34653c515b47a83e1de70ba9b0cda1f"] +``` + +## Use cases + +The `info` endpoint with `type: "approvedBuilders"` is useful for: + +* Checking which builders a user has authorized before submitting orders with builder fees +* Building wallet and frontend integrations that surface a user's approved builders +* Auditing builder-fee relationships for an address diff --git a/reference/hyperliquid-info-perp-concise-annotations.mdx b/reference/hyperliquid-info-perp-concise-annotations.mdx new file mode 100644 index 00000000..af688eea --- /dev/null +++ b/reference/hyperliquid-info-perp-concise-annotations.mdx @@ -0,0 +1,92 @@ +--- +title: perpConciseAnnotations | Hyperliquid info +openapi: /openapi/hyperliquid_node_api/hypercore_info/info_perp_concise_annotations.json post /4f8d8f4040bdacd1577bff8058438274/info +description: "The info endpoint with type: \"perpConciseAnnotations\" returns concise annotations (category, display name, keywords) for all perpetual assets." +--- + + +This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. + + +The `info` endpoint with `type: "perpConciseAnnotations"` returns concise annotations for all perpetual assets. Each annotation classifies a perpetual into a category and can carry a frontend display name and search keywords. Use this method to categorize and label perpetual markets in dashboards and search interfaces. + + + +**Get your own node endpoint today** + +[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required. + +You can sign up with your GitHub, X, Google, or Microsoft account. + + + +## Parameters + +### Request body + +* `type` (string, required) — The request type. Must be `"perpConciseAnnotations"`. + +## Response + +Returns an array of `[coin, annotation]` tuples. Each annotation object contains: + +* `category` (string) — The classification category assigned to the perpetual. +* `displayName` (string, optional) — A display name for frontends to use instead of the L1 name. +* `keywords` (array of strings, optional) — Keywords used as hints to match against searches. + +## Example request + + + +```shell Shell +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{"type": "perpConciseAnnotations"}' \ + https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info +``` + +```python Python (hyperliquid-python-sdk) +from hyperliquid.info import Info + +# skip_ws=True avoids opening a WebSocket connection for this REST call +info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True) + +# The SDK has no dedicated perpConciseAnnotations helper, so post the request directly. +perp_concise_annotations = info.post("/info", {"type": "perpConciseAnnotations"}) +print(perp_concise_annotations) +``` + +```typescript TypeScript (@nktkas/hyperliquid) +import { HttpTransport, InfoClient } from "@nktkas/hyperliquid"; + +// apiUrl points the transport at a custom server (your Chainstack endpoint) +const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" }); +const info = new InfoClient({ transport }); + +const perpConciseAnnotations = await info.perpConciseAnnotations(); +console.log(perpConciseAnnotations); +``` + + + + +**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production. + + +## Example response + +```json +[ + ["flx:BTC", { "category": "crypto" }], + ["flx:COIN", { "category": "stocks" }], + ["flx:GOLD", { "category": "commodities" }] +] +``` + +## Use cases + +The `info` endpoint with `type: "perpConciseAnnotations"` is useful for: + +* Grouping perpetual markets by category in dashboards and market screens +* Showing frontend-friendly display names instead of raw L1 names +* Powering search and filtering with per-asset keywords diff --git a/reference/hyperliquid-info-settled-outcome.mdx b/reference/hyperliquid-info-settled-outcome.mdx new file mode 100644 index 00000000..69135d3d --- /dev/null +++ b/reference/hyperliquid-info-settled-outcome.mdx @@ -0,0 +1,107 @@ +--- +title: settledOutcome | Hyperliquid info +openapi: /openapi/hyperliquid_node_api/hypercore_info/info_settled_outcome.json post /4f8d8f4040bdacd1577bff8058438274/info +description: "The info endpoint with type: \"settledOutcome\" retrieves the specification and settlement details for an outcome market by its outcome identifier." +--- + + +This method is available on Chainstack. Not all Hyperliquid methods are available on Chainstack, as the open-source node implementation does not support them yet — see [Hyperliquid methods](/docs/hyperliquid-methods) for the full availability breakdown. + + +The `info` endpoint with `type: "settledOutcome"` retrieves the specification and settlement details for an outcome market, identified by its `outcome` index. Outcome markets are binary (Yes/No) prediction markets on Hyperliquid. Use this method to read an outcome's definition and how it settled. + + + +**Get your own node endpoint today** + +[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required. + +You can sign up with your GitHub, X, Google, or Microsoft account. + + + +## Parameters + +### Request body + +* `type` (string, required) — The request type. Must be `"settledOutcome"`. +* `outcome` (integer, required) — The outcome identifier. + +## Response + +Returns a settled outcome object, or `null` if the outcome is not settled. + +* `spec` (object) — The outcome specification: + * `outcome` (integer) — The outcome identifier. + * `name` (string) — The name of the outcome. + * `description` (string) — The description of the outcome. + * `sideSpecs` (array) — The side specifications, each with a `name` and an optional `token`. + * `quoteToken` (string) — The quote token for this outcome. +* `settleFraction` (string) — The settlement fraction. +* `details` (string) — The settlement details. + +## Example request + + + +```shell Shell +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{"type": "settledOutcome", "outcome": 0}' \ + https://hyperliquid-mainnet.core.chainstack.com/4f8d8f4040bdacd1577bff8058438274/info +``` + +```python Python (hyperliquid-python-sdk) +from hyperliquid.info import Info + +# skip_ws=True avoids opening a WebSocket connection for this REST call +info = Info("YOUR_CHAINSTACK_ENDPOINT", skip_ws=True) + +# The SDK has no dedicated settledOutcome helper, so post the request directly. +settled_outcome = info.post("/info", {"type": "settledOutcome", "outcome": 0}) +print(settled_outcome) +``` + +```typescript TypeScript (@nktkas/hyperliquid) +import { HttpTransport, InfoClient } from "@nktkas/hyperliquid"; + +// apiUrl points the transport at a custom server (your Chainstack endpoint) +const transport = new HttpTransport({ apiUrl: "YOUR_CHAINSTACK_ENDPOINT" }); +const info = new InfoClient({ transport }); + +const settledOutcome = await info.settledOutcome({ outcome: 0 }); +console.log(settledOutcome); +``` + + + + +**Use your own endpoint in your code.** The code examples use a placeholder Chainstack endpoint (YOUR_CHAINSTACK_ENDPOINT) — replace it with your own Hyperliquid node endpoint from the [Chainstack console](https://console.chainstack.com/). The curl above uses a shared public endpoint for quick checks only; do not use it in production. + + +## Example response + +```json +{ + "spec": { + "outcome": 0, + "name": "Recurring", + "description": "class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d", + "sideSpecs": [ + { "name": "Yes" }, + { "name": "No" } + ], + "quoteToken": "USDH" + }, + "settleFraction": "0.0", + "details": "price:78212.4" +} +``` + +## Use cases + +The `info` endpoint with `type: "settledOutcome"` is useful for: + +* Reading the definition of an outcome market (underlying, target price, expiry) +* Checking how an outcome settled and its settlement fraction +* Building prediction-market dashboards and settlement reports