Concept Overview

This section introduces the core business concepts you need to understand before integrating the Outcomes API, including xp (the base asset), events, markets, outcomes, prices, Split / Merge, the mirror order book, the order book, positions, settlement, and the key IDs.

Once you understand these concepts, you will be able to reason more clearly about:

• How to find a tradable market from an event
• How to choose the YES / NO outcome
• Why placing orders, cancelling orders, and querying market data generally use assetId
• The relationship between Split / Merge and the mirror order book
• The difference between a Binary Market and a NegRisk Market

1. Prediction Market

A prediction market is a market for trading on the outcomes of future events.

Each market usually corresponds to a clear question, for example:

Will Germany win a given match?

Users trade the different outcomes of that question based on their own judgment. The most common outcomes are YES and NO.

Example:

In simple terms:

2. Core Object Model

The core object relationships in the Outcomes API are as follows:

• Event
  • Market
  • YES outcome
  • NO outcome

In simple terms:

When integrating, you typically follow this path:

1. Query an Event
2. Get the Markets under that Event
3. Choose the YES or NO outcome under a Market
4. Trade using the assetId of that outcome

3. Event and Market

An Event is the upper-level organizational unit of the prediction market, representing a real-world event.

Example:

An Event can contain multiple Markets:

What users actually trade is not the Event itself, but the YES or NO outcome under a specific Market.

4. Outcome

An Outcome is the tradable object under a Market.

In a binary market, each Market usually has two outcomes:

Each outcome has its own assetId. When placing an order, what you ultimately use is the assetId of the target outcome.

Example:

• marketId: 100001
• question: Will Germany win?
• yesOutcome: assetId = 100049000, price = 0.65
• noOutcome: assetId = 100049001, price = 0.35

To buy YES, use yesOutcome.assetId. To buy NO, use noOutcome.assetId.

5. Price and Probability

A price in the prediction market is a decimal between 0 and 1. It can be understood as the market's real-time estimate of the probability that an outcome happens.

For example:

Why price ≈ probability: a winning outcome settles at 1 xp and a losing one at 0 xp, so the expected value of holding an outcome = 1 xp × the probability that it occurs. In an efficient market the price converges to this expected value, so the price can be read as the market's estimate of that outcome's probability.

The price is formed by market trading and does not represent the final result. The final result is determined by market settlement.

6. Complementary Relationship of YES / NO

YES and NO are the two sides of the same Binary Market. When one outcome happens, the other does not.

Ideally, the sum of their prices is close to 1.

This relationship can be summarized as:

YES + NO ≈ 1

You do not need to handle the YES / NO price conversion manually. When placing an order, simply choose the target outcome and use its assetId.

7. Split / Merge Mechanism

Split / Merge is the underlying mechanism behind the YES / NO complementary relationship.

For a Binary Market, YES and NO can be seen as a pair of conditional outcomes. The system can convert between xp (the base asset of this prediction market) and the YES / NO outcomes via Split and Merge.

7.1 Split

Split splits one unit of xp into equal amounts of YES and NO outcomes.

1 xp → 1 YES + 1 NO

This can be understood as: the user splits one complete market entitlement into the market's two complementary outcomes.

7.2 Merge

Merge is the inverse of Split. The user can merge equal amounts of YES and NO outcomes back into xp.

1 YES + 1 NO → 1 xp

Merge is only possible when the YES and NO amounts are equal.

This mechanism guarantees the complementary relationship of YES and NO:

YES + NO ≈ 1

In other words, within the same Binary Market, YES and NO are not fully independent assets, but the two sides of the same set of conditional outcomes.

8. Mirror Order Book

Based on the YES / NO complementary relationship, the system can use a mirror order book to handle YES and NO trading in a unified way.

For the same Binary Market:

The reason is:

YES price + NO price ≈ 1

Therefore, the system can support both YES and NO trading on a single unified order book at the underlying level.

You do not need to split or convert mirror orders manually. When placing an order, simply choose the outcome the user wants to trade and use its assetId. The system handles the YES / NO equivalence at the order book level.

9. Order Book

Outcomes uses a central limit order book (CLOB).

CLOB stands for Central Limit Order Book. Market prices are not set directly by the platform, but are formed by users' orders and trades.

The order book has two sides:

Example:

When the bid and ask prices match, the orders are matched and traded.

10. Maker and Taker

When an order is filled, the user may be a Maker or a Taker.

Example:

The current best ask is 0.66.

Order matching generally follows:

11. Position

Open orders that are not yet filled occupy the available balance. After an order is filled, the user obtains a position in the corresponding outcome.

Example:

Positions change with the following operations:

12. Closing a Position

A user does not have to wait for market settlement to exit a position. If the market is still tradable, the user can close a position by selling an existing outcome.

Example:

Closing a position is essentially exiting an existing position via a reverse trade.

13. Settlement

Once an event's result is determined, the Market enters the settlement process.

After settlement:

