ritmex-bot/docs/standx/http.md at feat/mm

mirror of https://github.com/discountry/ritmex-bot.git synced 2026-09-09 08:18:07 +00:00

Files

T

discountry 93c6409688 Integrate StandX exchange support by updating configuration files, adding environment variables, and enhancing documentation. Include new API endpoints and authentication details for StandX in README and dedicated documentation files. Update CLI and adapter logic to accommodate StandX functionalities.

2025-12-21 15:37:03 +08:00

19 KiB

Raw Permalink Blame History

StandX Perps HTTP API List

⚠️ This document is under construction.

API Overview

Base URL

https://perps.standx.com

Authentication

All endpoints except public endpoints require JWT authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <your_jwt_token>

Token Validity: 7 days

Body Signature

Some endpoints require body signature. Add the following headers to signed requests:

x-request-sign-version: v1
x-request-id: <random_string>
x-request-timestamp: <timestamp_in_milliseconds>
x-request-signature: <your_body_signature>

See Authentication Guide for implementation details.

Session ID

For new_order and cancel_order requests, you will want to know the results of these requests after actual matching. To obtain these results, you need to add the following information to the header in these interface requests:

x-session-id: <your_custom_session_id>

Note that this session_id needs to be consistent with the session_id used in your ws-client.

Request Format

int parameters (e.g., timestamp) are expected as JSON integers, not strings
decimal parameters (e.g., price) are expected as JSON strings, not floats

Trade Endpoints

Create New Order

POST /api/new_order

Note: A successful response indicates the order was submitted, not necessarily executed. Some orders (e.g., ALO) may be rejected during matching if conditions are not met. Subscribe to Order Response Stream for real-time execution status.

To receive order updates via Order Response Stream, add the x-session-id header to your request. This session_id must be consistent with the session_id used in your ws-client.

Authentication Required • Body Signature Required

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
side	enum	Order side (see Reference)
order_type	enum	Order type (see Reference)
qty	decimal	Order quantity
time_in_force	enum	Time in force (see Reference)
reduce_only	boolean	Only reduce position if `true`

Optional Parameters

Parameter	Type	Description
price	decimal	Order price (required for limit orders)
cl_ord_id	string	Client order ID (auto-generated if omitted)
margin_mode	enum	Margin mode (see Reference). Must match position
leverage	int	Leverage value. Must match position

Request Example:

{
  "symbol": "BTC-USD",
  "side": "buy",
  "order_type": "limit",
  "qty": "0.1",
  "price": "50000",
  "time_in_force": "gtc",
  "reduce_only": false
}

Response Example:

{
  "code": 0,
  "message": "success",
  "request_id": "xxx-xxx-xxx"
}

Cancel Order

POST /api/cancel_order

To receive order updates via Order Response Stream, add the x-session-id header to your request. This session_id must be consistent with the session_id used in your ws-client.

Authentication Required • Body Signature Required

Parameters

At least one of order_id or cl_ord_id is required.

Parameter	Type	Description
order_id	int	Order ID to cancel
cl_ord_id	string	Client order ID to cancel

Request Example:

{
  "order_id": 2424844
}

Response Example:

{
  "code": 0,
  "message": "success",
  "request_id": "xxx-xxx-xxx"
}

Cancel Multiple Orders

POST /api/cancel_orders

Authentication Required • Body Signature Required

Parameters

At least one of order_id_list or cl_ord_id_list is required.

Parameter	Type	Description
order_id_list	int[]	Order IDs to cancel
cl_ord_id_list	string[]	Client order IDs to cancel

Request Example:

{
  "order_id_list": [2424844]
}

Response Example:

[]

Change Leverage

POST /api/change_leverage

Authentication Required • Body Signature Required

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
leverage	int	New leverage value

Request Example:

{
  "symbol": "BTC-USD",
  "leverage": 10
}

Response Example:

{
  "code": 0,
  "message": "success",
  "request_id": "xxx-xxx-xxx"
}

Change Margin Mode

POST /api/change_margin_mode

Authentication Required • Body Signature Required

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
margin_mode	enum	Margin mode (see Reference)

Request Example:

{
  "symbol": "BTC-USD",
  "margin_mode": "cross"
}

Response Example:

{
  "code": 0,
  "message": "success",
  "request_id": "xxx-xxx-xxx"
}

User Endpoints

Transfer Margin

POST /api/transfer_margin

Authentication Required • Body Signature Required

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
amount_in	decimal	Amount to transfer

Request Example:

{
  "symbol": "BTC-USD",
  "amount_in": "1000.0"
}

Response Example:

{
  "code": 0,
  "message": "success",
  "request_id": "xxx-xxx-xxx"
}

Query Order

GET /api/query_order

⚠️ NOTE: Orders may be rejected due mis-qualification due async matching network structure. To receive the order updates in real-time, please check Order Response Stream.

Authentication Required

Query Parameters

At least one of order_id or cl_ord_id is required.

Parameter	Type	Description
order_id	int	Order ID to query
cl_ord_id	string	Client order ID to query

Response Example:

{
  "avail_locked": "3.071880000",
  "cl_ord_id": "01K2BK4ZKQE0C308SRD39P8N9Z",
  "closed_block": -1,
  "created_at": "2025-08-11T03:35:25.559151Z",
  "created_block": -1,
  "fill_avg_price": "0",
  "fill_qty": "0",
  "id": 1820682,
  "leverage": "10",
  "liq_id": 0,
  "margin": "0",
  "order_type": "limit",
  "payload": null,
  "position_id": 15,
  "price": "121900.00",
  "qty": "0.060",
  "reduce_only": false,
  "remark": "",
  "side": "sell",
  "source": "user",
  "status": "open",
  "symbol": "BTC-USD",
  "time_in_force": "gtc",
  "updated_at": "2025-08-11T03:35:25.559151Z",
  "user": "bsc_0x..."
}

Query User Orders

GET /api/query_orders

Authentication Required

Query Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
status	enum	Order status (see Reference)
order_type	enum	Order type (see Reference)
start	string	Start time in ISO 8601 format
end	string	End time in ISO 8601 format
last_id	number	Last order ID for pagination
limit	number	Results limit (default: 100, max: 500)

Response Example:

{
  "page_size": 1,
  "result": [
    {
      "avail_locked": "3.071880000",
      "cl_ord_id": "01K2BK4ZKQE0C308SRD39P8N9Z",
      "closed_block": -1,
      "created_at": "2025-08-11T03:35:25.559151Z",
      "created_block": -1,
      "fill_avg_price": "0",
      "fill_qty": "0",
      "id": 1820682,
      "leverage": "10",
      "liq_id": 0,
      "margin": "0",
      "order_type": "limit",
      "payload": null,
      "position_id": 15,
      "price": "121900.00",
      "qty": "0.060",
      "reduce_only": false,
      "remark": "",
      "side": "sell",
      "source": "user",
      "status": "new",
      "symbol": "BTC-USD",
      "time_in_force": "gtc",
      "updated_at": "2025-08-11T03:35:25.559151Z",
      "user": "bsc_0x..."
    }
  ],
  "total": 1
}

Query User All Open Orders

GET /api/query_open_orders

Authentication Required

Query Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
limit	number	Results limit (default: 500, max: 1200)

Response Example:

{
  "page_size": 1,
  "result": [
    {
      "avail_locked": "3.071880000",
      "cl_ord_id": "01K2BK4ZKQE0C308SRD39P8N9Z",
      "closed_block": -1,
      "created_at": "2025-08-11T03:35:25.559151Z",
      "created_block": -1,
      "fill_avg_price": "0",
      "fill_qty": "0",
      "id": 1820682,
      "leverage": "10",
      "liq_id": 0,
      "margin": "0",
      "order_type": "limit",
      "payload": null,
      "position_id": 15,
      "price": "121900.00",
      "qty": "0.060",
      "reduce_only": false,
      "remark": "",
      "side": "sell",
      "source": "user",
      "status": "new",
      "symbol": "BTC-USD",
      "time_in_force": "gtc",
      "updated_at": "2025-08-11T03:35:25.559151Z",
      "user": "bsc_0x..."
    }
  ],
  "total": 1
}

Query User Trades

GET /api/query_trades

Authentication Required

Query Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
last_id	number	Last trade ID for pagination
side	string	Order side (see Reference)
start	string	Start time in ISO 8601 format
end	string	End time in ISO 8601 format
limit	number	Results limit (default: 100, max: 500)

