Get a single order by internal id

GET

orders

{order_id}

curl --request GET \
  --url https://execution.kairos.trade/orders/{order_id} \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://execution.kairos.trade/orders/{order_id}"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://execution.kairos.trade/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>",
    "X-Api-Secret: <api-key>",
    "X-Client-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/orders/{order_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/orders/{order_id}")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user_id": "<string>",
  "exchange_id": "polymarket",
  "market_id": "<string>",
  "side": "buy",
  "kind": "limit",
  "quantity": "100",
  "time_in_force": "GTC",
  "filled_quantity": "0",
  "status": "live",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "gas_sponsored": true,
  "collateral_mode": "skip",
  "shard_funding": true,
  "holding_wallet": "<string>",
  "token_id": "<string>",
  "price": "0.52",
  "price_bps": 5200,
  "post_only": false,
  "expires_at": "2023-11-07T05:31:56Z",
  "avg_fill_price": "<string>",
  "avg_fill_price_bps": 123,
  "exchange_order_id": "<string>",
  "terminal_fill_verification": {
    "state": "pending",
    "exchange_order_id": "<string>",
    "reason": "explicit_cancel",
    "target_status": "cancelled",
    "started_at": "2023-11-07T05:31:56Z",
    "final_filled_quantity": "<string>",
    "verified_at": "2023-11-07T05:31:56Z"
  },
  "locked_by": "<string>",
  "lock_expires_at": "2023-11-07T05:31:56Z",
  "error_message": "<string>",
  "failure": {
    "code": "FOK_NOT_FILLED",
    "classification": "expected_user_rejection",
    "details": {
      "code": "FUNDS_INSUFFICIENT_USDC",
      "message": "<string>",
      "actions": [
        {
          "action": "enable_trading",
          "label": "Add Funds",
          "primary": true,
          "url": "<string>"
        }
      ],
      "details": "<string>",
      "metadata": {}
    }
  },
  "fee_amount": "<string>",
  "fee_currency": "<string>",
  "client_order_id": "<string>",
  "wallet_id": "<string>",
  "outcome": "<string>",
  "outcome_id": "<string>",
  "trigger_price": "<string>",
  "trigger_price_bps": 123,
  "max_bridge_fee_usdc": "<string>",
  "max_funding_wait_ms": 123,
  "gas_amount": "<string>",
  "maker_address": "<string>",
  "tx_hash": "<string>",
  "raw": "<unknown>",
  "bot_id": "<string>",
  "source": "api",
  "metadata": "<unknown>"
}

{
  "error": "Unauthorized"
}

Authorizations

X-Client-Id

string

header

required

Credential client id (kairos_ck_...). Must be sent together with X-Api-Key and X-Api-Secret.

X-Api-Key

string

header

required

64-char hex API key.

X-Api-Secret

string

header

required

64-char hex API secret.

Path Parameters

order_id

string<uuid>

required

Internal Kairos order id (the order_id returned by POST /orders or POST /v2/orders/submit).

Response

The order, including raw and metadata.

Exchange-agnostic order record.

string<uuid>

required

Internal Kairos order id.

user_id

string

required

Owning user's id.

exchange_id

string

required

Venue identifier (e.g. polymarket, kalshi, predictfun, hyperliquid).

Example:

"polymarket"

market_id

string

required

Market/contract identifier on the venue (condition id for Polymarket; numeric HIP-4 outcome id for Hyperliquid).

side

enum<string>

required

Order/intent side. Lower-case on the wire.

Available options:

buy,

sell

Example:

"buy"

kind

enum<string>

required