Example:

Market: Will Germany win?

If Germany ultimately wins:

If Germany does not win:

After the market settles, open orders are closed, and the user's positions and balances are updated based on the final result.

14. Binary Market

A Binary Market is the most common market structure, representing a yes / no question.

Example:

A Binary Market usually has only two outcomes:

• YES
• NO

You only need to choose the assetId of YES or NO to trade.

15. NegRisk Market

A NegRisk Market is used for scenarios with multiple mutually exclusive outcomes. An Event can contain multiple related Markets, but usually only one outcome ultimately wins.

Example:

Event: Who will win the championship?

If Germany ultimately wins the title:

For developers, a NegRisk Market does not change the basic trading method. You still choose the YES or NO outcome under a specific Market and trade with its assetId.

16. Market Status

A Market goes through different states during its lifecycle.

Common states:

Check the Market status before placing an order. If the Market is not active, the order may be rejected.

17. Key IDs

When integrating the API, the various IDs are the most easily confused.

Keep these in mind:

The most important rule is:

Order placement, cancellation, market data, and order book operations generally use assetId.

If the API returns assetId as null, the outcome is temporarily not tradable. Wait until assetId returns a valid value before performing trading operations.

18. Summary

You can understand the core model of Outcomes with the following chain:

Event → Market → Outcome → assetId → Order / Position

The mapping is:

For API consumers, the most critical points are:

Quick Start

This guide walks you through the minimal integration flow of the Outcomes API and submitting your first order.

Prerequisites

Before you start, make sure you have the following:

Step 1: Set Up an API Key

Before signing any request, you must first create an API Key via the OKX API management page or the App. After creation, you receive the following 3 credentials, which must be kept safe:

APIKey and SecretKey are randomly generated and provided by the platform; the Passphrase is set by you to strengthen the security of API access.

APIKey Permissions

For the prediction market, select all of the following permissions:

Creation Steps

Step 1: Tap "View" on the App prediction market page	Step 2: Tap the top-right menu

Step 3: Open the API Key generation page	Step 4: Generate the API Key

Step 5: View details after generation	Step 6: Details page

All REST endpoints require OKX API credentials. Construct the client with with_credentials (see Step 5).

Step 2: Set Up an Agent

Keep your main key safe — create an Agent key that signs trades on your behalf.

1. Generate a new Ethereum key pair (any key-generation tool). Save the Agent private key and the Agent address.
2. Authorize the Agent in the OKX App — Agent authorization must be done via the App, not the API.

App Agent Authorization Steps

Step 1: Enter the Agent address to authorize	Step 2: Authorization succeeded

After authorization, all subsequent write API calls use the Agent private key; read API calls do not require the private key.

Step 3: Add the SDK

Installation

Add this SDK and the Tokio runtime to your Cargo.toml:

Cargo.toml dependencies

[dependencies]
okx-outcomes-sdk = { git = "https://github.com/okx/outcomes-sdk.git", features = ["signing", "websocket"] }
tokio = { version = "1", features = ["full"] }

That is the complete dependency list. tokio-tungstenite, k256, sha3, futures-util, etc. are pulled in transitively via the SDK's features. Do not add these dependencies yourself, or you may end up with versions inconsistent with what the SDK was built against.

Feature Flags

Step 4: Configure Environment Variables

We recommend storing credentials in environment variables:

Environment variable configuration

export PREDICTIONS_API_KEY="your-api-key"
export PREDICTIONS_API_SECRET="your-secret-key"
export PREDICTIONS_API_PASSPHRASE="your-passphrase"
export PREDICTIONS_AGENT_PRIVATE_KEY="0x..."

Step 5: Initialize the Client

Initialize the SDK Client with the API Key, Secret Key, and Passphrase:

Client initialization example

use okx_outcomes_sdk::{ApiCredentials, OutcomesSdkClient};

let creds = ApiCredentials {
    api_key:    std::env::var("PREDICTIONS_API_KEY")?,
    secret_key: std::env::var("PREDICTIONS_API_SECRET")?,
    passphrase: std::env::var("PREDICTIONS_API_PASSPHRASE")?,
};

let client = OutcomesSdkClient::with_credentials(creds);

The SDK signs REST requests locally and automatically writes the required authentication headers.

Step 6: Query Tradable Markets

get_events returns a paginated list of events. All filter parameters are optional:

Query events example

let page = client
    .get_events(
        Some("active"),      // status: "active" | "resolved"
        None,                // tag
        None,                // league_id
        Some("volume_24h"),  // sort: "volume" | "volume_24h" | "ending_soon" | "newest"
        None,                // cursor (from the previous page)
        Some(20),            // page_size (max 50)
    )
    .await?;

for event in &page.events {
    println!("{} - {} markets ({} points volume)",
        event.event_title, event.total_markets_count, event.volume);
}

// Pagination: pass `page.pagination.next_cursor` back as `cursor` on the next call.

Other read methods