Response Example:

{
  "page_size": 1,
  "result": [
    {
      "created_at": "2025-08-11T03:36:19.352620Z",
      "fee_asset": "DUSD",
      "fee_qty": "0.121900",
      "id": 409870,
      "order_id": 1820682,
      "pnl": "1.62040",
      "price": "121900",
      "qty": "0.01",
      "side": "sell",
      "symbol": "BTC-USD",
      "updated_at": "2025-08-11T03:36:19.352620Z",
      "user": "bsc_0x...",
      "value": "1219.00"
    }
  ],
  "total": 1
}

Query Position Config

GET /api/query_position_config

Authentication Required

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

{
  "symbol": "BTC-USD",
  "leverage": 10,
  "margin_mode": "cross"
}

Query User Positions

GET /api/query_positions

Authentication Required

Query Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

[
  {
    "bankruptcy_price": "109608.01",
    "created_at": "2025-08-10T09:05:50.265265Z",
    "entry_price": "121737.96",
    "entry_value": "114433.68240",
    "holding_margin": "11443.3682400",
    "id": 15,
    "initial_margin": "11443.36824",
    "leverage": "10",
    "liq_price": "112373.50",
    "maint_margin": "2860.30367500",
    "margin_asset": "DUSD",
    "margin_mode": "isolated",
    "mark_price": "121715.05",
    "mmr": "3.993223845366698695025800014",
    "position_value": "114412.14700",
    "qty": "0.940",
    "realized_pnl": "31.61532",
    "status": "open",
    "symbol": "BTC-USD",
    "time": "2025-08-11T03:41:40.922818Z",
    "updated_at": "2025-08-10T09:05:50.265265Z",
    "upnl": "-21.53540",
    "user": "bsc_0x..."
  }
]

Query User Balances

Endpoint: /api/query_balance
Method: GET
Authentication: Required
Description: Unified balance snapshot.

Response Fields:

Name	Type	Description
isolated_balance	decimal	Isolated wallet total
isolated_upnl	decimal	Isolated unrealized PnL
cross_balance	decimal	Cross wallet free balance
cross_margin	decimal	Cross margin used (executed positions only)
cross_upnl	decimal	Cross unrealized PnL
locked	decimal	Order lock (margin + fee), already includes safety factor b
cross_available	decimal	cross_balance - cross_margin - locked + cross_upnl
balance	decimal	Total account assets = cross_balance + isolated_balance
upnl	decimal	Total unrealized PnL = cross_upnl + isolated_upnl
equity	decimal	Account equity = balance + upnl
pnl_freeze	decimal	24h realized PnL (for display)

Response Example:

{
  "isolated_balance": "11443.3682400",
  "isolated_upnl": "-21.53540",
  "cross_balance": "1088575.259316737",
  "cross_margin": "2860.30367500",
  "cross_upnl": "31.61532",
  "locked": "0.000000000",
  "cross_available": "1085746.571",
  "balance": "1100018.627556737",
  "upnl": "10.07992",
  "equity": "1100028.707476657",
  "pnl_freeze": "31.61532"
}

Notes:

cross_available may be negative depending on PnL and locks;

Public Endpoints

Query Symbol Info

GET /api/query_symbol_info

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

[
  {
    "base_asset": "BTC",
    "base_decimals": 9,
    "created_at": "2025-07-10T05:15:32.089568Z",
    "def_leverage": "10",
    "depth_ticks": "0.01,0.1,1",
    "enabled": true,
    "maker_fee": "0.0001",
    "max_leverage": "20",
    "max_open_orders": "100",
    "max_order_qty": "100",
    "max_position_size": "1000",
    "min_order_qty": "0.001",
    "price_cap_ratio": "0.3",
    "price_floor_ratio": "0.3",
    "price_tick_decimals": 2,
    "qty_tick_decimals": 3,
    "quote_asset": "DUSD",
    "quote_decimals": 9,
    "symbol": "BTC-USD",
    "taker_fee": "0.0004",
    "updated_at": "2025-07-10T05:15:32.089568Z"
  }
]

Query Symbol Market

GET /api/query_symbol_market

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