Order type. market orders still require a price (the limit you'll cross to); limit orders rest at price until filled or cancelled.

Available options:

market,

limit

Example:

"limit"

quantity

string

required

Order quantity (decimal string, full precision), shares/contracts.

Example:

"100"

time_in_force

enum<string>

required

Time-in-force, always UPPER-CASE on the wire. GTC/GTD are resting (limit-style); FOK/FAK/IOC are immediate taker executions.

Available options:

GTC,

GTD,

FOK,

FAK,

IOC

Example:

"GTC"

filled_quantity

string

required

Cumulative filled quantity (decimal string).

Example:

"0"

status

enum<string>

required

Lifecycle status. partial is the wire spelling of a partially-filled order (NOT partially_filled).

The internal states queued, locked and orphaned are persisted as pending, so an order read back from GET /orders or GET /orders/{order_id} reports pending for all three — they are listed here because they are part of the type and can appear on in-process/streamed values. executing is the exception: once a worker claims the order for submission it is persisted as executing, and read-back endpoints report executing until the venue acknowledges (then live) or the attempt fails. The one place a caller sees queued directly is the status field of a fresh POST /orders response, which is the literal string "queued".

Available options:

pending,

queued,

locked,

executing,

live,

partial,

filled,

cancelled,

expired,

failed,

orphaned

Example:

"live"

created_at

string<date-time>

required

updated_at

string<date-time>

required

gas_sponsored

boolean

required

Whether Kairos sponsored gas for this order (always false on the self-custody external-signing lane).

collateral_mode

enum<string>

required

The collateral mode resolved for this order at submit. Always present; skip for an order that asked for nothing.

Available options:

skip,

check,

fund

Example:

"skip"

shard_funding

boolean

required

Whether the Kalshi shard move was permitted for this order. Always present; true unless the caller opted out.

Example:

true

holding_wallet

string

required

On-chain wallet that holds (or will hold) the resulting shares — the EOA for legacy Polymarket orders, or the Safe deposit-wallet proxy for upgraded/external-signing users. Empty string for non-Polymarket orders.

token_id

string | null

Outcome-token id. Hyperliquid uses a side coin such as #1010 or #1011.

price

string | null

Limit price as a decimal string in [tick, 1] (prediction-market venues).

Example:

"0.52"

price_bps

integer | null

price expressed in basis points (price × 10000), for DB/analytics compatibility.

Example:

5200

post_only

boolean

default:false

Whether this order was submitted maker-only. A post-only order is one the venue was told to REJECT rather than let cross the spread and take liquidity. Always present; false for ordinary orders and for venues with no post-only concept.

Example:

false

expires_at

string<date-time> | null

Expiration timestamp for GTD orders.

avg_fill_price

string | null

Size-weighted average fill price (decimal string, 0..1), null until any fill lands.

avg_fill_price_bps

integer | null

avg_fill_price in basis points.

exchange_order_id

string | null

Venue-assigned order handle. Null until the order reaches the venue.

terminal_fill_verification

object | null

Durable venue-terminal fill barrier. While pending, callers must retain protection even if another status field appears terminal. complete carries the exact venue cumulative that was folded before terminal publication.

Show child attributes

locked_by

string | null

Worker id currently holding the execution lock, if any.

lock_expires_at

string<date-time> | null

error_message

string | null

Failure detail when status is failed.

failure

object

Structured failure detail attached to a failed order (GET /orders, GET /orders/{order_id}, and the order_update WebSocket event). OMITTED entirely (not null) when the order has no failure.

classification is the authoritative retry policy: expected_user_rejection is a well-formed request the venue or the user's own inputs rejected — do not retry without changing the order; retryable is a transient condition that may succeed on retry; non_retryable cannot succeed by retrying the same order.

details.actions is a UI affordance only. It is derived from code independently of classification and may include retry (even as primary) on a non_retryable failure, because the suggested buttons target an end user who may be able to change something first. Do NOT build an automatic retry loop from actions; branch on classification. A client that is not rendering buttons can ignore actions entirely.

Show child attributes

fee_amount

string | null

Fee charged for this order, decimal string.

fee_currency

string | null

client_order_id

string | null

Caller-supplied idempotency key, if one was provided at submission.

wallet_id

string | null

FK to the user's wallet used for this order.

outcome

string | null

Human-readable outcome label (e.g. "Yes", "No", a team name).

outcome_id

string | null

Outcome id — equals token_id on Polymarket.

trigger_price

string | null

Trigger price for stop-loss/take-profit style orders, decimal string.

trigger_price_bps

integer | null

max_bridge_fee_usdc

string | null

The order's bridge-fee ceiling in USDC, decimal string. Only ever set under collateral_mode=fund.

max_funding_wait_ms

integer | null

The order's funding-wait ceiling in milliseconds. Only ever set under collateral_mode=fund.

gas_amount

string | null

Gas spent, decimal string, if applicable.

maker_address

string | null

On-chain maker/signer address, for Polymarket reconciliation.

tx_hash

string | null

On-chain transaction hash (Polygon), if the fill involved one.

raw

any | null

Full raw venue request/response payload for audit. Present on GET /orders/{order_id}; stripped to null on GET /orders (list responses) to keep list payloads small.

bot_id

string | null

Trading-bot id that placed this order, if any (null for manual/API orders).

source

string | null

Attribution for who initiated the order: manual (web UI), bot, copytrade, api (API-key auth), or fastlane (external-signing lane).

Example:

"api"

metadata

any | null

Exchange-specific metadata (arbitrary JSON). Present on GET /orders/{order_id}; stripped to null on GET /orders.

Get a single order by internal id

curl --request GET \
  --url https://execution.kairos.trade/orders/{order_id} \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-key>' \
  --header 'X-Client-Id: <api-key>'

import requests

url = "https://execution.kairos.trade/orders/{order_id}"

headers = {
    "X-Client-Id": "<api-key>",
    "X-Api-Key": "<api-key>",
    "X-Api-Secret": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-Client-Id': '<api-key>',
    'X-Api-Key': '<api-key>',
    'X-Api-Secret': '<api-key>'
  }
};