Find a market with status: "active" and record:

• yesOutcome.assetId (e.g. "100049000") — used for placing orders
• marketId (e.g. "1") — used for position queries

Step 7: Place a Limit Order

Buy 10 YES tokens at 0.55 xp on market 100049000. This requires two layers of authentication: the API Key headers + the SDK-signed request body.

Full limit order example

use okx_outcomes_sdk::{ApiCredentials, OutcomesSdkClient};
use okx_outcomes_sdk::models::order::{
    LimitOrderType, OrderItem, PlaceOrderAction, PlaceOrderRequest, SigningOrderSide, SizeType,
};
use okx_outcomes_sdk::signing::{
    action_place_order, generate_client_order_id_default, now_millis, parse_private_key,
    sign_to_wrapper, LimitTif, OrderRequest, OrderType,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let creds = ApiCredentials {
        api_key:    std::env::var("PREDICTIONS_API_KEY")?,
        secret_key: std::env::var("PREDICTIONS_API_SECRET")?,
        passphrase: std::env::var("PREDICTIONS_API_PASSPHRASE")?,
    };
    let client = OutcomesSdkClient::with_credentials(creds);

    // 1. Load the on-chain signing key (hex, with or without 0x prefix).
    let key = parse_private_key(&std::env::var("PREDICTIONS_AGENT_PRIVATE_KEY")?)?;

    // 2. Build the typed order. `asset_id` is the outcome asset ID from Step 6.
    let order_request = OrderRequest {
        asset_id:         "100049000".into(),
        side:             SigningOrderSide::Buy,
        market_type:      "prediction".into(),
        client_order_id:  Some(generate_client_order_id_default()?),
        price:            "0.55".into(),
        reduce_only:      false,
        size:             "10".into(),
        size_type:        SizeType::Base, // omitted on the wire (default)
        order_type:       OrderType::Limit(LimitOrderType { tif: LimitTif::Gtc }),
    };

    // 3. Derive the wire-format OrderItem from the same OrderRequest so the
    //    JSON body cannot drift from the signed msgpack bytes.
    let order_item = OrderItem::try_from(&order_request)?;
    let action = action_place_order(vec![order_request]);

    // 4. Sign and assemble the SignatureWrapper expected by the wire format.
    let nonce = now_millis();
    let signature = sign_to_wrapper(&action, nonce, None, &key)?;

    // 5. Submit.
    let req = PlaceOrderRequest {
        action: PlaceOrderAction {
            action_type: "placeOrder".into(),
            grouping:    "na".into(),
            orders:      vec![order_item],
        },
        nonce: nonce as i64,
        signature,
    };
    let resp = client.place_order(&req).await?;
    println!("tx_hash: {}", resp.tx_hash);
    Ok(())
}

Place order response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"
  }
}

Step 8: View Orders

When status = Some("open"), list_orders returns all non-terminal orders on the account, page by page. Pass the next_cursor from the previous response back via the cursor parameter until has_next is false:

Query order list example

use okx_outcomes_sdk::models::order::OrderRecord;

let mut cursor: Option<String> = None;
let mut all_open: Vec<OrderRecord> = Vec::new();

loop {
    let page = client
        .list_orders(
            None,             // market_id: None = all markets, Some(123) = a specific market
            Some("open"),     // "open" = PENDING_PLACE / ACTIVE / PENDING_CANCEL; "closed" = FILLED / PARTIALLY_FILLED / CANCELLED / EXPIRED / FAILED
            cursor.as_deref(),
            Some(50),         // max items per page
        )
        .await?;
    all_open.extend(page.list);
    if !page.has_next {
        break;
    }
    cursor = page.next_cursor;
}

println!("{} open orders", all_open.len());
for o in &all_open {
    println!(
        "#{} [{}] {} {}/{} @ {}  market={} asset={} cloid={:?}",
        o.id, o.status, o.side, o.filled_size, o.size, o.price,
        o.market_id, o.asset_id, o.client_order_id,
    );
}

Each OrderRecord exposes the order parameters (side, size, price, order_type, size_type, expiration), order metadata (market_id, asset_id, client_order_id, tx_hash), and the current lifecycle status (status, filled_size, filled_amount).

Tips:

• market_id is an i64 in the SDK, not a string; pass it as Some(123_456_789). The marketId returned by the REST API is a string, which the SDK converts internally.
• client_order_id (the cloid passed when placing the order) can be passed to cancel_order to cancel by client ID instead of server ID.
• Record id (e.g. 578840) — you need it when cancelling.

Step 9: Cancel an Order

The cancel flow is the same as place_order, also in three steps: build a typed CancelRequest, derive the corresponding wire-format CancelItem from it, sign the action, and finally submit the wire request. You can locate the target order by the order's server oid (the OrderRecord.id value) or by cloid (the client_order_id passed when placing the order).

The snippet below assumes client and key are already constructed as in the order placement section.

Cancel order example