{
  "base": "BTC",
  "funding_rate": "0.00010000",
  "high_price_24h": "122164.08",
  "index_price": "121601.158461",
  "last_price": "121599.94",
  "low_price_24h": "114098.44",
  "mark_price": "121602.43",
  "mid_price": "121599.99",
  "next_funding_time": "2025-08-11T08:00:00Z",
  "open_interest": "15.948",
  "quote": "DUSD",
  "spread": ["121599.94", "121600.04"],
  "symbol": "BTC-USD",
  "time": "2025-08-11T03:44:40.922233Z",
  "volume_24h": "9030.51800000000002509"
}

Query Symbol Price

GET /api/query_symbol_price

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

{
  "base": "BTC",
  "index_price": "121601.158461",
  "last_price": "121599.94",
  "mark_price": "121602.43",
  "mid_price": "121599.99",
  "quote": "DUSD",
  "spread_ask": "121600.04",
  "spread_bid": "121599.94",
  "symbol": "BTC-USD",
  "time": "2025-08-11T03:44:40.922233Z"
}

Note

: last_price, mid_price, spread_ask, spread_bid may be null if no recent trades.

Query Depth Book

GET /api/query_depth_book

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

{
  "asks": [
    ["121895.81", "0.843"],
    ["121896.11", "0.96"]
  ],
  "bids": [
    ["121884.01", "0.001"],
    ["121884.31", "0.001"]
  ],
  "symbol": "BTC-USD"
}

GET /api/query_recent_trades

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)

Response Example:

[
  {
    "is_buyer_taker": true,
    "price": "121720.18",
    "qty": "0.01",
    "quote_qty": "1217.2018",
    "symbol": "BTC-USD",
    "time": "2025-08-11T03:48:47.086505Z"
  },
  {
    "is_buyer_taker": true,
    "price": "121720.18",
    "qty": "0.01",
    "quote_qty": "1217.2018",
    "symbol": "BTC-USD",
    "time": "2025-08-11T03:48:46.850415Z"
  }
]

Query Funding Rates

GET /api/query_funding_rates

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
start_time	int	Start time in milliseconds
end_time	int	End time in milliseconds

Response Example:

[
  {
    "id": 1,
    "symbol": "BTC-USD",
    "funding_rate": "0.0001",
    "index_price": "121601.158461",
    "mark_price": "121602.43",
    "premium": "0.0001",
    "time": "2025-08-11T03:48:47.086505Z",
    "created_at": "2025-08-11T03:48:47.086505Z",
    "updated_at": "2025-08-11T03:48:47.086505Z"
  }
]

Kline Endpoints

Get Server Time

GET /api/kline/time

Response Example:

1620000000

Get Kline History

GET /api/kline/history

Required Parameters

Parameter	Type	Description
symbol	string	Trading pair (see Reference)
from	u64	Unix timestamp in seconds
to	u64	Unix timestamp in seconds
resolution	enum	Resolution (see Reference)

Optional Parameters

Parameter	Type	Description
countBack	u64	The required amount of bars to load

Response Example:

{
  "s": "ok",
  "t": [1754897028, 1754897031],
  "c": [121897.95, 121903.04],
  "o": [121896.02, 121898.05],
  "h": [121897.95, 121903.15],
  "l": [121895.92, 121898.05],
  "v": [0.09, 10.542]
}

Health Check

Health

GET /api/health

Response:

OK

Misc

Region and Server Time

GET https://geo.standx.com/v1/region

Response Example:

{
  "systemTime": 1761970177865,
  "region": "jp"
}

Reference

For enums, constants, and error codes, see API Reference.

Last updated on

Perps Auth Perps WebSocket API

19 KiB Raw Permalink Blame History

StandX Perps HTTP API List

API Overview

Base URL

Authentication

Body Signature

Session ID

Request Format

Trade Endpoints

Create New Order

Cancel Order

Cancel Multiple Orders

Change Leverage

Change Margin Mode

User Endpoints

Transfer Margin

Query Order

Query User Orders

Query User All Open Orders

Query User Trades

Query Position Config

Query User Positions

Query User Balances

Public Endpoints

Query Symbol Info

Query Symbol Market

Query Symbol Price

Query Depth Book

Query Funding Rates

Kline Endpoints

Get Server Time

Get Kline History

Health Check

Health

Misc

Region and Server Time

Reference

19 KiB

Raw Permalink Blame History