fetch('https://execution.kairos.trade/orders/{order_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/orders/{order_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: <api-key>",
    "X-Api-Secret: <api-key>",
    "X-Client-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/orders/{order_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Client-Id", "<api-key>")
	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("X-Api-Secret", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/orders/{order_id}")
  .header("X-Client-Id", "<api-key>")
  .header("X-Api-Key", "<api-key>")
  .header("X-Api-Secret", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/orders/{order_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Client-Id"] = '<api-key>'
request["X-Api-Key"] = '<api-key>'
request["X-Api-Secret"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user_id": "<string>",
  "exchange_id": "polymarket",
  "market_id": "<string>",
  "side": "buy",
  "kind": "limit",
  "quantity": "100",
  "time_in_force": "GTC",
  "filled_quantity": "0",
  "status": "live",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "gas_sponsored": true,
  "collateral_mode": "skip",
  "shard_funding": true,
  "holding_wallet": "<string>",
  "token_id": "<string>",
  "price": "0.52",
  "price_bps": 5200,
  "post_only": false,
  "expires_at": "2023-11-07T05:31:56Z",
  "avg_fill_price": "<string>",
  "avg_fill_price_bps": 123,
  "exchange_order_id": "<string>",
  "terminal_fill_verification": {
    "state": "pending",
    "exchange_order_id": "<string>",
    "reason": "explicit_cancel",
    "target_status": "cancelled",
    "started_at": "2023-11-07T05:31:56Z",
    "final_filled_quantity": "<string>",
    "verified_at": "2023-11-07T05:31:56Z"
  },
  "locked_by": "<string>",
  "lock_expires_at": "2023-11-07T05:31:56Z",
  "error_message": "<string>",
  "failure": {
    "code": "FOK_NOT_FILLED",
    "classification": "expected_user_rejection",
    "details": {
      "code": "FUNDS_INSUFFICIENT_USDC",
      "message": "<string>",
      "actions": [
        {
          "action": "enable_trading",
          "label": "Add Funds",
          "primary": true,
          "url": "<string>"
        }
      ],
      "details": "<string>",
      "metadata": {}
    }
  },
  "fee_amount": "<string>",
  "fee_currency": "<string>",
  "client_order_id": "<string>",
  "wallet_id": "<string>",
  "outcome": "<string>",
  "outcome_id": "<string>",
  "trigger_price": "<string>",
  "trigger_price_bps": 123,
  "max_bridge_fee_usdc": "<string>",
  "max_funding_wait_ms": 123,
  "gas_amount": "<string>",
  "maker_address": "<string>",
  "tx_hash": "<string>",
  "raw": "<unknown>",
  "bot_id": "<string>",
  "source": "api",
  "metadata": "<unknown>"
}

{
  "error": "Unauthorized"
}

Overview

Market Data API

Data API

Execution API

Agora Auction API

REST Guides

Market Data Guides

RPC Guides

RFQ Guides

WebSocket Guides

Krisis Guides

Get a single order by internal id

Authorizations

Path Parameters

Response