use okx_outcomes_sdk::models::order::{CancelItem, CancelOrderAction, CancelOrderRequest};
use okx_outcomes_sdk::signing::{
    action_cancel, now_millis, sign_to_wrapper, CancelRequest, CancelTarget,
};

// 1. CancelTarget must be one of:
//    Oid   = server-assigned order ID (OrderRecord.id), a decimal string.
//    Cloid = client-assigned order ID, a hex string with the 0x prefix.
let cancel_request = CancelRequest {
    asset_id:    "100049000".into(),
    market_type: "prediction".into(),
    target:      CancelTarget::Oid("578840".into()),
    // target:   CancelTarget::Cloid("0xabc...".into()),
};

// 2. Derive the wire item from the same request so the signed bytes do not diverge from the JSON body.
let cancel_item = CancelItem::from(&cancel_request);
let action      = action_cancel(vec![cancel_request]);

// 3. Sign and submit.
let nonce     = now_millis();
let signature = sign_to_wrapper(&action, nonce, None, &key)?;

let resp = client
    .cancel_order(&CancelOrderRequest {
        action: CancelOrderAction {
            action_type: "cancel".into(),
            cancels:     vec![cancel_item],
        },
        nonce:     nonce as i64,
        signature,
    })
    .await?;
println!("cancel tx_hash: {}", resp.tx_hash);

Step 10: View Balance, Orders, and Positions

Query balance and positions example

// Balance
let entries = client.get_balance().await?; // Vec<BalanceEntry>
for entry in &entries {
    println!("[{}] available={} total={}", entry.odds_type, entry.available, entry.balance);
}

// Positions
let positions = client.get_positions(
    Some("open"), // "open" | "closed" | "settled"
    None,         // market_id
    None,         // cursor
    Some(50),     // limit
).await?;
println!("{} positions", positions.list.len());

For order queries, see Step 8. get_positions is also paginated via cursor + limit.

Full Flow Recap

The minimal integration flow is:

1. Create an API Key in the App / web
2. Authorize an Agent in the App
3. Install the SDK
4. Configure environment variables
5. Initialize the Client
6. Query Events and Markets
7. Get the assetId of the YES / NO outcome and submit an order with it
8. Query order status
9. Cancel the order if needed
10. Query positions and balance after the fill

Notes

Price Tick Rules

FAQ

REST API

The REST API lets you query events, markets, tickers, order books, orders, trades, positions, and balances, and submit write operations such as place order, cancel order, Split, Merge, and Redeem. Developers can complete the full trading loop through the REST API: discover markets, obtain the assetId, submit orders, query order status, manage positions, and handle settlement-related operations. The base URL for all endpoints is https://www.okx.com.

1. Events & Markets API

Data Structures

OutcomeResp — Outcome option

MarketResp — Market object

EventResp — Event object

PaginationResp — Cursor pagination

1.1 Get events

Get the prediction market event list, with multi-dimensional filtering and sorting by status, etc.

HTTP Request

GET /api/v5/predictions/events

Request Parameters (Query)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "events": [
      {
        "id": "100",
        "eventId": "100",
        "negRisk": false,
        "status": "active",
        "eventTitle": "Will BTC exceed $100k by end of 2026?",
        "description": "This event tracks whether Bitcoin will cross $100,000.",
        "eventIcon": "https://cdn.example.com/events/100.png",
        "volume": "1250000.00",
        "startTime": 1700000000000,
        "endTime": 1798761600000,
        "createdAt": 1710000000000,
        "totalMarketsCount": 1,
        "finalOutcomesMarketId": null,
        "markets": [
          {
            "id": "1",
            "marketId": "1",
            "oddsType": "points",
            "negRisk": false,
            "status": "active",
            "settleStage": 0,
            "question": "Will BTC exceed $100k by end of 2026?",
            "shortQuestion": "BTC > $100k?",
            "description": "Resolves YES if BTC price exceeds $100,000 before Jan 1, 2027.",
            "marketIcon": null,
            "bestBid": "0.64",
            "bestAsk": "0.66",
            "lastTradePrice": "0.65",
            "volume": "1250000.00",
            "probability": "0.65",
            "resolutionSources": ["https://coinmarketcap.com"],
            "yesOutcome": {
              "tokenId": "0xabc...001",
              "assetId": "1",
              "name": "Yes",
              "price": "0.65",
              "finalResult": null
            },
            "noOutcome": {
              "tokenId": "0xabc...002",
              "assetId": "2",
              "name": "No",
              "price": "0.35",
              "finalResult": null
            }
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "eyJpZCI6MTAwfQ",
      "hasMore": true,
      "pageSize": 10
    }
  }
}

1.2 Get a single event

Get the full information for a specified event. The markets field returns all markets under the event (not truncated).

HTTP Request

GET /api/v5/predictions/events/{eventId}

Path Parameters

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "id": "100",
    "eventId": "100",
    "negRisk": false,
    "status": "active",
    "eventTitle": "NBA Finals 2026 - Lakers vs Celtics",
    "description": "Who will win the 2026 NBA Championship?",
    "eventIcon": "https://cdn.example.com/events/100.png",
    "volume": "3200000.00",
    "startTime": 1748000000000,
    "endTime": 1750000000000,
    "createdAt": 1710000000000,
    "totalMarketsCount": 3,
    "finalOutcomesMarketId": null,
    "markets": [ ]
  }
}

Returns the full EventResp, with markets containing all markets under the event.

1.3 Get markets

Get all markets under a specified event, without pagination.

HTTP Request

GET /api/v5/predictions/events/{eventId}/markets

Path Parameters

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "markets": [
      {
        "id": "1",
        "marketId": "1",
        "negRisk": false,
        "status": "active",
        "settleStage": 0,
        "question": "Will BTC exceed $100k by end of 2026?",
        "shortQuestion": "BTC > $100k?",
        "description": "Resolves YES if BTC price exceeds $100,000 before Jan 1, 2027.",
        "marketIcon": null,
        "bestBid": "0.64",
        "bestAsk": "0.66",
        "lastTradePrice": "0.65",
        "volume": "1250000.00",
        "probability": "0.65",
        "resolutionSources": ["https://coinmarketcap.com"],
        "yesOutcome": {
          "tokenId": "0xabc...001",
          "assetId": "1",
          "name": "Yes",
          "price": "0.65",
          "finalResult": null
        },
        "noOutcome": {
          "tokenId": "0xabc...002",
          "assetId": "2",
          "name": "No",
          "price": "0.35",
          "finalResult": null
        }
      }
    ]
  }
}

1.4 Get a single market

Get the detailed information for a specified market.

HTTP Request

GET /api/v5/predictions/markets/{marketId}

Path Parameters

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "id": "1",
    "marketId": "1",
    "negRisk": false,
    "status": "resolved",
    "settleStage": 5,
    "question": "Will BTC exceed $100k by end of 2026?",
    "shortQuestion": "BTC > $100k?",
    "description": "Resolves YES if BTC price exceeds $100,000 before Jan 1, 2027.",
    "marketIcon": null,
    "bestBid": null,
    "bestAsk": null,
    "lastTradePrice": "0.98",
    "volume": "1250000.00",
    "probability": null,
    "resolutionSources": ["https://coinmarketcap.com"],
    "yesOutcome": {
      "tokenId": "0xabc...001",
      "assetId": "1",
      "name": "Yes",
      "price": "1.00",
      "finalResult": true
    },
    "noOutcome": {
      "tokenId": "0xabc...002",
      "assetId": "2",
      "name": "No",
      "price": "0.00",
      "finalResult": false
    }
  }
}

Returns the full MarketResp.

1.5 Search events

Full-text search of events by keyword. Returns the matching event list, with cursor pagination.

HTTP Request

GET /api/v5/predictions/events/search

Request Parameters (Query)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "events": [
      {
        "id": "100",
        "eventId": "100",
        "negRisk": false,
        "status": "active",
        "eventTitle": "Will BTC exceed $100k by end of 2026?",
        "description": "This event tracks whether Bitcoin will cross $100,000.",
        "eventIcon": "https://cdn.example.com/events/100.png",
        "volume": "1250000.00",
        "startTime": 1700000000000,
        "endTime": 1798761600000,
        "createdAt": 1710000000000,
        "totalMarketsCount": 1,
        "finalOutcomesMarketId": null,
        "markets": [
          {
            "id": "1",
            "marketId": "1",
            "oddsType": "points",
            "negRisk": false,
            "status": "active",
            "settleStage": 0,
            "question": "Will BTC exceed $100k by end of 2026?",
            "shortQuestion": "BTC > $100k?",
            "description": "Resolves YES if BTC price exceeds $100,000 before Jan 1, 2027.",
            "marketIcon": null,
            "bestBid": "0.64",
            "bestAsk": "0.66",
            "lastTradePrice": "0.65",
            "volume": "1250000.00",
            "probability": "0.65",
            "resolutionSources": ["https://coinmarketcap.com"],
            "yesOutcome": {
              "tokenId": "0xabc...001",
              "assetId": "1",
              "name": "Yes",
              "price": "0.65",
              "finalResult": null
            },
            "noOutcome": {
              "tokenId": "0xabc...002",
              "assetId": "2",
              "name": "No",
              "price": "0.35",
              "finalResult": null
            }
          }
        ]
      }
    ],
    "pagination": {
      "nextCursor": "eyJpZCI6MTAwfQ",
      "hasMore": true,
      "pageSize": 10
    }
  }
}

2. Price API

2.1 Get ticker

Get the latest ticker for a single prediction market instrument, used to display the last trade price in the order book.

Request Parameters

HTTP Request

GET /api/v5/market/ticker?instId={yesAssetId}

Response Parameters

Response example

{
  "code": "0",
  "msg": "",
  "data": [{
    "instType": "SPOT",
    "instId": "{yesAssetId}",
    "last": "0.65",
    "lastSz": "100",
    "askPx": "0.66",
    "askSz": "500",
    "bidPx": "0.64",
    "bidSz": "300",
    "open24h": "0.60",
    "high24h": "0.70",
    "low24h": "0.55",
    "vol24h": "10000",
    "volCcy24h": "6500",
    "sodUtc0": "0.62",
    "sodUtc8": "0.61",
    "ts": "1711900800000"
  }]
}

2.2 Get candlesticks

Query historical candlestick data for a prediction market instrument. Candlesticks are grouped and returned by the requested bar size; at most 1,440 candles are available per bar size.

Request Parameters

HTTP Request

GET /api/v5/market/candles?instId={yesAssetId}&bar=1m&limit=100

Response Data

(data is a 2D array; each record's field order is as follows)

Response example

{
  "code": "0",
  "msg": "",
  "data": [
    ["1711900800000", "0.65", "0.67", "0.63", "0.66", "2000", "1300", "1300", "1"],
    ["1711900740000", "0.63", "0.66", "0.62", "0.65", "1800", "1170", "1170", "1"]
  ]
}

2.3 Get order book

Query a bid/ask depth snapshot for a prediction market instrument.

Request Parameters

HTTP Request

GET /api/v5/market/pm-books?instId={yesAssetId}&sz=400

Response Parameters

Response example

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "asks": [
        ["67364.1","0.45478048","5"]
      ],
      "bids": [
        ["67364","1.72315936", "17"]
      ],
      "ts": "1774943488756",
      "seqId": 74487243135
    }
  ]
}

Each record in the asks / bids arrays has the format: [price, size, order count]

3. Orders API

3.1 Place order

Submit a signed order request. The developer constructs the calldata and signs it with their own wallet private key (ECDSA); after the server validates it, the order is written to the database and forwarded directly to TradeZone (it does not go through the AA Wallet).

HTTP Request

POST /api/v5/predictions/orders

Request Body

Request example

{
  "action": {
    "type": "placeOrder",
    "grouping": "na",
    "orders": [{
      "assetId": "1",
      "marketType": "prediction",
      "side": "buy",
      "price": "0.65",
      "size": "100",
      "reduceOnly": false,
      "clientOrderId": "0x0197a98c91312671ca83f15ccbd5186f",
      "orderType": { "limit": { "tif": "gtc" } }
    }]
  },
  "nonce": 1708929600000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

TIF (Time In Force)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...789"
  }
}

3.2 Cancel a single order

Cancel an active order. The developer constructs the cancel calldata and signs it; after validating the order's ownership and status, the server submits it to TradeZone.

HTTP Request

POST /api/v5/predictions/orders/cancel

Request Body

Request example

{
  "action": {
    "type": "cancel",
    "cancels": [{
      "assetId": "1",
      "marketType": "prediction",
      "oid": "12345",
      "clientOrderId": "0x"
    }]
  },
  "nonce": 1708929600000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...abc"
  }
}

3.3 Get a single order

Get the full details of a specified order (active or historical).

HTTP Request

GET /api/v5/predictions/orders/{orderId}

Path Parameters

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "id": "1",
    "oid": "1",
    "clientOrderId": "1",
    "marketId": "1",
    "assetId": "1",
    "side": "BUY",
    "orderType": "GTC",
    "sizeType": "BASE",
    "size": "100",
    "price": "0.65",
    "expiration": null,
    "txHash": "0xdef...789",
    "status": "ACTIVE",
    "filledSize": "40",
    "filledAmount": "26",
    "failReason": null,
    "cancelReason": null,
    "oddsType": "points",
    "createdAt": "1710000000000",
    "updatedAt": "1710000000000"
  }
}

Order Status

3.4 Get user orders

Query the current authenticated user's order list, with filtering and pagination.

HTTP Request

GET /api/v5/predictions/orders

Request Parameters (Query)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "list": [
      {
        "id": "1",
        "oid": "1",
        "clientOrderId": "1",
        "marketId": "string",
        "assetId": "1",
        "side": "BUY",
        "orderType": "GTC",
        "sizeType": "BASE",
        "size": "100",
        "price": "0.65",
        "expiration": null,
        "txHash": "0xdef...789",
        "status": "ACTIVE",
        "filledSize": "40",
        "filledAmount": "26",
        "failReason": null,
        "cancelReason": null,
        "oddsType": "points",
        "createdAt": "1710000000000",
        "updatedAt": "1710000000000"
      }
    ],
    "nextCursor": "eyJpZCI6MTIzfQ",
    "hasNext": false
  }
}

3.5 Cancel all / market orders

Cancel the current authenticated user's active orders. When assetIds is an empty list, cancel orders across all markets; when specific values are passed, cancel only the orders in the markets of the corresponding assets.

HTTP Request

POST /api/v5/predictions/orders/cancel-all

Request Body

Request example (cancel by market)

{
  "action": {
    "type": "cancelAll",
    "assetIds": [1, 2, 5],
    "marketType": "prediction"
  },
  "nonce": 1708929600000,
  "expiresAfter": 1708929660000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Request example (cancel all)

{
  "action": {
    "type": "cancelAll",
    "assetIds": [],
    "marketType": "prediction"
  },
  "nonce": 1708929600000,
  "expiresAfter": 1708929660000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...abc"
  }
}

3.6 Send heartbeat

A heartbeat mechanism that protects the developer's active orders. The request body carries a pre-signed cancelAll action with nonce set to the current time + 5 minutes. The server stores this signature; if the developer does not renew the heartbeat within 5 minutes, the system automatically uses this signature to cancel all orders.

The developer should keep calling this endpoint (recommended interval < 5 minutes), each time overwriting the previous pre-signature with a new nonce (current time + 5 minutes).

HTTP Request

POST /api/v5/predictions/heartbeat

Request Body

Request example

{
  "action": {
    "type": "cancelAll",
    "assetIds": [],
    "marketType": "prediction"
  },
  "nonce": 1708929900000,
  "expiresAfter": 1708929960000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "serverTimestamp": 1708929600000,
    "expireAt": 1708929900000
  }
}

Order Semantics

Order Mode Support Matrix

Support matrix

Key rules

1. In the prediction market, ioc is equivalent to the commonly used fak: it fills as much as possible, cancels the remainder, and never leaves a resting order.

2. fok is only supported when ordering by shares: the combination of sizeType=quote and tif=fok is rejected by the server.

3. alo (Post Only) applies only to limit orders: combining it with sizeType=quote or a market order is rejected.

4. A market order is not an "unprotected order": at order time the system simulates a worstPrice from the book and submits it to TradeZone as the price. The actual fill price will never be worse than worstPrice.

5. tif=gtd must include expiration: the field path is action.orders[].orderType.limit.expiration, of type String (Unix ms timestamp, 13 digits), an absolute time. If missing or invalid, it currently throws 10001 PARAM_ERROR.

Error returns for unsupported combinations

Minimum Order Amount & Liquidation Exception

Minimum order amount rule

• The prediction market enforces a minimum notional amount per order: 1 xp.

Sell-All Exception

• After a user sells a position in one direction, if the remaining total position for that assetId (= available + frozen) is 0, it is treated as a sell-all (liquidation).

• In the sell-all scenario, the order is allowed even if the notional fill amount is below 1 xp.

Price Unit & Precision Rules

Valid range

Segmented precision rules

Precision is split into two segments by [0.04, 0.96] and outside it:

ClientOrderId Generation Specification

clientOrderId (cloid for short) is the order's unique identifier on chain. On-chain events are broadcast globally, and consumers in each region use the region/env prefix in the cloid to filter out the orders that belong to them. Any cloid generated by any integrator must follow this specification, otherwise orders will be misattributed.

Format

The format is 0x{region}{env}{random}:

The total length is fixed at 34 characters, all lowercase hex (0-9, a-f).

region / env code table

Each value is a single hex char; currently 0/1/2 are used, and future expansion will not exceed f (15).

random generation requirements

• Entropy: ≥ 120 bits (30 hex = 120 bits)
• Source: must use a cryptographically secure random source or equivalent strength (e.g. UUIDv4, crypto.randomBytes, secrets, etc.)
• Encoding: lowercase hex, zero-padded on the high bits if short

Reference implementations

Java (UUID-derived)

UUID u = UUID.randomUUID();
long hi = u.getMostSignificantBits();
long lo = u.getLeastSignificantBits();
StringBuilder sb = new StringBuilder("0x");
sb.append(Integer.toHexString(region & 0xF));
sb.append(Integer.toHexString(env & 0xF));
for (int i = 14; i >= 0; i--) {
    sb.append(Character.forDigit((int)((hi >>> (i * 4)) & 0xF), 16));
}
for (int i = 14; i >= 0; i--) {
    sb.append(Character.forDigit((int)((lo >>> (i * 4)) & 0xF), 16));
}
return sb.toString();

Node.js

const crypto = require('crypto');
function generate(region, env) {
  const rand = crypto.randomBytes(15).toString('hex'); // 30 hex
  return `0x${region.toString(16)}${env.toString(16)}${rand}`;
}

import secrets
def generate(region: int, env: int) -> str:
    return f"0x{region:x}{env:x}{secrets.token_hex(15)}"

Go

import (
    "crypto/rand"
    "encoding/hex"
    "fmt"
)

func Generate(region, env int) (string, error) {
    b := make([]byte, 15)
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return fmt.Sprintf("0x%x%x%s", region, env, hex.EncodeToString(b)), nil
}

Server-side parsing and attribution

The receiver decides whether a cloid belongs to the current environment using the following rules:

if cloid is null/empty
  or length < 4
  or does not start with "0x"
  or cloid[2], cloid[3] are not valid hex chars:
    treat as HK-staging (region=0, env=0)  <- fallback rule
else:
    region = parse_hex(cloid[2])
    env    = parse_hex(cloid[3])
    check whether it equals the current environment's (region, env)

FAQ

• Heartbeat: if you run a bot, set up a heartbeat to automatically cancel all orders when the bot disconnects. Send a pre-signed cancel-all every < 5 minutes; see the API docs for details.

• Nonce: use the current millisecond timestamp. Each nonce can be used only once.

• Timestamp drift: OK-ACCESS-TIMESTAMP must not differ from server time by more than 30 seconds, otherwise error code 50102 is returned.

4. Positions Operations API

4.1 Split (xp → YES + NO)

Split xp into an equal amount of YES and NO conditional token pairs. The developer constructs and signs the calldata; after validation, the server submits it directly to TradeZone.

HTTP Request

POST /api/v5/predictions/positions/split

Request Body

Request example

{
  "action": {
    "type": "predictionSplit",
    "marketId": "1",
    "size": "100000000"
  },
  "nonce": 1708929600000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...abc"
  }
}

4.2 Merge (YES + NO → xp)

Merge equal amounts of YES and NO conditional tokens back into xp (the inverse of Split). The developer constructs and signs the calldata; after validation, the server submits it directly to TradeZone.

HTTP Request

POST /api/v5/predictions/positions/merge

Request Body

Request example

{
  "action": {
    "type": "predictionMerge",
    "marketId": "1",
    "size": "100000000"
  },
  "nonce": 1708929600000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...abc"
  }
}

4.3 Redeem (redeem xp after settlement)

After a market settles, redeem xp 1:1 with the winning conditional tokens. The redeem amount is not passed in; by default it redeems all of the user's winning tokens.

HTTP Request

POST /api/v5/predictions/positions/redeem

Request Body

Request example

{
  "action": {
    "type": "predictionRedeem",
    "marketId": "1"
  },
  "nonce": 1708929600000,
  "signature": {
    "Ecdsa": {
      "r": "0x...",
      "s": "0x...",
      "v": 1
    }
  }
}

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "txHash": "0xdef...abc"
  }
}

5. Trade History API

5.1 Query trades

Query the current authenticated user's trade (fill) records. The server resolves the userId from the login session and internally converts it to an address for the query.

HTTP Request

GET /api/v5/predictions/trades

Request Parameters (Query)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "list": [
      {
        "tradeId": "1",
        "orderId": "1",
        "marketId": "1",
        "tokenId": "0xabc...001",
        "side": "BUY",
        "size": "50",
        "amount": "32.5",
        "price": "0.65",
        "fee": "0.065",
        "role": "TAKER",
        "txHash": "0xdef...789",
        "createdAt": 1710000030000
      }
    ],
    "nextCursor": "eyJpZCI6MTAwMDF9",
    "hasNext": false
  }
}

6. Positions Query API

6.1 Query current positions

Query the current authenticated user's active positions.

HTTP Request

GET /api/v5/predictions/positions?status=open

6.2 Query closed positions

Query the current authenticated user's exited or settled positions.

HTTP Request

GET /api/v5/predictions/positions?status=closed

6.3 Query positions in a specified market

Query the current authenticated user's positions in a specified market.

HTTP Request

GET /api/v5/predictions/positions?marketId={marketId}

6.4 Unified endpoint

All three scenarios above are implemented through the same endpoint + query parameter combinations:

HTTP Request

GET /api/v5/predictions/positions

Request Parameters (Query)

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": {
    "list": [
      {
        "id": "100001",
        "tokenId": "0xabc...001",
        "marketId": "1",
        "tokenIndex": "1",
        "tokenName": "Yes",
        "size": "500",
        "availableSize": "480",
        "value": "325",
        "avgPrice": "0.62",
        "unRealizedPnl": "15",
        "unRealizedPnlPercentage": "0.048",
        "title": "Will BTC exceed $100k by end of 2026?",
        "icon": "https://cdn.example.com/markets/1.png",
        "eventId": "100",
        "winningToken": null,
        "positionStatus": 1,
        "oddsType": "points",
        "curPrice": "0.65",
        "realizedPnl": "12.5",
        "realizedPnlPercentage": "0.04"
      }
    ],
    "nextCursor": "eyJpZCI6MTAwMDAxfQ",
    "hasNext": false
  }
}

7. Account Balance API

7.1 Query account balance

Query the current authenticated user's xp balance.

HTTP Request

GET /api/v5/predictions/balance

Request parameters: none

Response (data):

Response example

{
  "code": 0,
  "message": "OK",
  "data": [
    { "oddsType": "points", "balance": "2.2",  "available": "2.2"  }
  ]
}

data is an array; each element corresponds to the balance of one odds type:

8. Rate Limits