> This is part 1 of 2 of the full documentation (pages 1–100 of 142). > The content is paginated: fetch every part to see all of it. > Next part: https://www.pionex.com/docs/llms-full.txt/1 > Page index: https://www.pionex.com/docs/llms.txt # Home Welcome to Pionex Docs

Pionex Docs

Here you see an Open and AI-friendly Pionex.

Cover image

:square-terminal:

API DocsREST and WebSocket APIs for Spot, Futures, Bot, Earn and more.Englishcard1_api_doc.png

:sparkle:

AI Kit DocsMCP, Skills and CLI for your AI agents.Englishcard2_ai_mcp.png
# Overview Welcome to the API documentation. We provide complete RESTful API and WebSocket API to meet your trading needs. * It is recommended to set up an IP whitelisting along with API Key for security purpose. * Never tell your API Key/ Secret to anyone. * Feel free to join our Official Group if there is any question: .

:square-terminal:

Trade APITrade API

:square-terminal:

Trade WebsocketTrade Websocket

:square-terminal:

Wallet APIWallet API

:square-terminal:

Futures API (Internal)Futures API

:square-terminal:

Futures Websocket (Internal)Futures Websocket

:square-terminal:

Bot APIBot API

:square-terminal:

Earn API (Beta)Earn API

:square-terminal:

Earn Dual API (Beta)Earn Dual API

:square-terminal:

InstFund API (Internal)InstFund API

:square-terminal:

Partner API (Internal)Partner API

:square-terminal:

Institution API (Internal)Institution API
## References

:key:

API Key Guide :arrow-right:https://www.pionex.com/docs/api-docs/references/api-key-guide

:shield:

API Key Permissions :arrow-right:https://www.pionex.com/docs/api-docs/references/api-key-permissions

:github:

GitHub :arrow-right:https://github.com/pionex-official/pionex-open-api

:telegram:

Support :arrow-right:https://t.me/pionexapi
# Change log #### 2026-09-03 * Add Institution API (Internal) Institutional service-provider API (`/api/v2/institution/*`) for onboarding and operating the sub-accounts bound to an institution: fiat deposit/withdrawal, on-chain assets, stablecoin conversion, and trading-account balances. Uses public-key (RSA / Ed25519) signature authentication with per-key `read` / `write` scopes. Read endpoints (requires `read` scope): * `GET /api/v2/institution/users` : List sub-accounts * `GET /api/v2/institution/kyb` : Get platform KYB status * `GET /api/v2/institution/wire/deposit/account/requirements` : Get channel deposit onboarding requirements * `GET /api/v2/institution/wire/deposit/account` : Get deposit-account onboarding status * `GET /api/v2/institution/wire/deposit/accounts` : List deposit accounts * `GET /api/v2/institution/wire/deposit/orders` : List deposit orders * `GET /api/v2/institution/wire/deposit/order` : Get a deposit order * `GET /api/v2/institution/wire/payout/account/requirements` : Get payout-account field requirements * `GET /api/v2/institution/wire/payout/accounts` : List payout accounts * `GET /api/v2/institution/wire/payout/orders` : List payout orders * `GET /api/v2/institution/wire/payout/order` : Get a payout order * `GET /api/v2/institution/asset/currencies` : List currencies and chains * `GET /api/v2/institution/asset/withdraw` : Query a single on-chain withdrawal * `GET /api/v2/institution/asset/records` : Query deposit/withdrawal history * `GET /api/v2/institution/addressBooks` : List address-book entries * `GET /api/v2/institution/account/balances` : Get trading-account balances * `GET /api/v2/institution/convert/orders` : List conversion orders * `GET /api/v2/institution/convert/order` : Get a conversion order * `GET /api/v2/institution/file/download` : Download a file Write endpoints (requires `write` scope): * `POST /api/v2/institution/user/create` : Create a sub-account * `POST /api/v2/institution/kyb/create` : Submit platform KYB * `POST /api/v2/institution/wire/deposit/account/create` : Onboard a deposit account (channel KYB) * `POST /api/v2/institution/wire/payout/account/create` : Create a payout account * `POST /api/v2/institution/wire/payout/account/update` : Update a payout account * `POST /api/v2/institution/wire/payout/account/delete` : Delete a payout account * `POST /api/v2/institution/wire/payout/order/create` : Create a payout (fiat withdrawal) * `POST /api/v2/institution/asset/withdraw` : Create an on-chain withdrawal * `POST /api/v2/institution/addressBook` : Add an address-book entry * `POST /api/v2/institution/addressBook/delete` : Delete an address-book entry * `POST /api/v2/institution/convert/order/create` : Create a conversion * `POST /api/v2/institution/file/upload` : Upload a file #### 2026-07-21 * Add InstFund API (Invite only) Institutional fiat deposit, withdrawal, and fee query endpoints. Available to onboarded institutional users only. Private endpoints (requires Enable reading permission): * `GET /api/v1/instFund/straitsx/getAccount` : Query the InstFund virtual account * `GET /api/v1/instFund/straitsx/getWithdrawAccounts` : List bound withdraw accounts * `GET /api/v1/instFund/common/getDeposits` : Query fiat deposit history * `GET /api/v1/instFund/common/getWithdraws` : Query fiat withdrawal history * `GET /api/v1/instFund/common/getFee` : Query withdrawal fee Private endpoints (requires Institutional deposit & withdrawal permission): * `POST /api/v1/instFund/straitsx/createWithdraw` : Create a fiat withdrawal request #### 2026-04-01 * Add Earn API (Beta) Dual Investment endpoints for structured investment products: Public endpoints: * `GET /api/v1/earn/dual/symbols` : List supported trading pairs * `GET /api/v1/earn/dual/openProducts` : Query active products by direction * `GET /api/v1/earn/dual/prices` : Fetch yield rates and investability status * `GET /api/v1/earn/dual/index` : Real-time index price for settlement * `GET /api/v1/earn/dual/deliveryPrices` : Historical settlement prices Private endpoints (requires Enable reading permission): * `GET /api/v1/earn/dual/balances` : Get Earn Dual account balances * `POST /api/v1/earn/dual/invests` : Batch query investment orders * `GET /api/v1/earn/dual/records` : Get paginated investment history Private endpoints (requires Earn permission): * `POST /api/v1/earn/dual/invest` : Create investment order * `DELETE /api/v1/earn/dual/invest` : Revoke pending investment order * `POST /api/v1/earn/dual/collect` : Harvest settled earnings #### 2024-01-04 * Add new endpoint `GET /api/v1/market/klines` : Query the history klines. #### 2023-08-20 * Add new endpoint `GET /api/v1/market/bookTickers` : Query the best market price and size. #### 2023-06-20 * Market quote endpoints Supports Perpetual Futures. #### 2022-11-24 * Add new endpoint `GET /api/v1/market/tickers` : Query 24 hour rolling window price change statistics. **Careful** when accessing this with no symbol. * Update endpoint `GET /api/v1/market/depth` : upper limit changed to 1000 # Trade API REST endpoints for spot trading: authentication, market data, account balances, and order management.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/trade-api/general-info
## APIs

:square-terminal:

Commonhttps://www.pionex.com/docs/api-docs/trade-api/common

:square-terminal:

Markethttps://www.pionex.com/docs/api-docs/trade-api/market

:square-terminal:

Accounthttps://www.pionex.com/docs/api-docs/trade-api/account

:square-terminal:

Tradehttps://www.pionex.com/docs/api-docs/trade-api/trade
# General Info # Basic Info **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of ±20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"orderId": 123456789}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "TRADE_INVAILD_SYMBOL", "message": "Invalid symbol", "timestamp": 1566691672311} ``` **Error Codes:** | Code | Description | | -------------------- | -------------------------- | | APIKEY\_LOST | API Key is missing | | SIGNATURE\_LOST | Signature is missing | | IP\_NOT\_WHITELISTED | IP is not in the whitelist | | INVALID\_APIKEY | Invalid API Key | | INVALID\_SIGNATURE | Invalid signature | | APIKEY\_EXPIRED | API Key has expired | | INVALID\_TIMESTAMP | Invalid timestamp | | PERMISSION\_DENIED | Permission denied | # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. * The violating IP or account receives a 60-second ban. * Repeated violations extend the ban duration by 10 seconds per additional request. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. Public endpoints (base information, market data) do not require signing. API Keys must have appropriate permissions assigned before accessing corresponding endpoints. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within ±20 seconds) **Signing Process:** 1. Obtain current timestamp in milliseconds 2. Format query parameters as key-value pairs (no URL encoding for signature values) 3. Sort parameters alphabetically by key and join with `&` (include timestamp) 4. Build PATH\_URL by appending sorted parameters to the request path with `?` 5. Prepend the HTTP METHOD (GET, POST, DELETE) to the PATH\_URL 6. For POST/DELETE requests, append the request body; skip for GET 7. Generate HMAC SHA256 using your API Secret and the concatenated string, convert to hexadecimal The resulting hex signature goes into the request header as `PIONEX-SIGNATURE`. #### API Key Permissions Each API Key can be configured with **Enable reading** and/or **Enable trading** permissions. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Enable reading` permission:** * `GET /api/v1/account/balances` — Get account balances * `GET /api/v1/trade/order` — Get order * `GET /api/v1/trade/orderByClientOrderId` — Get order by client order ID * `GET /api/v1/trade/openOrders` — Get open orders * `GET /api/v1/trade/allOrders` — Get all orders * `GET /api/v1/trade/fills` — Get fills * `GET /api/v1/trade/fillsByOrderId` — Get fills by order ID **Endpoints requiring `Enable trading` permission:** * `POST /api/v1/trade/order` — Place a new order * `DELETE /api/v1/trade/order` — Cancel an order * `POST /api/v1/trade/massOrder` — Place multiple orders * `DELETE /api/v1/trade/allOrders` — Cancel all orders # Common Common symbols information ## Get symbols info > Get trading pair information. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Common","description":"Common symbols information"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/common/symbols":{"get":{"tags":["Common"],"summary":"Get symbols info","description":"Get trading pair information. Weight: 5.","operationId":"getSymbols","parameters":[{"name":"symbols","in":"query","description":"Concatenate multiple symbols with ','","schema":{"type":"string"}},{"name":"type","in":"query","description":"Market type. Defaults to SPOT when symbol is not specified.","schema":{"type":"string","enum":["SPOT","PERP"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbols":{"type":"array","items":{"$ref":"#/components/schemas/SymbolInfo"}}}}}}]}}}}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SymbolInfo":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair identifier"},"name":{"type":"string","description":"Name (PERP only)"},"type":{"type":"string","enum":["SPOT","PERP"],"description":"Market type"},"baseCurrency":{"type":"string","description":"Base asset"},"quoteCurrency":{"type":"string","description":"Quote asset"},"basePrecision":{"type":"integer","description":"Base currency decimal places"},"quotePrecision":{"type":"integer","description":"Quote currency decimal places"},"amountPrecision":{"type":"integer","description":"Market buy order amount decimal places"},"minNotional":{"type":"string","description":"Minimum notional value (PERP only)"},"minAmount":{"type":"string","description":"Minimum order amount (SPOT only)"},"minTradeSize":{"type":"string","description":"Minimum limit order quantity"},"maxTradeSize":{"type":"string","description":"Maximum limit order quantity"},"minTradeDumping":{"type":"string","description":"Minimum market sell quantity"},"maxTradeDumping":{"type":"string","description":"Maximum market sell quantity"},"buyCeiling":{"type":"string","description":"Maximum buy price multiplier ratio"},"sellFloor":{"type":"string","description":"Minimum sell price multiplier ratio"},"enable":{"type":"boolean","description":"Whether trading is enabled"},"maxImpactMarket":{"type":"string","description":"Market order max impact price (PERP only)"},"liquidationFeeRate":{"type":"string","description":"Liquidation fee percentage (PERP only)"}}}}}} ``` # Market Market data (public) ## Get market trades > Get recent trades. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/trades":{"get":{"tags":["Market"],"summary":"Get market trades","description":"Get recent trades. Weight: 1.","operationId":"getMarketTrades","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Default: 100. Range: 10 - 500","schema":{"type":"integer","default":100,"minimum":10,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"trades":{"type":"array","items":{"$ref":"#/components/schemas/MarketTrade"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"MarketTrade":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Transaction price"},"size":{"type":"string","description":"Transaction quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade side (from taker perspective)"},"timestamp":{"type":"string","description":"Execution timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get order book depth > Get order book snapshot. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/depth":{"get":{"tags":["Market"],"summary":"Get order book depth","description":"Get order book snapshot. Weight: 1.","operationId":"getMarketDepth","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Default: 20. Range: 1 - 1000","schema":{"type":"integer","default":20,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [price, quantity], sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [price, quantity], sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get 24hr tickers > Get 24-hour price change statistics. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/tickers":{"get":{"tags":["Market"],"summary":"Get 24hr tickers","description":"Get 24-hour price change statistics. Weight: 1.","operationId":"getTickers","parameters":[{"name":"symbol","in":"query","description":"Trading pair symbol. Returns all tickers if not specified.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Defaults to SPOT if symbol is not specified. Accepts SPOT or PERP.","schema":{"type":"string","enum":["SPOT","PERP"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tickers":{"type":"array","items":{"$ref":"#/components/schemas/Ticker"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Ticker":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"time":{"type":"integer","format":"int64","description":"Timestamp in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"24-hour total trading volume"},"amount":{"type":"string","description":"24-hour total trading amount"},"count":{"type":"string","description":"24-hour total trading count"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get book tickers > Get best bid/ask prices. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/bookTickers":{"get":{"tags":["Market"],"summary":"Get book tickers","description":"Get best bid/ask prices. Weight: 1.","operationId":"getBookTickers","parameters":[{"name":"symbol","in":"query","description":"Trading pair symbol. Returns all if not specified.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Defaults to PERP if symbol is not specified. Accepts SPOT or PERP.","schema":{"type":"string","enum":["SPOT","PERP"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tickers":{"type":"array","items":{"$ref":"#/components/schemas/BookTicker"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"BookTicker":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"bidPrice":{"type":"string","description":"Best bid price"},"bidSize":{"type":"string","description":"Volume at the best bid price"},"askPrice":{"type":"string","description":"Best ask price"},"askSize":{"type":"string","description":"Volume at the best ask price"},"timestamp":{"type":"string","description":"Timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get klines (candlestick data) > Get OHLCV candlestick data. Weight: 1. Maximum 10,000 records. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/klines":{"get":{"tags":["Market"],"summary":"Get klines (candlestick data)","description":"Get OHLCV candlestick data. Weight: 1. Maximum 10,000 records.","operationId":"getKlines","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"interval","in":"query","required":true,"description":"Kline interval","schema":{"type":"string","enum":["1M","5M","15M","30M","60M","4H","8H","12H","1D"]}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Default: 100. Range: 1 - 500","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"klines":{"type":"array","items":{"$ref":"#/components/schemas/Kline"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Kline":{"type":"object","properties":{"time":{"type":"integer","format":"int64","description":"Timestamp in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Total trading volume"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` # Account Account information (private) ## Get account balances > Get trading account balances (excludes bot and earn accounts). Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Account information (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Balance":{"type":"object","properties":{"coin":{"type":"string","description":"Cryptocurrency identifier"},"free":{"type":"string","description":"Available balance, 8 decimal digits"},"frozen":{"type":"string","description":"Frozen balance, 8 decimal digits"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/account/balances":{"get":{"tags":["Account"],"summary":"Get account balances","description":"Get trading account balances (excludes bot and earn accounts). Weight: 1.","operationId":"getBalances","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"balances":{"type":"array","description":"Balances sorted by coin in ascending order","items":{"$ref":"#/components/schemas/Balance"}}}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Trade Order management (private) ## Get order > Get order details by order ID. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","enum":["MANUAL","API"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/order":{"get":{"tags":["Trade"],"summary":"Get order","description":"Get order details by order ID. Weight: 1.","operationId":"getOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"orderId","in":"query","required":true,"description":"Order ID","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## New order > Place a new order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"NewOrderRequest":{"type":"object","required":["symbol","side","type"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"clientOrderId":{"type":"string","description":"Client order ID (alphanumeric and hyphen, max 64 characters)","maxLength":64,"pattern":"^[a-zA-Z0-9-]+$"},"size":{"type":"string","description":"Order quantity (required for LIMIT orders and MARKET sell orders)"},"price":{"type":"string","description":"Order price (required for LIMIT orders)"},"amount":{"type":"string","description":"Order amount (required for MARKET buy orders)"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/order":{"post":{"tags":["Trade"],"summary":"New order","description":"Place a new order. Weight: 1.","operationId":"newOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewOrderRequest"}}}},"responses":{"200":{"description":"Order placed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Unique order identifier"},"clientOrderId":{"type":"string","description":"Client-provided order identifier"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel order > Cancel an existing order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/order":{"delete":{"tags":["Trade"],"summary":"Cancel order","description":"Cancel an existing order. Weight: 1.","operationId":"cancelOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","orderId"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"orderId":{"type":"integer","format":"int64","description":"Order ID to cancel"}}}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## New multiple orders > Place multiple orders at once (up to 20, LIMIT only). Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"MassOrderRequest":{"type":"object","required":["symbol","orders"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"orders":{"type":"array","description":"Collection of orders (up to 20)","maxItems":20,"items":{"type":"object","required":["side","type","size","price"],"properties":{"side":{"type":"string","enum":["BUY","SELL"]},"type":{"type":"string","enum":["LIMIT"],"description":"Only LIMIT orders are supported"},"clientOrderId":{"type":"string","description":"Client order ID (alphanumeric and hyphen, max 64 characters)","maxLength":64},"size":{"type":"string","description":"Order quantity"},"price":{"type":"string","description":"Order price"}}}}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/massOrder":{"post":{"tags":["Trade"],"summary":"New multiple orders","description":"Place multiple orders at once (up to 20, LIMIT only). Weight: 1.","operationId":"newMassOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MassOrderRequest"}}}},"responses":{"200":{"description":"Orders placed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64"},"clientOrderId":{"type":"string"}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get order by client order ID > Get order details by client order ID. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","enum":["MANUAL","API"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/orderByClientOrderId":{"get":{"tags":["Trade"],"summary":"Get order by client order ID","description":"Get order details by client order ID. Weight: 1.","operationId":"getOrderByClientOrderId","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"clientOrderId","in":"query","required":true,"description":"Client order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get open orders > Get all open orders for a symbol. Maximum 200 open orders per symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","enum":["MANUAL","API"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/openOrders":{"get":{"tags":["Trade"],"summary":"Get open orders","description":"Get all open orders for a symbol. Maximum 200 open orders per symbol. Weight: 5.","operationId":"getOpenOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get all orders > Get all orders (open and closed) for a symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","enum":["MANUAL","API"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/allOrders":{"get":{"tags":["Trade"],"summary":"Get all orders","description":"Get all orders (open and closed) for a symbol. Weight: 5.","operationId":"getAllOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"startTime","in":"query","description":"Start time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Default: 50. Range: 1 - 200. Returns latest orders when exceeding limit.","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel all orders > Cancel all open orders for a symbol. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/allOrders":{"delete":{"tags":["Trade"],"summary":"Cancel all orders","description":"Cancel all open orders for a symbol. Weight: 1.","operationId":"cancelAllOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"}}}}}},"responses":{"200":{"description":"All orders cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get fills > Get trade fills for a symbol. Returns latest 100 fills when exceeding limit. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/fills":{"get":{"tags":["Trade"],"summary":"Get fills","description":"Get trade fills for a symbol. Returns latest 100 fills when exceeding limit. Weight: 5.","operationId":"getFills","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"startTime","in":"query","description":"Start time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"fills":{"type":"array","description":"Fills sorted by time descending","items":{"$ref":"#/components/schemas/Fill"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get fills by order ID > Get trade fills for a specific order. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Order management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/trade/fillsByOrderId":{"get":{"tags":["Trade"],"summary":"Get fills by order ID","description":"Get trade fills for a specific order. Weight: 5.","operationId":"getFillsByOrderId","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"orderId","in":"query","required":true,"description":"Order ID. Returns empty list if not found.","schema":{"type":"integer","format":"int64"}},{"name":"fromId","in":"query","description":"Return 100 earlier fills before this fill ID. Returns latest fills if unspecified.","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"fills":{"type":"array","description":"Fills sorted by time descending","items":{"$ref":"#/components/schemas/Fill"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code","enum":["APIKEY_LOST","SIGNATURE_LOST","IP_NOT_WHITELISTED","INVALID_APIKEY","INVALID_SIGNATURE","APIKEY_EXPIRED","INVALID_TIMESTAMP","PERMISSION_DENIED","TRADE_INVALID_SYMBOL","TRADE_PARAMETER_ERROR","TRADE_OPERATION_DENIED","TRADE_ORDER_NOT_FOUND","MARKET_INVALID_SYMBOL","MARKET_PARAMETER_ERROR","MARKET_INVALID_TIME"]},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}}}} ``` ## The SymbolInfo object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"SymbolInfo":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair identifier"},"name":{"type":"string","description":"Name (PERP only)"},"type":{"type":"string","enum":["SPOT","PERP"],"description":"Market type"},"baseCurrency":{"type":"string","description":"Base asset"},"quoteCurrency":{"type":"string","description":"Quote asset"},"basePrecision":{"type":"integer","description":"Base currency decimal places"},"quotePrecision":{"type":"integer","description":"Quote currency decimal places"},"amountPrecision":{"type":"integer","description":"Market buy order amount decimal places"},"minNotional":{"type":"string","description":"Minimum notional value (PERP only)"},"minAmount":{"type":"string","description":"Minimum order amount (SPOT only)"},"minTradeSize":{"type":"string","description":"Minimum limit order quantity"},"maxTradeSize":{"type":"string","description":"Maximum limit order quantity"},"minTradeDumping":{"type":"string","description":"Minimum market sell quantity"},"maxTradeDumping":{"type":"string","description":"Maximum market sell quantity"},"buyCeiling":{"type":"string","description":"Maximum buy price multiplier ratio"},"sellFloor":{"type":"string","description":"Minimum sell price multiplier ratio"},"enable":{"type":"boolean","description":"Whether trading is enabled"},"maxImpactMarket":{"type":"string","description":"Market order max impact price (PERP only)"},"liquidationFeeRate":{"type":"string","description":"Liquidation fee percentage (PERP only)"}}}}}} ``` ## The MarketTrade object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"MarketTrade":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Transaction price"},"size":{"type":"string","description":"Transaction quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade side (from taker perspective)"},"timestamp":{"type":"string","description":"Execution timestamp in milliseconds"}}}}}} ``` ## The Ticker object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"Ticker":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"time":{"type":"integer","format":"int64","description":"Timestamp in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"24-hour total trading volume"},"amount":{"type":"string","description":"24-hour total trading amount"},"count":{"type":"string","description":"24-hour total trading count"}}}}}} ``` ## The BookTicker object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"BookTicker":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"bidPrice":{"type":"string","description":"Best bid price"},"bidSize":{"type":"string","description":"Volume at the best bid price"},"askPrice":{"type":"string","description":"Best ask price"},"askSize":{"type":"string","description":"Volume at the best ask price"},"timestamp":{"type":"string","description":"Timestamp in milliseconds"}}}}}} ``` ## The Kline object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"Kline":{"type":"object","properties":{"time":{"type":"integer","format":"int64","description":"Timestamp in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Total trading volume"}}}}}} ``` ## The Balance object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"Balance":{"type":"object","properties":{"coin":{"type":"string","description":"Cryptocurrency identifier"},"free":{"type":"string","description":"Available balance, 8 decimal digits"},"frozen":{"type":"string","description":"Frozen balance, 8 decimal digits"}}}}}} ``` ## The NewOrderRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"NewOrderRequest":{"type":"object","required":["symbol","side","type"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"clientOrderId":{"type":"string","description":"Client order ID (alphanumeric and hyphen, max 64 characters)","maxLength":64,"pattern":"^[a-zA-Z0-9-]+$"},"size":{"type":"string","description":"Order quantity (required for LIMIT orders and MARKET sell orders)"},"price":{"type":"string","description":"Order price (required for LIMIT orders)"},"amount":{"type":"string","description":"Order amount (required for MARKET buy orders)"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag","default":false}}}}}} ``` ## The MassOrderRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"MassOrderRequest":{"type":"object","required":["symbol","orders"],"properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"orders":{"type":"array","description":"Collection of orders (up to 20)","maxItems":20,"items":{"type":"object","required":["side","type","size","price"],"properties":{"side":{"type":"string","enum":["BUY","SELL"]},"type":{"type":"string","enum":["LIMIT"],"description":"Only LIMIT orders are supported"},"clientOrderId":{"type":"string","description":"Client order ID (alphanumeric and hyphen, max 64 characters)","maxLength":64},"size":{"type":"string","description":"Order quantity"},"price":{"type":"string","description":"Order price"}}}}}}}}} ``` ## The Order object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","enum":["MANUAL","API"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}}}}} ``` ## The Fill object ```json {"openapi":"3.0.3","info":{"title":"Pionex Open API","version":"1.0.0"},"components":{"schemas":{"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ``` # Trade Websocket WebSocket streams for spot trading: public market data and private account/order updates.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/trade-websocket/general-info
## Streams

:square-terminal:

Public Streamhttps://www.pionex.com/docs/api-docs/trade-websocket/public-stream

:square-terminal:

Private Streamhttps://www.pionex.com/docs/api-docs/trade-websocket/private-stream
# General Info # Connection Endpoints * **Public stream**: `wss://ws.pionex.com/wsPub` (no authentication) * **Private stream**: `wss://ws.pionex.com/ws` (requires authentication) # Authentication (Private Stream) [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private streams require authentication via query parameters: * `key`: Your API Key * `timestamp`: Current time in milliseconds * `signature`: HMAC SHA256 hash for verification #### Signing 1. Obtain the current millisecond timestamp 2. Format key-value pairs for `key` and `timestamp` 3. Sort parameters alphabetically and join with `&` 4. Append sorted parameters to the path: `/ws?` 5. Concatenate the string `websocket_auth` to the path URL 6. Generate HMAC SHA256 using your API Secret and the complete string, convert to hexadecimal 7. Add the resulting signature to query parameters **Example:** Concatenated string for signing: ``` /ws?key=OElNn5D_Frnf5MR0ChjYdG7PunK0AOgHTvevwzWS×tamp=1655896754515websocket_auth ``` Generated signature: ``` 3e901247350e744353f4a7a479fd67181184a627b119352ec1b7a432925e772c ``` Final connection URL: ``` wss://ws.pionex.com/ws?key=OElNn5D_Frnf5MR0ChjYdG7PunK0AOgHTvevwzWS×tamp=1655896754515&signature=3e901247350e744353f4a7a479fd67181184a627b119352ec1b7a432925e772c ``` # Subscribe / Unsubscribe Send JSON message after connection: ```json {"op": "SUBSCRIBE", "topic": "", "symbol": ""} {"op": "UNSUBSCRIBE", "topic": "", "symbol": ""} ``` # Heartbeat * Server sends `{"op": "PING", "timestamp": }` every 15 seconds * Client must reply `{"op": "PONG", "timestamp": }` * Missing 3 consecutive PONGs triggers disconnection # Limits * Maximum 10 concurrent connections per IP # Public Stream Public channels via `wss://ws.pionex.com/wsPub` (no auth required) ## Trade Stream > \*\*Topic\*\*: \`TRADE\`\ > \ > Real-time market trade stream. Up to 100 trade records per message, sorted by timestamp descending.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "TRADE", "symbol": "BTC\_USDT"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "TRADE", "symbol": "BTC\_USDT"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex WebSocket Server"}],"paths":{"/wsPub (trade)":{"get":{"tags":["Public Stream"],"summary":"Trade Stream","operationId":"subscribeTrade","description":"**Topic**: `TRADE`\n\nReal-time market trade stream. Up to 100 trade records per message, sorted by timestamp descending.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"TRADE\", \"symbol\": \"BTC_USDT\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"TRADE\", \"symbol\": \"BTC_USDT\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Trade update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeMessage"}}}}}}}},"components":{"schemas":{"TradeMessage":{"type":"object","description":"Trade stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Up to 100 trade records sorted by timestamp descending","maxItems":100,"items":{"$ref":"#/components/schemas/TradeRecord"}}}},"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}}}}} ```` ## Depth Stream > \*\*Topic\*\*: \`DEPTH\`\ > \ > Real-time order book depth stream.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "DEPTH", "symbol": "BTC\_USDT", "limit": 5}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "DEPTH", "symbol": "BTC\_USDT"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex WebSocket Server"}],"paths":{"/wsPub (depth)":{"get":{"tags":["Public Stream"],"summary":"Depth Stream","operationId":"subscribeDepth","description":"**Topic**: `DEPTH`\n\nReal-time order book depth stream.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"DEPTH\", \"symbol\": \"BTC_USDT\", \"limit\": 5}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"DEPTH\", \"symbol\": \"BTC_USDT\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Depth level limit. Range: 1 - 100. Default: 5","schema":{"type":"integer","minimum":1,"maximum":100,"default":5}}],"responses":{"200":{"description":"Depth update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepthMessage"}}}}}}}},"components":{"schemas":{"DepthMessage":{"type":"object","description":"Depth stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [[price, size], ...] sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [[price, size], ...] sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}}}}}}}}} ```` # Private Stream Private channels via `wss://ws.pionex.com/ws` (auth required) ## Order Stream > \*\*Topic\*\*: \`ORDER\`\ > \ > Real-time order updates. Updates every 250ms when there are changes, every 5000ms when idle.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "ORDER", "symbol": "BTC\_USDT"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "ORDER", "symbol": "BTC\_USDT"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/ws` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex WebSocket Server"}],"paths":{"/ws (order)":{"get":{"tags":["Private Stream"],"summary":"Order Stream","operationId":"subscribeOrder","description":"**Topic**: `ORDER`\n\nReal-time order updates. Updates every 250ms when there are changes, every 5000ms when idle.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"ORDER\", \"symbol\": \"BTC_USDT\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"ORDER\", \"symbol\": \"BTC_USDT\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Order update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderMessage"}}}}}}}},"components":{"schemas":{"OrderMessage":{"type":"object","description":"Order stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/OrderRecord"}}},"OrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"clientOrderId":{"type":"string","description":"Client order ID"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}}}}} ```` ## Fill Stream > \*\*Topic\*\*: \`FILL\`\ > \ > Real-time fill (trade execution) updates across all markets.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "FILL", "symbol": "BTC\_USDT"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "FILL", "symbol": "BTC\_USDT"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/ws` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex WebSocket Server"}],"paths":{"/ws (fill)":{"get":{"tags":["Private Stream"],"summary":"Fill Stream","operationId":"subscribeFill","description":"**Topic**: `FILL`\n\nReal-time fill (trade execution) updates across all markets.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"FILL\", \"symbol\": \"BTC_USDT\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"FILL\", \"symbol\": \"BTC_USDT\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Fill update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FillMessage"}}}}}}}},"components":{"schemas":{"FillMessage":{"type":"object","description":"Fill stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FillRecord"}}},"FillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ```` ## Balance Stream > \*\*Topic\*\*: \`BALANCE\`\ > \ > Real-time account balance updates. No symbol required.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "BALANCE"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "BALANCE"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/ws` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex WebSocket Server"}],"paths":{"/ws (balance)":{"get":{"tags":["Private Stream"],"summary":"Balance Stream","operationId":"subscribeBalance","description":"**Topic**: `BALANCE`\n\nReal-time account balance updates. No symbol required.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"BALANCE\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"BALANCE\"}\n```\n","responses":{"200":{"description":"Balance update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceMessage"}}}}}}}},"components":{"schemas":{"BalanceMessage":{"type":"object","description":"Balance stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"balances":{"type":"array","items":{"$ref":"#/components/schemas/BalanceRecord"}},"timestamp":{"type":"integer","format":"int64","description":"Data timestamp in milliseconds"}}}}},"BalanceRecord":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"}}}}}} ```` # Models ## The TradeMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"TradeMessage":{"type":"object","description":"Trade stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Up to 100 trade records sorted by timestamp descending","maxItems":100,"items":{"$ref":"#/components/schemas/TradeRecord"}}}},"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}}}}} ``` ## The TradeRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}}}}} ``` ## The DepthMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"DepthMessage":{"type":"object","description":"Depth stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [[price, size], ...] sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [[price, size], ...] sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}}}}}}}}} ``` ## The OrderMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"OrderMessage":{"type":"object","description":"Order stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/OrderRecord"}}},"OrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"clientOrderId":{"type":"string","description":"Client order ID"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}}}}} ``` ## The OrderRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"OrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET"],"description":"Order type"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order direction"},"price":{"type":"string","description":"Order price"},"size":{"type":"string","description":"Order quantity"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"IOC":{"type":"boolean","description":"Immediate-or-cancel flag"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status"},"clientOrderId":{"type":"string","description":"Client order ID"},"createTime":{"type":"integer","format":"int64","description":"Create timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update timestamp in milliseconds"}}}}}} ``` ## The FillMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"FillMessage":{"type":"object","description":"Fill stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FillRecord"}}},"FillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ``` ## The FillRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"FillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ``` ## The BalanceMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"BalanceMessage":{"type":"object","description":"Balance stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"balances":{"type":"array","items":{"$ref":"#/components/schemas/BalanceRecord"}},"timestamp":{"type":"integer","format":"int64","description":"Data timestamp in milliseconds"}}}}},"BalanceRecord":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"}}}}}} ``` ## The BalanceRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"BalanceRecord":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"}}}}}} ``` ## The PingMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"PingMessage":{"type":"object","description":"Server heartbeat ping","properties":{"op":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Server timestamp in milliseconds"}}}}}} ``` ## The PongMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex WebSocket API","version":"1.0.0"},"components":{"schemas":{"PongMessage":{"type":"object","description":"Client heartbeat pong response","properties":{"op":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Timestamp from the PING message"}}}}}} ``` # Wallet API REST endpoints for deposits, withdrawals, and wallet balances.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/wallet-api/general-info
## APIs

:square-terminal:

Wallethttps://www.pionex.com/docs/api-docs/wallet-api/wallet
# General Info # Basic Info **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of +/-20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"totalInUsdt": "12345.67", "totalInBtc": "0.18426"}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "PARAMETER_ERROR", "message": "Invalid parameter", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions Each API Key can be configured with **`Trade reading`** permission. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Trade reading` permission:** * `GET /api/v1/balancesFull` — Get full account balances overview # Wallet Account balance query (private) ## Get full account balances overview > Query all account balances overview including Spot (Bot Account) and Futures (Trader Account) dimensions,\ > with price information for each coin and total USDT/BTC valuations. Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"tags":[{"name":"Wallet","description":"Account balance query (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key for authentication. Signature must be provided in PIONEX-SIGNATURE header."}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Request timestamp in milliseconds. Any timestamp older than 20,000 milliseconds or in the future is invalid.","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}},"BalancesFullResponse":{"type":"object","description":"Full account balances overview","properties":{"prices":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/BalancePrice"},"description":"Price information for each coin, keyed by coin symbol (e.g. BTC, ETH)"},"totalInUsdt":{"type":"string","description":"Total USDT valuation across all accounts"},"totalInBtc":{"type":"string","description":"Total BTC valuation across all accounts"},"botAccount":{"$ref":"#/components/schemas/BotAccountBalanceDetail"},"traderAccount":{"$ref":"#/components/schemas/TraderAccountDetail"}}},"BalancePrice":{"type":"object","description":"Coin price information","properties":{"priceInUsd":{"type":"string","description":"Price in USD"},"priceInBtc":{"type":"string","description":"Price in BTC"},"change24hInUsd":{"type":"string","description":"24h price change in USD"},"change24hInBtc":{"type":"string","description":"24h price change in BTC"},"fullName":{"type":"string","description":"Full name of the coin"}}},"BotAccountBalanceDetail":{"type":"object","description":"Bot (Spot) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Bot account"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/BalanceDetail"},"description":"Categorized balance detail list"}}},"BalanceDetail":{"type":"object","description":"Balance category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"list":{"type":"array","items":{"type":"object"},"description":"Balance entries (structure depends on type)"},"hasMore":{"type":"boolean","description":"Whether more data is available"},"count":{"type":"integer","description":"Total number of entries"}}},"TraderAccountDetail":{"type":"object","description":"Trader (Futures) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Trader account"},"title":{"type":"string","description":"Account title"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/FutureDetail"},"description":"Futures account categorized detail"}}},"FutureDetail":{"type":"object","description":"Futures account category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"riskState":{"type":"string","description":"Risk control state"},"balances":{"type":"array","items":{"type":"object"},"description":"Futures balance list"},"positions":{"type":"array","items":{"type":"object"},"description":"Position list"},"quoteRisks":{"type":"array","items":{"type":"object"},"description":"Quote risk list"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid API key or signature","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/wallet/balancesFull":{"get":{"tags":["Wallet"],"summary":"Get full account balances overview","description":"Query all account balances overview including Spot (Bot Account) and Futures (Trader Account) dimensions,\nwith price information for each coin and total USDT/BTC valuations. Weight: 1.\n","operationId":"getBalancesFull","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"appLang","in":"query","required":false,"description":"Application language (takes priority over sysLang)","schema":{"type":"string"}},{"name":"sysLang","in":"query","required":false,"description":"System language (used as fallback when appLang is empty)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BalancesFullResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}}}} ``` ## The BalancesFullResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"BalancesFullResponse":{"type":"object","description":"Full account balances overview","properties":{"prices":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/BalancePrice"},"description":"Price information for each coin, keyed by coin symbol (e.g. BTC, ETH)"},"totalInUsdt":{"type":"string","description":"Total USDT valuation across all accounts"},"totalInBtc":{"type":"string","description":"Total BTC valuation across all accounts"},"botAccount":{"$ref":"#/components/schemas/BotAccountBalanceDetail"},"traderAccount":{"$ref":"#/components/schemas/TraderAccountDetail"}}},"BalancePrice":{"type":"object","description":"Coin price information","properties":{"priceInUsd":{"type":"string","description":"Price in USD"},"priceInBtc":{"type":"string","description":"Price in BTC"},"change24hInUsd":{"type":"string","description":"24h price change in USD"},"change24hInBtc":{"type":"string","description":"24h price change in BTC"},"fullName":{"type":"string","description":"Full name of the coin"}}},"BotAccountBalanceDetail":{"type":"object","description":"Bot (Spot) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Bot account"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/BalanceDetail"},"description":"Categorized balance detail list"}}},"BalanceDetail":{"type":"object","description":"Balance category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"list":{"type":"array","items":{"type":"object"},"description":"Balance entries (structure depends on type)"},"hasMore":{"type":"boolean","description":"Whether more data is available"},"count":{"type":"integer","description":"Total number of entries"}}},"TraderAccountDetail":{"type":"object","description":"Trader (Futures) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Trader account"},"title":{"type":"string","description":"Account title"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/FutureDetail"},"description":"Futures account categorized detail"}}},"FutureDetail":{"type":"object","description":"Futures account category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"riskState":{"type":"string","description":"Risk control state"},"balances":{"type":"array","items":{"type":"object"},"description":"Futures balance list"},"positions":{"type":"array","items":{"type":"object"},"description":"Position list"},"quoteRisks":{"type":"array","items":{"type":"object"},"description":"Quote risk list"}}}}}} ``` ## The BalancePrice object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"BalancePrice":{"type":"object","description":"Coin price information","properties":{"priceInUsd":{"type":"string","description":"Price in USD"},"priceInBtc":{"type":"string","description":"Price in BTC"},"change24hInUsd":{"type":"string","description":"24h price change in USD"},"change24hInBtc":{"type":"string","description":"24h price change in BTC"},"fullName":{"type":"string","description":"Full name of the coin"}}}}}} ``` ## The BotAccountBalanceDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"BotAccountBalanceDetail":{"type":"object","description":"Bot (Spot) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Bot account"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/BalanceDetail"},"description":"Categorized balance detail list"}}},"BalanceDetail":{"type":"object","description":"Balance category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"list":{"type":"array","items":{"type":"object"},"description":"Balance entries (structure depends on type)"},"hasMore":{"type":"boolean","description":"Whether more data is available"},"count":{"type":"integer","description":"Total number of entries"}}}}}} ``` ## The BalanceDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"BalanceDetail":{"type":"object","description":"Balance category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"list":{"type":"array","items":{"type":"object"},"description":"Balance entries (structure depends on type)"},"hasMore":{"type":"boolean","description":"Whether more data is available"},"count":{"type":"integer","description":"Total number of entries"}}}}}} ``` ## The TraderAccountDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"TraderAccountDetail":{"type":"object","description":"Trader (Futures) account balance detail","properties":{"totalInUsdt":{"type":"string","description":"Total USDT valuation of Trader account"},"title":{"type":"string","description":"Account title"},"detail":{"type":"array","items":{"$ref":"#/components/schemas/FutureDetail"},"description":"Futures account categorized detail"}}},"FutureDetail":{"type":"object","description":"Futures account category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"riskState":{"type":"string","description":"Risk control state"},"balances":{"type":"array","items":{"type":"object"},"description":"Futures balance list"},"positions":{"type":"array","items":{"type":"object"},"description":"Position list"},"quoteRisks":{"type":"array","items":{"type":"object"},"description":"Quote risk list"}}}}}} ``` ## The FutureDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Wallet Open API","version":"1.0.0"},"components":{"schemas":{"FutureDetail":{"type":"object","description":"Futures account category detail","properties":{"type":{"type":"string","description":"Category type"},"title":{"type":"string","description":"Category title"},"totalInUsdt":{"type":"string","description":"USDT valuation for this category"},"riskState":{"type":"string","description":"Risk control state"},"balances":{"type":"array","items":{"type":"object"},"description":"Futures balance list"},"positions":{"type":"array","items":{"type":"object"},"description":"Position list"},"quoteRisks":{"type":"array","items":{"type":"object"},"description":"Quote risk list"}}}}}} ``` # Futures API REST endpoints for futures trading: market data, account, positions, orders, and transfers.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/futures-api/general-info
## APIs

:square-terminal:

Commonhttps://www.pionex.com/docs/api-docs/futures-api/common

:square-terminal:

Accounthttps://www.pionex.com/docs/api-docs/futures-api/account

:square-terminal:

Tradehttps://www.pionex.com/docs/api-docs/futures-api/trade

:square-terminal:

Transferhttps://www.pionex.com/docs/api-docs/futures-api/transfer

:square-terminal:

Markethttps://www.pionex.com/docs/api-docs/futures-api/market
# General Info # Basic Info **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of ±20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"orderId": 123456789}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "TRADE_INVALID_SYMBOL", "message": "Invalid symbol", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. * The violating IP or account receives a 60-second ban. * Repeated violations extend the ban duration by 10 seconds per additional request. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. Public endpoints (common information, market data) do not require signing. API Keys must have appropriate permissions assigned before accessing corresponding endpoints. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within ±20 seconds) **Signing Process:** 1. Obtain current timestamp in milliseconds 2. Format query parameters as key-value pairs (no URL encoding for signature values) 3. Sort parameters alphabetically by key and join with `&` (include timestamp) 4. Build PATH\_URL by appending sorted parameters to the request path with `?` 5. Prepend the HTTP METHOD (GET, POST, DELETE) to the PATH\_URL 6. For POST/DELETE requests, append the request body; skip for GET 7. Generate HMAC SHA256 using your API Secret and the concatenated string, convert to hexadecimal The resulting hex signature goes into the request header as `PIONEX-SIGNATURE`. #### API Key Permissions Each API Key can be configured with **Enable reading**, **Enable trading**, and/or **Enable transfer** permissions. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Enable reading` permission:** * `GET /uapi/v1/account/balances` — Get account balances * `GET /uapi/v1/account/positions` — Get current positions * `GET /uapi/v1/account/historyPositions` — Get history positions * `GET /uapi/v1/account/detail` — Get account detail * `GET /uapi/v1/account/leverage` — Get current leverage * `GET /uapi/v1/account/positionMode` — Get position mode * `GET /uapi/v1/trade/isolatedMode` — Get margin mode * `GET /uapi/v1/trade/order` — Get single order * `GET /uapi/v1/trade/orderByClientOrderId` — Get order by client order ID * `GET /uapi/v1/trade/openOrders` — Get open orders * `GET /uapi/v1/trade/historyOrders` — Get history orders * `GET /uapi/v1/trade/fills` — Get fills * `GET /uapi/v1/trade/fillsByOrderId` — Get fills by order ID * `GET /uapi/v1/trade/fundingFee` — Get funding fee records * `GET /api/v1/assets/transfer` — Get single transfer record * `GET /api/v1/assets/transfers` — Get transfer records **Endpoints requiring `Enable trading` permission:** * `POST /uapi/v1/trade/order` — Place order * `DELETE /uapi/v1/trade/order` — Cancel order * `POST /uapi/v1/trade/massOrder` — Batch place orders * `DELETE /uapi/v1/trade/allOrders` — Cancel all orders * `POST /uapi/v1/trade/isolateMargin` — Transfer isolated margin * `POST /uapi/v1/account/leverage` — Update leverage * `POST /uapi/v1/account/positionMode` — Update position mode * `POST /uapi/v1/trade/isolatedMode` — Update margin mode **Endpoints requiring `Enable transfer` permission:** * `POST /api/v1/assets/transfer` — Create transfer # Common Futures common information (public) ## Get futures symbols info > Get all futures trading pair information. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Common","description":"Futures common information (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/common/symbols":{"get":{"tags":["Common"],"summary":"Get futures symbols info","description":"Get all futures trading pair information. Weight: 5.","operationId":"getFuturesSymbols","parameters":[{"name":"symbols","in":"query","description":"Comma-separated symbol list, e.g. BTC_USDT_PERP,ETH_USDT_PERP. When specified, `type` parameter is ignored.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Market type. Defaults to SPOT. Only effective when `symbols` is not specified.","schema":{"type":"string","enum":["SPOT","PERP"]}},{"name":"status","in":"query","description":"Filter by status. Defaults to ALL. Only effective for PERP type.","schema":{"type":"string","enum":["ALL","TRADING","OFFLINE"],"default":"ALL"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbols":{"type":"array","items":{"$ref":"#/components/schemas/FuturesSymbolInfo"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesSymbolInfo":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol identifier (displaySymbol)"},"name":{"type":"string","description":"Futures symbol display name"},"contractType":{"type":"string","description":"Contract type","enum":["PERPETUAL"]},"baseCurrency":{"type":"string","description":"Base asset"},"quoteCurrency":{"type":"string","description":"Quote asset"},"basePrecision":{"type":"integer","description":"Base asset decimal places"},"quotePrecision":{"type":"integer","description":"Quote asset decimal places"},"minNotional":{"type":"string","description":"Minimum notional value"},"baseStep":{"type":"string","description":"Quantity step size (base asset)"},"quoteStep":{"type":"string","description":"Price step size (quote asset)"},"minSizeLimit":{"type":"string","description":"Minimum quantity for limit orders"},"maxSizeLimit":{"type":"string","description":"Maximum quantity for limit orders"},"maxImpactLimit":{"type":"string","description":"Maximum impact price ratio for limit orders"},"minSizeMarket":{"type":"string","description":"Minimum quantity for market orders"},"maxSizeMarket":{"type":"string","description":"Maximum quantity for market orders"},"maxImpactMarket":{"type":"string","description":"Maximum impact price ratio for market orders"},"maxOrderNum":{"type":"integer","description":"Maximum number of orders per user"},"status":{"type":"string","description":"Symbol trading status","enum":["TRADING","OFFLINE"]},"liquidationFeeRate":{"type":"string","description":"Liquidation fee rate"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get risk table > Get risk limit tiers for futures symbols. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Common","description":"Futures common information (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/common/riskTable":{"get":{"tags":["Common"],"summary":"Get risk table","description":"Get risk limit tiers for futures symbols. Weight: 5.","operationId":"getRiskTable","parameters":[{"name":"symbol","in":"query","description":"Futures symbol. Returns all symbols if not specified.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbols":{"type":"array","items":{"$ref":"#/components/schemas/RiskTableEntry"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"RiskTableEntry":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol (displaySymbol)"},"rows":{"type":"array","description":"Risk tier rows","items":{"type":"object","properties":{"rowNum":{"type":"integer","description":"Tier level number"},"notionalLimit":{"type":"string","description":"Maximum notional value for this tier"},"maxLeverage":{"type":"string","description":"Maximum leverage for this tier"},"maintMarginRatio":{"type":"string","description":"Maintenance margin ratio"},"quickDeduction":{"type":"string","description":"Quick deduction amount"}}}}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` # Account Futures account management (private) ## Get account balances > Query futures account asset balances. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"AccountBalance":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance (8 decimal places)"},"frozen":{"type":"string","description":"Frozen balance (8 decimal places)"},"debts":{"type":"string","description":"Debt amount"}}},"IsolatedBalance":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Isolated margin type","enum":["ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"balances":{"type":"array","description":"Isolated margin balances","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/balances":{"get":{"tags":["Account"],"summary":"Get account balances","description":"Query futures account asset balances. Weight: 5.","operationId":"getAccountBalances","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"balances":{"type":"array","description":"Cross margin balance list","items":{"$ref":"#/components/schemas/AccountBalance"}},"isolates":{"type":"array","description":"Isolated margin asset list","items":{"$ref":"#/components/schemas/IsolatedBalance"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get current positions > Query current active positions. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Position":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID"},"symbol":{"type":"string","description":"Futures symbol (displaySymbol)"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"riskState":{"type":"string","description":"Risk state for isolated positions"},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort"},"avgPrice":{"type":"string","description":"Average entry price = abs((amountLong + amountShort + amountSettled) / (sizeLong + sizeShort))"},"unrealizedPnL":{"type":"string","description":"Unrealized PnL = (markPrice - avgPrice) * netSize"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"markPrice":{"type":"string","description":"Mark price"},"initialMargin":{"type":"string","description":"Initial margin requirement"},"maintMargin":{"type":"string","description":"Maintenance margin requirement"},"liquidationPrice":{"type":"string","description":"Estimated liquidation price"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/positions":{"get":{"tags":["Account"],"summary":"Get current positions","description":"Query current active positions. Weight: 5.","operationId":"getPositions","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","description":"Futures symbol. Returns all positions if not specified.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get history positions > Query historical closed or taken-over positions. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"HistoryPosition":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID"},"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"sizeLong":{"type":"string","description":"Cumulative long size"},"sizeShort":{"type":"string","description":"Cumulative short size"},"amountLong":{"type":"string","description":"Cumulative long cost"},"amountShort":{"type":"string","description":"Cumulative short proceeds"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"sizeTakeover":{"type":"string","description":"Taken-over size"},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/historyPositions":{"get":{"tags":["Account"],"summary":"Get history positions","description":"Query historical closed or taken-over positions. Weight: 5.","operationId":"getHistoryPositions","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","description":"Futures symbol","schema":{"type":"string"}},{"name":"positionFlag","in":"query","description":"Position flag filter","schema":{"type":"string","enum":["CLOSED","TAKEOVER"]}},{"name":"startTime","in":"query","description":"Start time filter based on updateTime (milliseconds)","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time filter based on updateTime (milliseconds)","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return","schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"positions":{"type":"array","description":"Positions sorted by close time in descending order","items":{"$ref":"#/components/schemas/HistoryPosition"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get account detail > Query account detail including balances, positions, and risk info. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"AccountDetail":{"type":"object","properties":{"quoteRisks":{"type":"array","description":"Risk data partitioned by quote currency","items":{"type":"object","properties":{"quote":{"type":"string","description":"Quote currency"},"riskState":{"type":"string","description":"Risk state of the partition"}}}},"balances":{"type":"array","description":"Cross margin balance list (excluding zero balances)","items":{"$ref":"#/components/schemas/AccountDetailBalance"}},"positions":{"type":"array","description":"Position list","items":{"$ref":"#/components/schemas/AccountDetailPosition"}}}},"AccountDetailBalance":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"assets":{"type":"string","description":"Total assets = free + frozen"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"transferable":{"type":"string","description":"Funds available for spot trading"},"available":{"type":"string","description":"Available margin"},"unrealizedPnL":{"type":"string","description":"Total unrealized PnL"},"totalInitialMargin":{"type":"string","description":"Total initial margin"},"debts":{"type":"string","description":"Total debt"}}},"AccountDetailPosition":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"positionId":{"type":"string","description":"Position unique identifier"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort + sizeLiquidated"},"avgPrice":{"type":"string","description":"Average entry price"},"unrealizedPnL":{"type":"string","description":"Unrealized PnL = (markPrice - avgPrice) * netSize"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"markPrice":{"type":"string","description":"Mark price"},"initialMargin":{"type":"string","description":"Initial margin (for hedge mode, this covers both long, short, and pending order margin)"},"maintMargin":{"type":"string","description":"Maintenance margin"},"liquidationPrice":{"type":"string","description":"Estimated liquidation price"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"createdTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updatedTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"},"riskState":{"type":"string","description":"Risk state for isolated positions"},"balances":{"type":"array","description":"Isolated margin balances","items":{"type":"object","properties":{"totalInitialMargin":{"type":"string","description":"Isolated initial margin"},"transferable":{"type":"string","description":"Funds available for trading or transfer"},"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/detail":{"get":{"tags":["Account"],"summary":"Get account detail","description":"Query account detail including balances, positions, and risk info. Weight: 5.","operationId":"getAccountDetail","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Transfer isolated margin > Transfer funds in or out of isolated margin for a specific symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/isolateMargin":{"post":{"tags":["Account"],"summary":"Transfer isolated margin","description":"Transfer funds in or out of isolated margin for a specific symbol. Weight: 5.","operationId":"transferIsolateMargin","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","symbol","direction","isolatedMode","coin","amount"],"properties":{"clientId":{"type":"string","description":"Unique client ID per request, used for deduplication. Valid for 8 hours."},"symbol":{"type":"string","description":"Futures symbol"},"direction":{"type":"string","description":"Transfer direction","enum":["IN","OUT"]},"isolatedMode":{"type":"string","description":"Isolated margin mode","enum":["ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"coin":{"type":"string","description":"Currency to transfer (USDT or BTC)","enum":["USDT","BTC"]},"amount":{"type":"string","description":"Transfer amount"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get current leverage > Query current leverage for a specific symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/leverage":{"get":{"tags":["Account"],"summary":"Get current leverage","description":"Query current leverage for a specific symbol. Weight: 5.","operationId":"getLeverage","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"leverage":{"type":"string","description":"Current leverage multiplier"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Update leverage > Modify leverage for a specific symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/leverage":{"post":{"tags":["Account"],"summary":"Update leverage","description":"Modify leverage for a specific symbol. Weight: 5.","operationId":"updateLeverage","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","leverage"],"properties":{"symbol":{"type":"string","description":"Futures symbol"},"leverage":{"type":"string","description":"Leverage multiplier"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"leverage":{"type":"string","description":"Updated leverage multiplier"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get position mode > Query current position mode. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/positionMode":{"get":{"tags":["Account"],"summary":"Get position mode","description":"Query current position mode. Weight: 5.","operationId":"getPositionMode","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Update position mode > Modify position mode. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/account/positionMode":{"post":{"tags":["Account"],"summary":"Update position mode","description":"Modify position mode. Weight: 5.","operationId":"updatePositionMode","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["positionMode"],"properties":{"positionMode":{"type":"string","description":"Position mode: BUYSELL (one-way) or OPENCLOSE (hedge)","enum":["BUYSELL","OPENCLOSE"]}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get margin mode > Query isolated/cross margin mode for a specific symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/isolatedMode":{"get":{"tags":["Account"],"summary":"Get margin mode","description":"Query isolated/cross margin mode for a specific symbol. Weight: 5.","operationId":"getIsolatedMode","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED"]}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Update margin mode > Switch between isolated and cross margin mode for a specific symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Account","description":"Futures account management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/isolatedMode":{"post":{"tags":["Account"],"summary":"Update margin mode","description":"Switch between isolated and cross margin mode for a specific symbol. Weight: 5.","operationId":"updateIsolatedMode","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","isolatedMode"],"properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode: CROSS (default) or ISOLATED","enum":["CROSS","ISOLATED"]}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Trade Futures order trading (private) ## Get single order > Query a single order by order ID. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"positionSide":{"type":"string","description":"Position side","enum":["BOTH","LONG","SHORT"]},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"status":{"type":"string","description":"Order status. OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED. CLOSED includes FILLED/CANCELED/REJECTED.","enum":["OPEN","CLOSED"]},"reduceOnly":{"type":"boolean","description":"Whether this is a reduce-only order. Only applicable in one-way mode (BUYSELL)."},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","description":"Order source","enum":["MANUAL","API","SYSTEM","TRIGGER"]},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/order":{"get":{"tags":["Trade"],"summary":"Get single order","description":"Query a single order by order ID. Weight: 5.","operationId":"getOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"orderId","in":"query","required":true,"description":"Order ID","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Place order > Place a new futures order (async). Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/order":{"post":{"tags":["Trade"],"summary":"Place order","description":"Place a new futures order (async). Weight: 5.","operationId":"placeOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","side","type"],"properties":{"clientOrderId":{"type":"string","description":"Client order ID for deduplication (server validates within 2 hours). Max 64 characters, alphanumeric and hyphen only."},"symbol":{"type":"string","description":"Futures symbol"},"positionSide":{"type":"string","description":"Position side. Required for hedge mode (LONG/SHORT). Defaults to BOTH for one-way mode.","enum":["BOTH","LONG","SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"size":{"type":"string","description":"Order quantity. Required for limit orders."},"price":{"type":"string","description":"Order price. Required for limit orders."},"reduceOnly":{"type":"boolean","description":"Reduce-only flag. Only applicable in one-way mode (BUYSELL). Defaults to false. Must be false in hedge mode (OPENCLOSE).","default":false}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel order > Cancel an existing order (async). Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/order":{"delete":{"tags":["Trade"],"summary":"Cancel order","description":"Cancel an existing order (async). Weight: 5.","operationId":"cancelOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","orderId"],"properties":{"symbol":{"type":"string","description":"Futures symbol"},"orderId":{"type":"integer","format":"int64","description":"Order ID to cancel"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Batch place orders > Place multiple limit orders in a single request (async). Maximum 20 orders per request. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/massOrder":{"post":{"tags":["Trade"],"summary":"Batch place orders","description":"Place multiple limit orders in a single request (async). Maximum 20 orders per request. Weight: 5.","operationId":"batchPlaceOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol","orders"],"properties":{"symbol":{"type":"string","description":"Futures symbol"},"orders":{"type":"array","description":"Limit order list. Maximum 20 orders.","maxItems":20,"items":{"type":"object","required":["side","type"],"properties":{"clientOrderId":{"type":"string","description":"Client order ID for deduplication. Max 64 characters, alphanumeric and hyphen only."},"positionSide":{"type":"string","description":"Position side. Required for hedge mode.","enum":["BOTH","LONG","SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"size":{"type":"string","description":"Order quantity. Required for limit orders."},"price":{"type":"string","description":"Order price. Required for limit orders."},"type":{"type":"string","description":"Order type. Must be LIMIT.","enum":["LIMIT"]},"reduceOnly":{"type":"boolean","description":"Reduce-only flag. Must be false in hedge mode.","default":false}}}}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"clientOrderId":{"type":"string","description":"Client order ID"}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get order by client order ID > Query an order by client order ID. Only orders within a certain time window can be queried. For normal queries, use /v1/trade/order instead. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"positionSide":{"type":"string","description":"Position side","enum":["BOTH","LONG","SHORT"]},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"status":{"type":"string","description":"Order status. OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED. CLOSED includes FILLED/CANCELED/REJECTED.","enum":["OPEN","CLOSED"]},"reduceOnly":{"type":"boolean","description":"Whether this is a reduce-only order. Only applicable in one-way mode (BUYSELL)."},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","description":"Order source","enum":["MANUAL","API","SYSTEM","TRIGGER"]},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/orderByClientOrderId":{"get":{"tags":["Trade"],"summary":"Get order by client order ID","description":"Query an order by client order ID. Only orders within a certain time window can be queried. For normal queries, use /v1/trade/order instead. Weight: 5.","operationId":"getOrderByClientOrderId","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"clientOrderId","in":"query","required":true,"description":"Client order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get open orders > Query currently active (open) orders. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"positionSide":{"type":"string","description":"Position side","enum":["BOTH","LONG","SHORT"]},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"status":{"type":"string","description":"Order status. OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED. CLOSED includes FILLED/CANCELED/REJECTED.","enum":["OPEN","CLOSED"]},"reduceOnly":{"type":"boolean","description":"Whether this is a reduce-only order. Only applicable in one-way mode (BUYSELL)."},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","description":"Order source","enum":["MANUAL","API","SYSTEM","TRIGGER"]},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/openOrders":{"get":{"tags":["Trade"],"summary":"Get open orders","description":"Query currently active (open) orders. Weight: 5.","operationId":"getOpenOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","description":"Futures symbol. Returns all symbols if not specified.","schema":{"type":"string"}},{"name":"endTime","in":"query","description":"End time (exclusive), defaults to current time. Milliseconds.","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-500.","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get history orders > Query historical closed orders. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"positionSide":{"type":"string","description":"Position side","enum":["BOTH","LONG","SHORT"]},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"status":{"type":"string","description":"Order status. OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED. CLOSED includes FILLED/CANCELED/REJECTED.","enum":["OPEN","CLOSED"]},"reduceOnly":{"type":"boolean","description":"Whether this is a reduce-only order. Only applicable in one-way mode (BUYSELL)."},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","description":"Order source","enum":["MANUAL","API","SYSTEM","TRIGGER"]},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/historyOrders":{"get":{"tags":["Trade"],"summary":"Get history orders","description":"Query historical closed orders. Weight: 5.","operationId":"getHistoryOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","description":"Futures symbol","schema":{"type":"string"}},{"name":"startTime","in":"query","description":"Start time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time in milliseconds. Defaults to current time.","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 50, range 1-200.","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get fills > Query trade fill records sorted by time in descending order. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"role":{"type":"string","description":"Fill role","enum":["TAKER","MAKER"]},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Fee amount"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","description":"Fee type. TRADING: trading fee, LIQUIDATION: liquidation fee.","enum":["TRADING","LIQUIDATION"]},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/fills":{"get":{"tags":["Trade"],"summary":"Get fills","description":"Query trade fill records sorted by time in descending order. Weight: 5.","operationId":"getFills","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"startTime","in":"query","description":"Start time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-200.","schema":{"type":"integer","default":100,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"fills":{"type":"array","description":"Fills sorted by time in descending order","items":{"$ref":"#/components/schemas/Fill"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get fills by order ID > Query trade fill records for a specific order sorted by time in descending order. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"role":{"type":"string","description":"Fill role","enum":["TAKER","MAKER"]},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Fee amount"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","description":"Fee type. TRADING: trading fee, LIQUIDATION: liquidation fee.","enum":["TRADING","LIQUIDATION"]},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/fillsByOrderId":{"get":{"tags":["Trade"],"summary":"Get fills by order ID","description":"Query trade fill records for a specific order sorted by time in descending order. Weight: 5.","operationId":"getFillsByOrderId","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"orderId","in":"query","required":true,"description":"Order ID","schema":{"type":"integer","format":"int64"}},{"name":"fromId","in":"query","description":"Starting fill ID","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-200.","schema":{"type":"integer","default":100,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"fills":{"type":"array","description":"Fills sorted by time in descending order","items":{"$ref":"#/components/schemas/Fill"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel all orders > Cancel all open orders for a specific symbol (async). Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/allOrders":{"delete":{"tags":["Trade"],"summary":"Cancel all orders","description":"Cancel all open orders for a specific symbol (async). Weight: 5.","operationId":"cancelAllOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string","description":"Futures symbol"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get funding fee records > Query funding fee payment records sorted by time in descending order. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Trade","description":"Futures order trading (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FundingFeeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode. CROSS for cross margin, ISOLATED for all isolated types.","enum":["CROSS","ISOLATED"]},"fundingFee":{"type":"string","description":"Funding fee amount"},"fundingCoin":{"type":"string","description":"Funding fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Funding fee time in milliseconds"},"fundingRate":{"type":"string","description":"Funding rate used for calculation"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/uapi/v1/trade/fundingFee":{"get":{"tags":["Trade"],"summary":"Get funding fee records","description":"Query funding fee payment records sorted by time in descending order. Weight: 5.","operationId":"getFundingFees","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"symbol","in":"query","description":"Futures symbol","schema":{"type":"string"}},{"name":"startTime","in":"query","description":"Start time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-200.","schema":{"type":"integer","default":100,"minimum":1,"maximum":200}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"fundings":{"type":"array","description":"Funding fee records sorted by time in descending order","items":{"$ref":"#/components/schemas/FundingFeeRecord"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Transfer Fund transfers between accounts (private) ## Get single transfer record > Query a single transfer record by client ID. Requires Read permission. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Transfer","description":"Fund transfers between accounts (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"TransferRecord":{"type":"object","properties":{"transferId":{"type":"string","description":"Transfer ID"},"fromAccount":{"type":"string","description":"Source account","enum":["MAIN","TRADE"]},"toAccount":{"type":"string","description":"Destination account","enum":["MAIN","TRADE"]},"currency":{"type":"string","description":"Currency"},"amount":{"type":"string","description":"Transfer amount"},"clientId":{"type":"string","description":"Client request ID"},"status":{"type":"string","description":"Transfer status","enum":["COMPLETED","PROCESSING","FAILED"]},"reason":{"type":"string","description":"Transfer reason","enum":["USER_MANUAL","OPENAPI"]},"comment":{"type":"string","description":"Remark, limited to 32 characters"},"timestamp":{"type":"integer","format":"int64","description":"Operation time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/assets/transfer":{"get":{"tags":["Transfer"],"summary":"Get single transfer record","description":"Query a single transfer record by client ID. Requires Read permission. Weight: 5.","operationId":"getTransfer","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"clientId","in":"query","description":"Client request ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransferRecord"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Create transfer > Transfer funds between main account and trade account. Requires Transfer permission. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Transfer","description":"Fund transfers between accounts (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/assets/transfer":{"post":{"tags":["Transfer"],"summary":"Create transfer","description":"Transfer funds between main account and trade account. Requires Transfer permission. Weight: 5.","operationId":"createTransfer","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromAccount","toAccount","currency","amount"],"properties":{"fromAccount":{"type":"string","description":"Source account","enum":["MAIN","TRADE"]},"toAccount":{"type":"string","description":"Destination account","enum":["MAIN","TRADE"]},"currency":{"type":"string","description":"Currency to transfer"},"amount":{"type":"string","description":"Transfer amount"},"clientId":{"type":"string","description":"Client request ID, must be unique"},"comment":{"type":"string","description":"Remark, limited to 32 characters"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"transferId":{"type":"string","description":"Transfer ID"},"status":{"type":"string","description":"Transfer status","enum":["COMPLETED","PROCESSING","FAILED"]}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get transfer records > Query transfer record list sorted by time in descending order. Requires Read permission. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Transfer","description":"Fund transfers between accounts (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"TransferRecord":{"type":"object","properties":{"transferId":{"type":"string","description":"Transfer ID"},"fromAccount":{"type":"string","description":"Source account","enum":["MAIN","TRADE"]},"toAccount":{"type":"string","description":"Destination account","enum":["MAIN","TRADE"]},"currency":{"type":"string","description":"Currency"},"amount":{"type":"string","description":"Transfer amount"},"clientId":{"type":"string","description":"Client request ID"},"status":{"type":"string","description":"Transfer status","enum":["COMPLETED","PROCESSING","FAILED"]},"reason":{"type":"string","description":"Transfer reason","enum":["USER_MANUAL","OPENAPI"]},"comment":{"type":"string","description":"Remark, limited to 32 characters"},"timestamp":{"type":"integer","format":"int64","description":"Operation time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/assets/transfers":{"get":{"tags":["Transfer"],"summary":"Get transfer records","description":"Query transfer record list sorted by time in descending order. Requires Read permission. Weight: 5.","operationId":"getTransfers","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"status","in":"query","description":"Filter by transfer status. Defaults to ALL.","schema":{"type":"string","enum":["ALL","COMPLETED","FAILED","PROCESSING"],"default":"ALL"}},{"name":"endTime","in":"query","description":"End time in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 20, range 1-100.","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"records":{"type":"array","description":"Transfer records sorted by time in descending order","items":{"$ref":"#/components/schemas/TransferRecord"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Market Futures market data (public) ## Get recent trades > Query recent market trades. Results are taker-side trades only, sorted in descending order. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/trades":{"get":{"tags":["Market"],"summary":"Get recent trades","description":"Query recent market trades. Results are taker-side trades only, sorted in descending order. Weight: 5.","operationId":"getMarketTrades","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 10-500.","schema":{"type":"integer","default":100,"minimum":10,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"trades":{"type":"array","description":"Recent trades sorted in descending order","items":{"$ref":"#/components/schemas/MarketTrade"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"MarketTrade":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"tradeId":{"type":"string","description":"Trade ID"},"price":{"type":"string","description":"Trade price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","description":"Taker side","enum":["BUY","SELL"]},"timestamp":{"type":"string","description":"Trade time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get klines (candlestick data) > Query candlestick/kline data for a futures symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/klines":{"get":{"tags":["Market"],"summary":"Get klines (candlestick data)","description":"Query candlestick/kline data for a futures symbol. Weight: 5.","operationId":"getMarketKlines","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"interval","in":"query","required":true,"description":"Kline interval. M=minutes, H=hours, D=day, W=week, m=month. Daily and larger intervals start from UTC 00:00. Weekly starts from Monday UTC 00:00. Monthly starts from the 1st UTC 00:00.","schema":{"type":"string","enum":["1M","5M","15M","30M","60M","4H","8H","12H","1D","1W","1m"]}},{"name":"endTime","in":"query","description":"End time in milliseconds. Defaults to current time. Returned klines include this time.","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-500.","schema":{"type":"integer","default":100,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"klines":{"type":"array","description":"Klines sorted by time in descending order","items":{"$ref":"#/components/schemas/Kline"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Kline":{"type":"object","properties":{"time":{"type":"integer","format":"int64","description":"Kline open time in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Trading volume in base currency"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get order book depth > Query order book depth for a futures symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/depth":{"get":{"tags":["Market"],"summary":"Get order book depth","description":"Query order book depth for a futures symbol. Weight: 5.","operationId":"getMarketDepth","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Number of price levels. Default 20, range 1-1000.","schema":{"type":"integer","default":20,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [price, size], sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [price, size], sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get 24hr ticker > Query 24-hour rolling window price change statistics. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/tickers":{"get":{"tags":["Market"],"summary":"Get 24hr ticker","description":"Query 24-hour rolling window price change statistics. Weight: 5.","operationId":"getMarketTickers","parameters":[{"name":"symbol","in":"query","description":"Futures symbol. If specified, `type` is ignored.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Market type. Defaults to SPOT. Only effective when `symbol` is not specified.","schema":{"type":"string","enum":["SPOT","PERP"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tickers":{"type":"array","description":"24hr ticker data sorted by symbol ascending","items":{"$ref":"#/components/schemas/Ticker"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"Ticker":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"time":{"type":"integer","format":"int64","description":"Server time in milliseconds (rounded up to the second)"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Trading volume in base currency"},"amount":{"type":"string","description":"Trading amount (sum of price * quantity)"},"count":{"type":"integer","description":"Number of trades"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get best bid/ask price > Query best bid and ask price for futures symbols. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/bookTicker":{"get":{"tags":["Market"],"summary":"Get best bid/ask price","description":"Query best bid and ask price for futures symbols. Weight: 5.","operationId":"getBookTicker","parameters":[{"name":"symbol","in":"query","description":"Futures symbol. If specified, `type` is ignored.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Market type. Defaults to PERP. Only effective when `symbol` is not specified.","schema":{"type":"string","enum":["SPOT","PERP"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"tickers":{"type":"array","description":"Book tickers sorted by symbol ascending","items":{"$ref":"#/components/schemas/BookTicker"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"BookTicker":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"bidPrice":{"type":"string","description":"Best bid price"},"bidSize":{"type":"string","description":"Best bid quantity"},"askPrice":{"type":"string","description":"Best ask price"},"askSize":{"type":"string","description":"Best ask quantity"},"timestamp":{"type":"integer","format":"int64","description":"Update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get index price klines > Query index price candlestick data for a futures symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/indexKlines":{"get":{"tags":["Market"],"summary":"Get index price klines","description":"Query index price candlestick data for a futures symbol. Weight: 5.","operationId":"getIndexKlines","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol. Only perpetual contracts are supported.","schema":{"type":"string"}},{"name":"interval","in":"query","required":true,"description":"Kline interval. M=minutes, H=hours, D=day, W=week, m=month. Daily and larger intervals start from UTC 00:00.","schema":{"type":"string","enum":["1M","5M","15M","30M","60M","4H","8H","12H","1D","1W","1m"]}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-2000.","schema":{"type":"integer","default":100,"minimum":1,"maximum":2000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"klines":{"type":"array","description":"Index price klines sorted by time in descending order","items":{"$ref":"#/components/schemas/IndexKline"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"IndexKline":{"type":"object","properties":{"time":{"type":"string","description":"Kline open time in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get mark price klines > Query mark price candlestick data for a futures symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/markKlines":{"get":{"tags":["Market"],"summary":"Get mark price klines","description":"Query mark price candlestick data for a futures symbol. Weight: 5.","operationId":"getMarkKlines","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol. Only perpetual contracts are supported.","schema":{"type":"string"}},{"name":"interval","in":"query","required":true,"description":"Kline interval. M=minutes, H=hours, D=day, W=week, m=month. Daily and larger intervals start from UTC 00:00.","schema":{"type":"string","enum":["1M","5M","15M","30M","60M","4H","8H","12H","1D","1W","1m"]}},{"name":"limit","in":"query","description":"Number of results to return. Default 100, range 1-2000.","schema":{"type":"integer","default":100,"minimum":1,"maximum":2000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"klines":{"type":"array","description":"Mark price klines sorted by time in descending order","items":{"$ref":"#/components/schemas/IndexKline"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"IndexKline":{"type":"object","properties":{"time":{"type":"string","description":"Kline open time in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get historical funding rates > Query historical funding rates for a futures symbol. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/fundingRates":{"get":{"tags":["Market"],"summary":"Get historical funding rates","description":"Query historical funding rates for a futures symbol. Weight: 5.","operationId":"getFundingRates","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures symbol. Only perpetual contracts are supported.","schema":{"type":"string"}},{"name":"endTime","in":"query","description":"Query funding rates before this time. Defaults to current time. Milliseconds.","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","description":"Number of results to return. Default 1, range 1-500.","schema":{"type":"integer","default":1,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"rates":{"type":"array","description":"Funding rates sorted by fundingTime in descending order","items":{"type":"object","properties":{"fundingRate":{"type":"string","description":"Funding rate"},"fundingTime":{"type":"integer","format":"int64","description":"Funding time in milliseconds"}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get futures index prices > Query index price, mark price, and next funding rate for futures symbols. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/indexes":{"get":{"tags":["Market"],"summary":"Get futures index prices","description":"Query index price, mark price, and next funding rate for futures symbols. Weight: 5.","operationId":"getIndexes","parameters":[{"name":"symbol","in":"query","description":"Futures symbol. Only perpetual contracts are supported. Returns all if not specified.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"indexes":{"type":"array","description":"Index data sorted by symbol ascending","items":{"$ref":"#/components/schemas/FuturesIndex"}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesIndex":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"indexPrice":{"type":"string","description":"Index price"},"markPrice":{"type":"string","description":"Mark price"},"nextFundingRate":{"type":"string","description":"Estimated next funding rate"},"nextFundingTime":{"type":"integer","format":"int64","description":"Next funding time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` ## Get open interest > Query open interest for all futures symbols. Weight: 5. ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"tags":[{"name":"Market","description":"Futures market data (public)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"paths":{"/api/v1/market/openInterests":{"get":{"tags":["Market"],"summary":"Get open interest","description":"Query open interest for all futures symbols. Weight: 5.","operationId":"getOpenInterests","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"openInterests":{"type":"array","description":"Open interest data sorted by symbol ascending","items":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"openInterest":{"type":"string","description":"Open interest amount"}}}}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ``` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}}}} ``` ## The FuturesSymbolInfo object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"FuturesSymbolInfo":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol identifier (displaySymbol)"},"name":{"type":"string","description":"Futures symbol display name"},"contractType":{"type":"string","description":"Contract type","enum":["PERPETUAL"]},"baseCurrency":{"type":"string","description":"Base asset"},"quoteCurrency":{"type":"string","description":"Quote asset"},"basePrecision":{"type":"integer","description":"Base asset decimal places"},"quotePrecision":{"type":"integer","description":"Quote asset decimal places"},"minNotional":{"type":"string","description":"Minimum notional value"},"baseStep":{"type":"string","description":"Quantity step size (base asset)"},"quoteStep":{"type":"string","description":"Price step size (quote asset)"},"minSizeLimit":{"type":"string","description":"Minimum quantity for limit orders"},"maxSizeLimit":{"type":"string","description":"Maximum quantity for limit orders"},"maxImpactLimit":{"type":"string","description":"Maximum impact price ratio for limit orders"},"minSizeMarket":{"type":"string","description":"Minimum quantity for market orders"},"maxSizeMarket":{"type":"string","description":"Maximum quantity for market orders"},"maxImpactMarket":{"type":"string","description":"Maximum impact price ratio for market orders"},"maxOrderNum":{"type":"integer","description":"Maximum number of orders per user"},"status":{"type":"string","description":"Symbol trading status","enum":["TRADING","OFFLINE"]},"liquidationFeeRate":{"type":"string","description":"Liquidation fee rate"}}}}}} ``` ## The RiskTableEntry object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"RiskTableEntry":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol (displaySymbol)"},"rows":{"type":"array","description":"Risk tier rows","items":{"type":"object","properties":{"rowNum":{"type":"integer","description":"Tier level number"},"notionalLimit":{"type":"string","description":"Maximum notional value for this tier"},"maxLeverage":{"type":"string","description":"Maximum leverage for this tier"},"maintMarginRatio":{"type":"string","description":"Maintenance margin ratio"},"quickDeduction":{"type":"string","description":"Quick deduction amount"}}}}}}}}} ``` ## The AccountBalance object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"AccountBalance":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance (8 decimal places)"},"frozen":{"type":"string","description":"Frozen balance (8 decimal places)"},"debts":{"type":"string","description":"Debt amount"}}}}}} ``` ## The IsolatedBalance object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"IsolatedBalance":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Isolated margin type","enum":["ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"balances":{"type":"array","description":"Isolated margin balances","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}}}}}}} ``` ## The Position object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"Position":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID"},"symbol":{"type":"string","description":"Futures symbol (displaySymbol)"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"riskState":{"type":"string","description":"Risk state for isolated positions"},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort"},"avgPrice":{"type":"string","description":"Average entry price = abs((amountLong + amountShort + amountSettled) / (sizeLong + sizeShort))"},"unrealizedPnL":{"type":"string","description":"Unrealized PnL = (markPrice - avgPrice) * netSize"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"markPrice":{"type":"string","description":"Mark price"},"initialMargin":{"type":"string","description":"Initial margin requirement"},"maintMargin":{"type":"string","description":"Maintenance margin requirement"},"liquidationPrice":{"type":"string","description":"Estimated liquidation price"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The HistoryPosition object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"HistoryPosition":{"type":"object","properties":{"positionId":{"type":"string","description":"Position ID"},"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"sizeLong":{"type":"string","description":"Cumulative long size"},"sizeShort":{"type":"string","description":"Cumulative short size"},"amountLong":{"type":"string","description":"Cumulative long cost"},"amountShort":{"type":"string","description":"Cumulative short proceeds"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"sizeTakeover":{"type":"string","description":"Taken-over size"},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The AccountDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"AccountDetail":{"type":"object","properties":{"quoteRisks":{"type":"array","description":"Risk data partitioned by quote currency","items":{"type":"object","properties":{"quote":{"type":"string","description":"Quote currency"},"riskState":{"type":"string","description":"Risk state of the partition"}}}},"balances":{"type":"array","description":"Cross margin balance list (excluding zero balances)","items":{"$ref":"#/components/schemas/AccountDetailBalance"}},"positions":{"type":"array","description":"Position list","items":{"$ref":"#/components/schemas/AccountDetailPosition"}}}},"AccountDetailBalance":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"assets":{"type":"string","description":"Total assets = free + frozen"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"transferable":{"type":"string","description":"Funds available for spot trading"},"available":{"type":"string","description":"Available margin"},"unrealizedPnL":{"type":"string","description":"Total unrealized PnL"},"totalInitialMargin":{"type":"string","description":"Total initial margin"},"debts":{"type":"string","description":"Total debt"}}},"AccountDetailPosition":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"positionId":{"type":"string","description":"Position unique identifier"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort + sizeLiquidated"},"avgPrice":{"type":"string","description":"Average entry price"},"unrealizedPnL":{"type":"string","description":"Unrealized PnL = (markPrice - avgPrice) * netSize"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"markPrice":{"type":"string","description":"Mark price"},"initialMargin":{"type":"string","description":"Initial margin (for hedge mode, this covers both long, short, and pending order margin)"},"maintMargin":{"type":"string","description":"Maintenance margin"},"liquidationPrice":{"type":"string","description":"Estimated liquidation price"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"createdTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updatedTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"},"riskState":{"type":"string","description":"Risk state for isolated positions"},"balances":{"type":"array","description":"Isolated margin balances","items":{"type":"object","properties":{"totalInitialMargin":{"type":"string","description":"Isolated initial margin"},"transferable":{"type":"string","description":"Funds available for trading or transfer"},"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}}}}}}} ``` ## The AccountDetailBalance object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"AccountDetailBalance":{"type":"object","properties":{"coin":{"type":"string","description":"Currency"},"assets":{"type":"string","description":"Total assets = free + frozen"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"transferable":{"type":"string","description":"Funds available for spot trading"},"available":{"type":"string","description":"Available margin"},"unrealizedPnL":{"type":"string","description":"Total unrealized PnL"},"totalInitialMargin":{"type":"string","description":"Total initial margin"},"debts":{"type":"string","description":"Total debt"}}}}}} ``` ## The AccountDetailPosition object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"AccountDetailPosition":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"positionId":{"type":"string","description":"Position unique identifier"},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"positionSide":{"type":"string","description":"Position direction","enum":["LONG","SHORT"]},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort + sizeLiquidated"},"avgPrice":{"type":"string","description":"Average entry price"},"unrealizedPnL":{"type":"string","description":"Unrealized PnL = (markPrice - avgPrice) * netSize"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"markPrice":{"type":"string","description":"Mark price"},"initialMargin":{"type":"string","description":"Initial margin (for hedge mode, this covers both long, short, and pending order margin)"},"maintMargin":{"type":"string","description":"Maintenance margin"},"liquidationPrice":{"type":"string","description":"Estimated liquidation price"},"leverage":{"type":"string","description":"Leverage multiplier"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"createdTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updatedTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"},"riskState":{"type":"string","description":"Risk state for isolated positions"},"balances":{"type":"array","description":"Isolated margin balances","items":{"type":"object","properties":{"totalInitialMargin":{"type":"string","description":"Isolated initial margin"},"transferable":{"type":"string","description":"Funds available for trading or transfer"},"coin":{"type":"string","description":"Currency"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}}}}}}} ``` ## The Order object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"Order":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"type":{"type":"string","description":"Order type","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"]},"positionMode":{"type":"string","description":"Position mode","enum":["BUYSELL","OPENCLOSE"]},"isolatedMode":{"type":"string","description":"Margin mode","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"]},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"positionSide":{"type":"string","description":"Position side","enum":["BOTH","LONG","SHORT"]},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount"},"status":{"type":"string","description":"Order status. OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED. CLOSED includes FILLED/CANCELED/REJECTED.","enum":["OPEN","CLOSED"]},"reduceOnly":{"type":"boolean","description":"Whether this is a reduce-only order. Only applicable in one-way mode (BUYSELL)."},"clientOrderId":{"type":"string","description":"Client order ID"},"source":{"type":"string","description":"Order source","enum":["MANUAL","API","SYSTEM","TRIGGER"]},"createTime":{"type":"integer","format":"int64","description":"Creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The Fill object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"Fill":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill ID"},"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures symbol"},"side":{"type":"string","description":"Order side","enum":["BUY","SELL"]},"role":{"type":"string","description":"Fill role","enum":["TAKER","MAKER"]},"price":{"type":"string","description":"Fill price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Fee amount"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","description":"Fee type. TRADING: trading fee, LIQUIDATION: liquidation fee.","enum":["TRADING","LIQUIDATION"]},"timestamp":{"type":"integer","format":"int64","description":"Fill time in milliseconds"}}}}}} ``` ## The FundingFeeRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"FundingFeeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"isolatedMode":{"type":"string","description":"Margin mode. CROSS for cross margin, ISOLATED for all isolated types.","enum":["CROSS","ISOLATED"]},"fundingFee":{"type":"string","description":"Funding fee amount"},"fundingCoin":{"type":"string","description":"Funding fee currency"},"timestamp":{"type":"integer","format":"int64","description":"Funding fee time in milliseconds"},"fundingRate":{"type":"string","description":"Funding rate used for calculation"}}}}}} ``` ## The MarketTrade object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"MarketTrade":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"tradeId":{"type":"string","description":"Trade ID"},"price":{"type":"string","description":"Trade price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","description":"Taker side","enum":["BUY","SELL"]},"timestamp":{"type":"string","description":"Trade time in milliseconds"}}}}}} ``` ## The Kline object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"Kline":{"type":"object","properties":{"time":{"type":"integer","format":"int64","description":"Kline open time in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Trading volume in base currency"}}}}}} ``` ## The Ticker object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"Ticker":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"time":{"type":"integer","format":"int64","description":"Server time in milliseconds (rounded up to the second)"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"},"volume":{"type":"string","description":"Trading volume in base currency"},"amount":{"type":"string","description":"Trading amount (sum of price * quantity)"},"count":{"type":"integer","description":"Number of trades"}}}}}} ``` ## The BookTicker object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"BookTicker":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"bidPrice":{"type":"string","description":"Best bid price"},"bidSize":{"type":"string","description":"Best bid quantity"},"askPrice":{"type":"string","description":"Best ask price"},"askSize":{"type":"string","description":"Best ask quantity"},"timestamp":{"type":"integer","format":"int64","description":"Update time in milliseconds"}}}}}} ``` ## The IndexKline object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"IndexKline":{"type":"object","properties":{"time":{"type":"string","description":"Kline open time in milliseconds"},"open":{"type":"string","description":"Open price"},"close":{"type":"string","description":"Close price"},"high":{"type":"string","description":"Highest price"},"low":{"type":"string","description":"Lowest price"}}}}}} ``` ## The FuturesIndex object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"FuturesIndex":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures symbol"},"indexPrice":{"type":"string","description":"Index price"},"markPrice":{"type":"string","description":"Mark price"},"nextFundingRate":{"type":"string","description":"Estimated next funding rate"},"nextFundingTime":{"type":"integer","format":"int64","description":"Next funding time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The TransferRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures Open API","version":"1.0.0"},"components":{"schemas":{"TransferRecord":{"type":"object","properties":{"transferId":{"type":"string","description":"Transfer ID"},"fromAccount":{"type":"string","description":"Source account","enum":["MAIN","TRADE"]},"toAccount":{"type":"string","description":"Destination account","enum":["MAIN","TRADE"]},"currency":{"type":"string","description":"Currency"},"amount":{"type":"string","description":"Transfer amount"},"clientId":{"type":"string","description":"Client request ID"},"status":{"type":"string","description":"Transfer status","enum":["COMPLETED","PROCESSING","FAILED"]},"reason":{"type":"string","description":"Transfer reason","enum":["USER_MANUAL","OPENAPI"]},"comment":{"type":"string","description":"Remark, limited to 32 characters"},"timestamp":{"type":"integer","format":"int64","description":"Operation time in milliseconds"}}}}}} ``` # Futures Websocket WebSocket streams for futures trading: public market data and private account/order updates.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/futures-websocket/general-info
## Streams

:square-terminal:

Public Streamhttps://www.pionex.com/docs/api-docs/futures-websocket/public-stream

:square-terminal:

Private Streamhttps://www.pionex.com/docs/api-docs/futures-websocket/private-stream
# General Info # Connection Endpoints * **Public stream**: `wss://ws.pionex.com/wsPub` (no authentication) * **Private stream**: `wss://ws.pionex.com/wsUA` (requires authentication) # Authentication (Private Stream) [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private futures streams require authentication via message after connection: ```json {"op": "auth", "args": [apiKey, timestamp, signature]} ``` #### Signing 1. Obtain the current millisecond timestamp 2. Concatenate the timestamp with the string `websocket_auth`: `timestamp + "websocket_auth"` 3. Generate HMAC SHA256 using your API Secret and the concatenated string 4. Convert the signature to hexadecimal 5. Send auth message with \[apiKey, timestamp, signature] as args **Example:** Concatenated string for signing: ``` 1655896754515websocket_auth ``` Generated signature: ``` 3e901247350e744353f4a7a479fd67181184a627b119352ec1b7a432925e772c ``` Auth message: ```json {"op": "auth", "args": ["OElNn5D_Frnf5MR0ChjYdG7PunK0AOgHTvevwzWS", 1655896754515, "3e901247350e744353f4a7a479fd67181184a627b119352ec1b7a432925e772c"]} ``` # Subscribe / Unsubscribe Send JSON message after connection (and after authentication for private stream): ```json {"op": "SUBSCRIBE", "topic": "", "symbol": ""} {"op": "UNSUBSCRIBE", "topic": "", "symbol": ""} ``` Success response: ```json {"type": "SUBSCRIBED", "topic": "", "symbol": ""} {"type": "UNSUBSCRIBED", "topic": "", "symbol": ""} ``` # Heartbeat * Server sends `{"op": "PING", "timestamp": }` every 15 seconds * Client must reply `{"op": "PONG", "timestamp": }` * Missing 3 consecutive PONGs triggers disconnection # Limits * Maximum 5 messages per second per connection * Maximum 10 concurrent connections per IP * Single connection can subscribe to multiple data streams # Public Stream Public channels via `wss://ws.pionex.com/wsPub` (no auth required) ## Trade Stream > \*\*Topic\*\*: \`TRADE\`\ > \ > Real-time market trade stream for futures symbols. Only TAKER side trades are pushed.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "TRADE", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "TRADE", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsPub (trade)":{"get":{"tags":["Public Stream"],"summary":"Trade Stream","operationId":"subscribeTrade","description":"**Topic**: `TRADE`\n\nReal-time market trade stream for futures symbols. Only TAKER side trades are pushed.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"TRADE\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"TRADE\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Trade update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeMessage"}}}}}}}},"components":{"schemas":{"TradeMessage":{"type":"object","description":"Trade stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Trade records","items":{"$ref":"#/components/schemas/TradeRecord"}}}},"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"type":{"type":"string","enum":["NORMAL"],"description":"Trade type (currently only NORMAL for regular trades)"},"timestamp":{"type":"integer","format":"int64","description":"Trade time in milliseconds"}}}}}} ```` ## Depth Stream > \*\*Topic\*\*: \`DEPTH\`\ > \ > Real-time order book depth stream. Updates every 250ms (if changes) to 5s (if no changes).\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "DEPTH", "symbol": "BTC\_USDT\_PERP", "limit": 5}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "DEPTH", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsPub (depth)":{"get":{"tags":["Public Stream"],"summary":"Depth Stream","operationId":"subscribeDepth","description":"**Topic**: `DEPTH`\n\nReal-time order book depth stream. Updates every 250ms (if changes) to 5s (if no changes).\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"DEPTH\", \"symbol\": \"BTC_USDT_PERP\", \"limit\": 5}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"DEPTH\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Depth level limit. Range: 1 - 100. Default: 5","schema":{"type":"integer","minimum":1,"maximum":100,"default":5}}],"responses":{"200":{"description":"Depth update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepthMessage"}}}}}}}},"components":{"schemas":{"DepthMessage":{"type":"object","description":"Depth stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [[price, size], ...] sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [[price, size], ...] sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}}}}}}}}} ```` ## Order Book Stream (Incremental) > \*\*Topic\*\*: \`ORDERBOOK\`\ > \ > Real-time incremental order book updates. Maintains 100 price levels.\ > \ > \*\*Initial Response\*\*: Full snapshot with 100 levels\ > \*\*Subsequent Updates\*\*: Incremental changes only (50ms aggregation)\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "ORDERBOOK", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "ORDERBOOK", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > \*\*Update Logic\*\*:\ > \- \`action: "SNAPSHOT"\` - Initial full order book (100 levels)\ > \- \`action: "UPDATE"\` - Incremental changes (aggregated over 50ms)\ > \- \`size: "0"\` means the price level was removed\ > \- \`number\` and \`prevNumber\` provide sequence tracking for consistency\ > \- Order book always maintains 100 levels: when a level is consumed, the 101st level becomes the new 100th
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsPub (orderbook)":{"get":{"tags":["Public Stream"],"summary":"Order Book Stream (Incremental)","operationId":"subscribeOrderBook","description":"**Topic**: `ORDERBOOK`\n\nReal-time incremental order book updates. Maintains 100 price levels.\n\n**Initial Response**: Full snapshot with 100 levels\n**Subsequent Updates**: Incremental changes only (50ms aggregation)\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"ORDERBOOK\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"ORDERBOOK\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\n**Update Logic**:\n- `action: \"SNAPSHOT\"` - Initial full order book (100 levels)\n- `action: \"UPDATE\"` - Incremental changes (aggregated over 50ms)\n- `size: \"0\"` means the price level was removed\n- `number` and `prevNumber` provide sequence tracking for consistency\n- Order book always maintains 100 levels: when a level is consumed, the 101st level becomes the new 100th\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol (only futures symbols supported)","schema":{"type":"string"}}],"responses":{"200":{"description":"Order book update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderBookMessage"}}}}}}}},"components":{"schemas":{"OrderBookMessage":{"type":"object","description":"Incremental order book message (100 levels)","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"action":{"type":"string","enum":["SNAPSHOT","UPDATE"],"description":"SNAPSHOT for initial full book, UPDATE for incremental changes"},"bids":{"type":"array","description":"Bid updates [[price, size], ...]. size='0' means level removed.","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask updates [[price, size], ...]. size='0' means level removed.","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"number":{"type":"integer","format":"int64","description":"Sequence number of this update"},"prevNumber":{"type":"integer","format":"int64","description":"Sequence number of previous update (for consistency check)"},"timeStamp":{"type":"integer","format":"int64","description":"Order book update timestamp in milliseconds"}}}}}}}} ```` ## Index Price Stream > \*\*Topic\*\*: \`INDEX\`\ > \ > Real-time index price, mark price, and funding rate information for futures symbols.\ > \ > \*\*Subscribe\*\*:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "INDEX", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "INDEX", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Public Stream","description":"Public channels via `wss://ws.pionex.com/wsPub` (no auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsPub (index)":{"get":{"tags":["Public Stream"],"summary":"Index Price Stream","operationId":"subscribeIndex","description":"**Topic**: `INDEX`\n\nReal-time index price, mark price, and funding rate information for futures symbols.\n\n**Subscribe**:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"INDEX\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"INDEX\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol","schema":{"type":"string"}}],"responses":{"200":{"description":"Index price update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexMessage"}}}}}}}},"components":{"schemas":{"IndexMessage":{"type":"object","description":"Index price stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Index price data","items":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures trading pair symbol"},"indexPrice":{"type":"string","description":"Index price"},"markPrice":{"type":"string","description":"Mark price (used for liquidation calculation)"},"nextFundingRate":{"type":"string","description":"Estimated next funding rate"},"nextFundingTime":{"type":"integer","format":"int64","description":"Next funding time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update time in milliseconds"}}}}}}}}} ```` # Private Stream Private channels via `wss://ws.pionex.com/wsUA` (auth required) ## Order Stream > \*\*Topic\*\*: \`ORDER\`\ > \ > Real-time futures order updates. Pushes when order state changes.\ > \ > \*\*Subscribe\*\* (after authentication):\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "ORDER", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > Or subscribe to all symbols:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "ORDER", "symbol": "ALL"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "ORDER", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/wsUA` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsUA (order)":{"get":{"tags":["Private Stream"],"summary":"Order Stream","operationId":"subscribeOrder","description":"**Topic**: `ORDER`\n\nReal-time futures order updates. Pushes when order state changes.\n\n**Subscribe** (after authentication):\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"ORDER\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\nOr subscribe to all symbols:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"ORDER\", \"symbol\": \"ALL\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"ORDER\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol, or 'ALL' for all symbols","schema":{"type":"string"}}],"responses":{"200":{"description":"Order update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesOrderMessage"}}}}}}}},"components":{"schemas":{"FuturesOrderMessage":{"type":"object","description":"Futures order stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesOrderRecord"}}},"FuturesOrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"],"description":"Order type"},"positionMode":{"type":"string","enum":["BUYSELL","OPENCLOSE"],"description":"Position mode (one-way or hedge mode)"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order side"},"positionSide":{"type":"string","enum":["BOTH","LONG","SHORT"],"description":"Position side (BOTH for one-way mode, LONG/SHORT for hedge mode)"},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount (for MARKET_AMT orders)"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount (quote currency)"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status (OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED, CLOSED includes FILLED/CANCELED/REJECTED)"},"reduceOnly":{"type":"boolean","description":"Whether this order only reduces position (does not increase)"},"clientOrderId":{"type":"string","description":"Client order ID for deduplication"},"source":{"type":"string","enum":["MANUAL","API","SYSTEM","TRIGGER"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Order creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ```` ## Fill Stream > \*\*Topic\*\*: \`FILL\`\ > \ > Real-time fill (trade execution) updates for futures orders.\ > \ > \*\*Subscribe\*\* (after authentication):\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "FILL", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > Or subscribe to all symbols:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "FILL", "symbol": "ALL"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "FILL", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/wsUA` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsUA (fill)":{"get":{"tags":["Private Stream"],"summary":"Fill Stream","operationId":"subscribeFill","description":"**Topic**: `FILL`\n\nReal-time fill (trade execution) updates for futures orders.\n\n**Subscribe** (after authentication):\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"FILL\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\nOr subscribe to all symbols:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"FILL\", \"symbol\": \"ALL\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"FILL\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol, or 'ALL' for all symbols","schema":{"type":"string"}}],"responses":{"200":{"description":"Fill update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesFillMessage"}}}}}}}},"components":{"schemas":{"FuturesFillMessage":{"type":"object","description":"Futures fill stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesFillRecord"}}},"FuturesFillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","enum":["TRADING","LIQUIDATION"],"description":"Fee type (TRADING for normal trade fee, LIQUIDATION for liquidation fee)"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ```` ## Balance Stream > \*\*Topic\*\*: \`BALANCE\`\ > \ > Real-time account balance updates for futures account. Pushes when balance changes (order, fill, funding, transfer, etc.).\ > \ > Updates are aggregated within 100ms and only push when actual changes occur.\ > \ > \*\*Two message types\*\* (discriminated by \`type\` field):\ > \- \*\*CROSS\*\*: Cross margin account balance\ > \- \*\*ISOLATE\_LONG / ISOLATE\_SHORT / ISOLATE\_BOTH\*\*: Isolated margin position balance\ > \ > \*\*Subscribe\*\* (after authentication):\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "BALANCE"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "BALANCE"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/wsUA` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsUA (balance)":{"get":{"tags":["Private Stream"],"summary":"Balance Stream","operationId":"subscribeBalance","description":"**Topic**: `BALANCE`\n\nReal-time account balance updates for futures account. Pushes when balance changes (order, fill, funding, transfer, etc.).\n\nUpdates are aggregated within 100ms and only push when actual changes occur.\n\n**Two message types** (discriminated by `type` field):\n- **CROSS**: Cross margin account balance\n- **ISOLATE_LONG / ISOLATE_SHORT / ISOLATE_BOTH**: Isolated margin position balance\n\n**Subscribe** (after authentication):\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"BALANCE\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"BALANCE\"}\n```\n","responses":{"200":{"description":"Balance update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesBalanceMessage"}}}}}}}},"components":{"schemas":{"FuturesBalanceMessage":{"type":"object","description":"Futures balance stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"oneOf":[{"$ref":"#/components/schemas/CrossBalanceData"},{"$ref":"#/components/schemas/IsolateBalanceData"}],"discriminator":{"propertyName":"type","mapping":{"CROSS":"#/components/schemas/CrossBalanceData","ISOLATE_LONG":"#/components/schemas/IsolateBalanceData","ISOLATE_SHORT":"#/components/schemas/IsolateBalanceData","ISOLATE_BOTH":"#/components/schemas/IsolateBalanceData"}}}}},"CrossBalanceData":{"type":"object","description":"Cross margin account balance data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Balance type indicator"},"balances":{"type":"array","description":"Balance list for all currencies","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}},"IsolateBalanceData":{"type":"object","description":"Isolated margin position balance data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"balances":{"type":"array","description":"Balance list for this isolated position","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}}}}} ```` ## Risk State Stream > \*\*Topic\*\*: \`RISK\`\ > \ > Real-time risk state monitoring for futures account and positions.\ > \ > \*\*Two message types\*\* (discriminated by \`type\` field):\ > \- \*\*CROSS\*\*: Cross margin account risk state\ > \- \*\*ISOLATE\_LONG / ISOLATE\_SHORT / ISOLATE\_BOTH\*\*: Isolated margin position risk state\ > \ > \*\*Push frequency\*\*:\ > \- Non-TRADING state: every 10 seconds\ > \- TRADING state: every 15 minutes\ > \- State changes: immediate push\ > \ > \*\*Subscribe\*\* (after authentication):\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "RISK"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "RISK"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/wsUA` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsUA (risk)":{"get":{"tags":["Private Stream"],"summary":"Risk State Stream","operationId":"subscribeRisk","description":"**Topic**: `RISK`\n\nReal-time risk state monitoring for futures account and positions.\n\n**Two message types** (discriminated by `type` field):\n- **CROSS**: Cross margin account risk state\n- **ISOLATE_LONG / ISOLATE_SHORT / ISOLATE_BOTH**: Isolated margin position risk state\n\n**Push frequency**:\n- Non-TRADING state: every 10 seconds\n- TRADING state: every 15 minutes\n- State changes: immediate push\n\n**Subscribe** (after authentication):\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"RISK\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"RISK\"}\n```\n","responses":{"200":{"description":"Risk state update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesRiskMessage"}}}}}}}},"components":{"schemas":{"FuturesRiskMessage":{"type":"object","description":"Futures risk state stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"oneOf":[{"$ref":"#/components/schemas/CrossRiskData"},{"$ref":"#/components/schemas/IsolateRiskData"}],"discriminator":{"propertyName":"type","mapping":{"CROSS":"#/components/schemas/CrossRiskData","ISOLATE_LONG":"#/components/schemas/IsolateRiskData","ISOLATE_SHORT":"#/components/schemas/IsolateRiskData","ISOLATE_BOTH":"#/components/schemas/IsolateRiskData"}}}}},"CrossRiskData":{"type":"object","description":"Cross margin account risk data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Risk type indicator"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Account equity"},"totalMaintMargin":{"type":"string","description":"Total maintenance margin requirement"}}}}},"IsolateRiskData":{"type":"object","description":"Isolated margin position risk data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Position equity"},"totalMaintMargin":{"type":"string","description":"Maintenance margin requirement"}}}}}}}} ```` ## Position Stream > \*\*Topic\*\*: \`POSITION\`\ > \ > Real-time position updates for futures trading. Pushes when position changes.\ > \ > \*\*Subscribe\*\* (after authentication):\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "POSITION", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`\ > \ > Or subscribe to all symbols:\ > \`\`\`json\ > {"op": "SUBSCRIBE", "topic": "POSITION", "symbol": "ALL"}\ > \`\`\`\ > \ > \*\*Unsubscribe\*\*:\ > \`\`\`json\ > {"op": "UNSUBSCRIBE", "topic": "POSITION", "symbol": "BTC\_USDT\_PERP"}\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"tags":[{"name":"Private Stream","description":"Private channels via `wss://ws.pionex.com/wsUA` (auth required)"}],"servers":[{"url":"wss://ws.pionex.com","description":"Pionex Futures WebSocket Server"}],"paths":{"/wsUA (position)":{"get":{"tags":["Private Stream"],"summary":"Position Stream","operationId":"subscribePosition","description":"**Topic**: `POSITION`\n\nReal-time position updates for futures trading. Pushes when position changes.\n\n**Subscribe** (after authentication):\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"POSITION\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n\nOr subscribe to all symbols:\n```json\n{\"op\": \"SUBSCRIBE\", \"topic\": \"POSITION\", \"symbol\": \"ALL\"}\n```\n\n**Unsubscribe**:\n```json\n{\"op\": \"UNSUBSCRIBE\", \"topic\": \"POSITION\", \"symbol\": \"BTC_USDT_PERP\"}\n```\n","parameters":[{"name":"symbol","in":"query","required":true,"description":"Futures trading pair symbol, or 'ALL' for all symbols","schema":{"type":"string"}}],"responses":{"200":{"description":"Position update message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesPositionMessage"}}}}}}}},"components":{"schemas":{"FuturesPositionMessage":{"type":"object","description":"Futures position stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesPositionRecord"}}},"FuturesPositionRecord":{"type":"object","properties":{"positionId":{"type":"string","description":"Position unique identifier"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"positionSide":{"type":"string","enum":["LONG","SHORT"],"description":"Position direction"},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort"},"avgPrice":{"type":"string","description":"Average entry price = abs((amountLong + amountShort + amountSettled) / (sizeLong + sizeShort))"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"sizeTakeover":{"type":"string","description":"Takeover size (in cases where position was taken over by system)"},"createTime":{"type":"integer","format":"int64","description":"Position creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ```` # Models ## The TradeMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"TradeMessage":{"type":"object","description":"Trade stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Trade records","items":{"$ref":"#/components/schemas/TradeRecord"}}}},"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"type":{"type":"string","enum":["NORMAL"],"description":"Trade type (currently only NORMAL for regular trades)"},"timestamp":{"type":"integer","format":"int64","description":"Trade time in milliseconds"}}}}}} ``` ## The TradeRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"TradeRecord":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures trading pair symbol"},"tradeId":{"type":"string","description":"Unique trade identifier"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Trade quantity"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Liquidity taker's direction"},"type":{"type":"string","enum":["NORMAL"],"description":"Trade type (currently only NORMAL for regular trades)"},"timestamp":{"type":"integer","format":"int64","description":"Trade time in milliseconds"}}}}}} ``` ## The DepthMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"DepthMessage":{"type":"object","description":"Depth stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"bids":{"type":"array","description":"Bid orders [[price, size], ...] sorted by price descending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask orders [[price, size], ...] sorted by price ascending","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}}}}}}}}} ``` ## The OrderBookMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"OrderBookMessage":{"type":"object","description":"Incremental order book message (100 levels)","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"object","properties":{"action":{"type":"string","enum":["SNAPSHOT","UPDATE"],"description":"SNAPSHOT for initial full book, UPDATE for incremental changes"},"bids":{"type":"array","description":"Bid updates [[price, size], ...]. size='0' means level removed.","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"asks":{"type":"array","description":"Ask updates [[price, size], ...]. size='0' means level removed.","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"number":{"type":"integer","format":"int64","description":"Sequence number of this update"},"prevNumber":{"type":"integer","format":"int64","description":"Sequence number of previous update (for consistency check)"},"timeStamp":{"type":"integer","format":"int64","description":"Order book update timestamp in milliseconds"}}}}}}}} ``` ## The IndexMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"IndexMessage":{"type":"object","description":"Index price stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"type":"array","description":"Index price data","items":{"type":"object","properties":{"symbol":{"type":"string","description":"Futures trading pair symbol"},"indexPrice":{"type":"string","description":"Index price"},"markPrice":{"type":"string","description":"Mark price (used for liquidation calculation)"},"nextFundingRate":{"type":"string","description":"Estimated next funding rate"},"nextFundingTime":{"type":"integer","format":"int64","description":"Next funding time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Update time in milliseconds"}}}}}}}}} ``` ## The FuturesOrderMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesOrderMessage":{"type":"object","description":"Futures order stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesOrderRecord"}}},"FuturesOrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"],"description":"Order type"},"positionMode":{"type":"string","enum":["BUYSELL","OPENCLOSE"],"description":"Position mode (one-way or hedge mode)"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order side"},"positionSide":{"type":"string","enum":["BOTH","LONG","SHORT"],"description":"Position side (BOTH for one-way mode, LONG/SHORT for hedge mode)"},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount (for MARKET_AMT orders)"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount (quote currency)"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status (OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED, CLOSED includes FILLED/CANCELED/REJECTED)"},"reduceOnly":{"type":"boolean","description":"Whether this order only reduces position (does not increase)"},"clientOrderId":{"type":"string","description":"Client order ID for deduplication"},"source":{"type":"string","enum":["MANUAL","API","SYSTEM","TRIGGER"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Order creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The FuturesOrderRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesOrderRecord":{"type":"object","properties":{"orderId":{"type":"integer","format":"int64","description":"Order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"type":{"type":"string","enum":["LIMIT","MARKET_QTY","IOC","FOK","POSTONLY"],"description":"Order type"},"positionMode":{"type":"string","enum":["BUYSELL","OPENCLOSE"],"description":"Position mode (one-way or hedge mode)"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Order side"},"positionSide":{"type":"string","enum":["BOTH","LONG","SHORT"],"description":"Position side (BOTH for one-way mode, LONG/SHORT for hedge mode)"},"price":{"type":"string","description":"Order price"},"origSize":{"type":"string","description":"Original order quantity as submitted by user"},"size":{"type":"string","description":"Actual order quantity (may be trimmed for reduce-only orders)"},"amount":{"type":"string","description":"Market buy order amount (for MARKET_AMT orders)"},"filledSize":{"type":"string","description":"Filled quantity"},"filledAmount":{"type":"string","description":"Filled amount (quote currency)"},"status":{"type":"string","enum":["OPEN","CLOSED"],"description":"Order status (OPEN includes SUBMITTED/CONFIRMED/PARTIAL_FILLED, CLOSED includes FILLED/CANCELED/REJECTED)"},"reduceOnly":{"type":"boolean","description":"Whether this order only reduces position (does not increase)"},"clientOrderId":{"type":"string","description":"Client order ID for deduplication"},"source":{"type":"string","enum":["MANUAL","API","SYSTEM","TRIGGER"],"description":"Order source"},"createTime":{"type":"integer","format":"int64","description":"Order creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The FuturesFillMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesFillMessage":{"type":"object","description":"Futures fill stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesFillRecord"}}},"FuturesFillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","enum":["TRADING","LIQUIDATION"],"description":"Fee type (TRADING for normal trade fee, LIQUIDATION for liquidation fee)"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ``` ## The FuturesFillRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesFillRecord":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"Fill record ID"},"orderId":{"type":"integer","format":"int64","description":"Associated order ID"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"side":{"type":"string","enum":["BUY","SELL"],"description":"Trade direction"},"role":{"type":"string","enum":["TAKER","MAKER"],"description":"Participant role"},"price":{"type":"string","description":"Execution price"},"size":{"type":"string","description":"Fill quantity"},"fee":{"type":"string","description":"Transaction fee"},"feeCoin":{"type":"string","description":"Fee currency"},"feeType":{"type":"string","enum":["TRADING","LIQUIDATION"],"description":"Fee type (TRADING for normal trade fee, LIQUIDATION for liquidation fee)"},"timestamp":{"type":"integer","format":"int64","description":"Fill timestamp in milliseconds"}}}}}} ``` ## The FuturesBalanceMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesBalanceMessage":{"type":"object","description":"Futures balance stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"oneOf":[{"$ref":"#/components/schemas/CrossBalanceData"},{"$ref":"#/components/schemas/IsolateBalanceData"}],"discriminator":{"propertyName":"type","mapping":{"CROSS":"#/components/schemas/CrossBalanceData","ISOLATE_LONG":"#/components/schemas/IsolateBalanceData","ISOLATE_SHORT":"#/components/schemas/IsolateBalanceData","ISOLATE_BOTH":"#/components/schemas/IsolateBalanceData"}}}}},"CrossBalanceData":{"type":"object","description":"Cross margin account balance data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Balance type indicator"},"balances":{"type":"array","description":"Balance list for all currencies","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}},"IsolateBalanceData":{"type":"object","description":"Isolated margin position balance data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"balances":{"type":"array","description":"Balance list for this isolated position","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}}}}} ``` ## The CrossBalanceData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"CrossBalanceData":{"type":"object","description":"Cross margin account balance data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Balance type indicator"},"balances":{"type":"array","description":"Balance list for all currencies","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}}}}} ``` ## The IsolateBalanceData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"IsolateBalanceData":{"type":"object","description":"Isolated margin position balance data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"balances":{"type":"array","description":"Balance list for this isolated position","items":{"type":"object","properties":{"coin":{"type":"string","description":"Currency code"},"free":{"type":"string","description":"Available balance"},"frozen":{"type":"string","description":"Frozen balance"},"debts":{"type":"string","description":"Debt amount"}}}},"timestamp":{"type":"integer","format":"int64","description":"Balance update timestamp in milliseconds"}}}}}} ``` ## The FuturesRiskMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesRiskMessage":{"type":"object","description":"Futures risk state stream message","properties":{"topic":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"oneOf":[{"$ref":"#/components/schemas/CrossRiskData"},{"$ref":"#/components/schemas/IsolateRiskData"}],"discriminator":{"propertyName":"type","mapping":{"CROSS":"#/components/schemas/CrossRiskData","ISOLATE_LONG":"#/components/schemas/IsolateRiskData","ISOLATE_SHORT":"#/components/schemas/IsolateRiskData","ISOLATE_BOTH":"#/components/schemas/IsolateRiskData"}}}}},"CrossRiskData":{"type":"object","description":"Cross margin account risk data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Risk type indicator"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Account equity"},"totalMaintMargin":{"type":"string","description":"Total maintenance margin requirement"}}}}},"IsolateRiskData":{"type":"object","description":"Isolated margin position risk data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Position equity"},"totalMaintMargin":{"type":"string","description":"Maintenance margin requirement"}}}}}}}} ``` ## The CrossRiskData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"CrossRiskData":{"type":"object","description":"Cross margin account risk data","properties":{"type":{"type":"string","enum":["CROSS"],"description":"Risk type indicator"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Account equity"},"totalMaintMargin":{"type":"string","description":"Total maintenance margin requirement"}}}}}}}} ``` ## The IsolateRiskData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"IsolateRiskData":{"type":"object","description":"Isolated margin position risk data","properties":{"type":{"type":"string","enum":["ISOLATE_LONG","ISOLATE_SHORT","ISOLATE_BOTH"],"description":"Isolated margin type"},"symbol":{"type":"string","description":"Futures trading pair symbol for the isolated position"},"riskState":{"type":"string","description":"Risk state: TRADING, HOLDING, MERGING, LIQUIDATING, TAKEOVER"},"quote":{"type":"string","description":"Quote currency"},"updatedTime":{"type":"integer","format":"int64","description":"Risk state update time in milliseconds"},"extraInfo":{"type":"object","description":"Additional risk information","properties":{"accountEquity":{"type":"string","description":"Position equity"},"totalMaintMargin":{"type":"string","description":"Maintenance margin requirement"}}}}}}}} ``` ## The FuturesPositionMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesPositionMessage":{"type":"object","description":"Futures position stream message","properties":{"topic":{"type":"string"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"timestamp":{"type":"integer","format":"int64","description":"Message timestamp in milliseconds"},"data":{"$ref":"#/components/schemas/FuturesPositionRecord"}}},"FuturesPositionRecord":{"type":"object","properties":{"positionId":{"type":"string","description":"Position unique identifier"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"positionSide":{"type":"string","enum":["LONG","SHORT"],"description":"Position direction"},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort"},"avgPrice":{"type":"string","description":"Average entry price = abs((amountLong + amountShort + amountSettled) / (sizeLong + sizeShort))"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"sizeTakeover":{"type":"string","description":"Takeover size (in cases where position was taken over by system)"},"createTime":{"type":"integer","format":"int64","description":"Position creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The FuturesPositionRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"FuturesPositionRecord":{"type":"object","properties":{"positionId":{"type":"string","description":"Position unique identifier"},"symbol":{"type":"string","description":"Futures trading pair symbol"},"isolatedMode":{"type":"string","enum":["CROSS","ISOLATED_BOTH","ISOLATED_LONG","ISOLATED_SHORT"],"description":"Margin mode"},"positionSide":{"type":"string","enum":["LONG","SHORT"],"description":"Position direction"},"netSize":{"type":"string","description":"Net position size = sizeLong + sizeShort"},"avgPrice":{"type":"string","description":"Average entry price = abs((amountLong + amountShort + amountSettled) / (sizeLong + sizeShort))"},"sizeLong":{"type":"string","description":"Cumulative long size (positive)"},"sizeShort":{"type":"string","description":"Cumulative short size (negative)"},"amountLong":{"type":"string","description":"Cumulative long cost (negative)"},"amountShort":{"type":"string","description":"Cumulative short proceeds (positive)"},"amountSettled":{"type":"string","description":"Cumulative settled amount"},"sizeLiquidated":{"type":"string","description":"Cumulative liquidated size (negative for long, positive for short)"},"amountLiquidated":{"type":"string","description":"Cumulative liquidated amount (positive for long, negative for short)"},"sizeTakeover":{"type":"string","description":"Takeover size (in cases where position was taken over by system)"},"createTime":{"type":"integer","format":"int64","description":"Position creation time in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update time in milliseconds"}}}}}} ``` ## The PingMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"PingMessage":{"type":"object","description":"Server heartbeat ping","properties":{"op":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Server timestamp in milliseconds"}}}}}} ``` ## The PongMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"PongMessage":{"type":"object","description":"Client heartbeat pong response","properties":{"op":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Timestamp from the PING message"}}}}}} ``` ## The AuthMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"AuthMessage":{"type":"object","description":"Authentication message for private stream","properties":{"op":{"type":"string"},"args":{"type":"array","description":"[apiKey, timestamp, signature]","items":{"oneOf":[{"type":"string"},{"type":"integer"}]},"minItems":3,"maxItems":3}}}}}} ``` ## The SubscribeMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"SubscribeMessage":{"type":"object","description":"Subscribe to a topic","properties":{"op":{"type":"string"},"topic":{"type":"string","description":"Topic name","enum":["TRADE","DEPTH","ORDERBOOK","INDEX","ORDER","FILL","BALANCE","RISK","POSITION"]},"symbol":{"type":"string","description":"Trading pair symbol (optional for BALANCE and RISK topics)"},"limit":{"type":"integer","description":"Depth limit for DEPTH topic (optional, 1-100)"}}}}}} ``` ## The UnsubscribeMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"UnsubscribeMessage":{"type":"object","description":"Unsubscribe from a topic","properties":{"op":{"type":"string"},"topic":{"type":"string","description":"Topic name","enum":["TRADE","DEPTH","ORDERBOOK","INDEX","ORDER","FILL","BALANCE","RISK","POSITION"]},"symbol":{"type":"string","description":"Trading pair symbol (optional for BALANCE and RISK topics)"}}}}}} ``` ## The ErrorMessage object ```json {"openapi":"3.0.3","info":{"title":"Pionex Futures WebSocket API","version":"1.0.0"},"components":{"schemas":{"ErrorMessage":{"type":"object","description":"Error response message","properties":{"event":{"type":"string"},"mcode":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message description"},"timestamp":{"type":"integer","format":"int64","description":"Error timestamp in milliseconds"}}}}}} ``` # Bot API REST endpoints for managing trading bots: grid, smart copy, and signals.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/bot-api/general-info
## APIs

:square-terminal:

Bot Ordershttps://www.pionex.com/docs/api-docs/bot-api/bot-orders

:square-terminal:

Futures Gridhttps://www.pionex.com/docs/api-docs/bot-api/futures-grid

:square-terminal:

Spot Gridhttps://www.pionex.com/docs/api-docs/bot-api/spot-grid

:square-terminal:

Smart Copyhttps://www.pionex.com/docs/api-docs/bot-api/smart-copy

:square-terminal:

Signalhttps://www.pionex.com/docs/api-docs/bot-api/signal

:square-terminal:

KOLhttps://www.pionex.com/docs/api-docs/bot-api/kol
# General Info # Basic Info **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of +/-20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"buOrderId": "123456789"}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "PARAMETER_ERROR", "message": "Invalid parameter", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions Each API Key can be configured with **Bot reading**, **Bot trading**, and/or **Enable trading** permissions. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Bot reading` permission:** * `GET /api/v1/bot/orders` — Get bot order list * `GET /api/v1/bot/orders/futuresGrid/order` — Get futures grid order * `GET /api/v1/bot/orders/spotGrid/order` — Get spot grid order * `GET /api/v1/bot/orders/spotGrid/aiStrategy` — Get spot grid AI strategy * `POST /api/v1/bot/orders/futuresGrid/checkParams` — Check futures grid parameters * `POST /api/v1/bot/orders/futuresGrid/adjustParamsCheck` — Check futures grid adjust parameters (dry-run) * `POST /api/v1/bot/orders/futuresGrid/reduceCheck` — Check futures grid reduce (dry-run) * `POST /api/v1/bot/orders/spotGrid/checkParams` — Check spot grid parameters * `POST /api/v1/bot/orders/smartCopy/checkParams` — Check smart copy parameters * `GET /api/v1/bot/orders/smartCopy/order` — Get smart copy order * `GET /api/v1/bot/signal/userSignal` — List user custom signals * `GET /api/v1/bot/signal/userSignal/detail` — Get user custom signal detail **Endpoints requiring `Enable trading` permission:** * `POST /api/v1/bot/signal/listener` — Push custom trading signal **Endpoints requiring `Bot trading` permission:** * `POST /api/v1/bot/signal/userSignal` — Create user custom signal * `POST /api/v1/bot/signal/userSignal/edit` — Edit user custom signal * `DELETE /api/v1/bot/signal/userSignal/delete` — Delete user custom signal * `POST /api/v1/bot/orders/futuresGrid/create` — Create futures grid order * `POST /api/v1/bot/orders/futuresGrid/adjustParams` — Adjust futures grid (add investment / modify range) * `POST /api/v1/bot/orders/futuresGrid/reduce` — Reduce futures grid position * `POST /api/v1/bot/orders/futuresGrid/cancel` — Cancel futures grid order * `POST /api/v1/bot/orders/futuresGrid/pauseCheck` — Check futures grid pause (dry-run) * `POST /api/v1/bot/orders/futuresGrid/pause` — Pause futures grid order * `POST /api/v1/bot/orders/futuresGrid/resumeCheck` — Check futures grid resume (dry-run) * `POST /api/v1/bot/orders/futuresGrid/resume` — Resume futures grid order * `POST /api/v1/bot/orders/futuresGrid/addMarginCheck` — Check futures grid add margin (dry-run) * `POST /api/v1/bot/orders/futuresGrid/addMargin` — Add margin to futures grid order * `POST /api/v1/bot/orders/futuresGrid/reduceMarginCheck` — Check futures grid reduce margin (dry-run) * `POST /api/v1/bot/orders/futuresGrid/reduceMargin` — Reduce margin of futures grid order * `POST /api/v1/bot/orders/futuresGrid/updateTriggerProfitLoss` — Set / update / clear take-profit & stop-loss of a running futures grid order * `POST /api/v1/bot/orders/spotGrid/create` — Create spot grid order * `POST /api/v1/bot/orders/spotGrid/adjustParams` — Adjust spot grid parameters * `POST /api/v1/bot/orders/spotGrid/investIn` — Add investment to spot grid * `POST /api/v1/bot/orders/spotGrid/cancel` — Cancel spot grid order * `POST /api/v1/bot/orders/spotGrid/profit` — Extract profit from spot grid * `POST /api/v1/bot/orders/smartCopy/create` — Create smart copy order * `POST /api/v1/bot/orders/smartCopy/cancel` — Cancel smart copy order # Bot Orders Bot order list query (private) ## Get bot order list > Query bot order list with optional filters by order type, status, and trading pair. Supports pagination. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Bot Orders","description":"Bot order list query (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"BotOrderListResponse":{"type":"object","description":"Bot order list response with pagination","properties":{"nextPageToken":{"type":"string","nullable":true,"description":"Token to fetch the next page"},"previousPageToken":{"type":"string","nullable":true,"description":"Token to fetch the previous page"},"results":{"type":"array","description":"List of bot orders","items":{"$ref":"#/components/schemas/BotOrder"}}}},"BotOrder":{"type":"object","description":"Bot order result","properties":{"buOrderType":{"type":"string","description":"Bot order type. Supported values: `futures_grid`, `future_hedge_grid` (Cross Margin Futures Grid), `spot_grid`, `smart_copy`.\n"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"strategyId":{"type":"string","description":"Strategy ID"},"canceling":{"type":"integer","format":"int64","description":"Canceling flag"},"note":{"type":"string","description":"Order note"},"closeNote":{"type":"string","description":"Close note"},"customizeName":{"type":"string","description":"Custom name"},"botName":{"type":"string","description":"Bot name"},"groupId":{"type":"string","description":"Group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"buOrderData":{"type":"object","description":"Order detail data. The structure depends on `buOrderType`:\n`futures_grid` -> `FuturesGridOrderData`,\n`future_hedge_grid` -> `FutureHedgeGridOrderData`,\n`spot_grid` -> `SpotGridOrderData`,\n`smart_copy` -> `SmartCopyOrderData`\n"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders":{"get":{"tags":["Bot Orders"],"summary":"Get bot order list","description":"Query bot order list with optional filters by order type, status, and trading pair. Supports pagination. Weight: 1.","operationId":"getBotOrders","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"status","in":"query","description":"Order status filter:\n`running` - Running orders (default),\n`finished` - Closed/cancelled orders\n","schema":{"type":"string","default":"running"}},{"name":"base","in":"query","description":"Base currency filter (e.g. BTC)","schema":{"type":"string"}},{"name":"quote","in":"query","description":"Quote currency filter (e.g. USDT)","schema":{"type":"string"}},{"name":"pageToken","in":"query","description":"Pagination token (from `nextPageToken` or `previousPageToken` in response)","schema":{"type":"string"}},{"name":"buOrderTypes","in":"query","description":"Order type filter. Can pass multiple values. If omitted, returns all types.\nSupported values: `futures_grid`, `future_hedge_grid` (Cross Margin Futures Grid), `spot_grid`, `smart_copy`.\n","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BotOrderListResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Futures Grid Futures Grid Bot management (private) ## Get futures grid order > Query a futures grid bot order by ID. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridOrder":{"type":"object","properties":{"keyId":{"type":"string","description":"API Key ID"},"userId":{"type":"string","description":"User ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"number","description":"Creation timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"groupId":{"type":"string","description":"Bound group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"note":{"type":"string","description":"Note"},"customizeName":{"type":"string","description":"Custom name"},"buOrderData":{"$ref":"#/components/schemas/FuturesGridOrderData"}}},"FuturesGridOrderData":{"type":"object","properties":{"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `condition_lock`, `open_position`, `init_grid`,\n`running`, `destroy_grid`, `close_position`, `unlock_currency`, `canceled`,\n`adjust_params`, `adjust_params_open_position`, `adjust_params_init_grid`,\n`pre_pause`, `pausing`, `paused`, `pre_resume`, `resuming`\n","enum":["prepare","lock_currency","condition_lock","open_position","init_grid","running","destroy_grid","close_position","unlock_currency","canceled","adjust_params","adjust_params_open_position","adjust_params_init_grid","pre_pause","pausing","paused","pre_resume","resuming"]},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel` - User cancelled,\n`force_liquidation` - Liquidated,\n`loss_stop` - Stop loss triggered,\n`profit_stop` - Take profit triggered,\n`not_enough_balance` - Insufficient balance during running,\n`not_enough_balance_when_lock` - Lock funds failed after order,\n`create_failed` - Order creation failed\n","enum":["user_cancel","force_liquidation","loss_stop","profit_stop","not_enough_balance","not_enough_balance_when_lock","create_failed"]},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Current price at creation"},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"type":{"type":"string","description":"Operation type (e.g. `invest_in` for adding investment)"},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Total investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraBalance":{"type":"string","description":"Extra balance"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated liquidation price (upward)"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated liquidation price (downward)"},"lossStopType":{"type":"string","description":"Stop loss type:\n`price` - By market price (default),\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`price` -> stop loss price,\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`price` - By price (default),\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`price` -> take profit price,\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"riskStatus":{"type":"string","description":"Risk status","enum":["TRADING","HOLDING","TAKEOVER","LIQUIDATION"],"default":"TRADING"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitWithdrawn":{"type":"string","description":"Total profit withdrawn"},"openQuotePrice":{"type":"string","description":"Average quote-to-USDT price for investment"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only,\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"quoteAmountBeforeSell":{"type":"string","description":"Quote amount before closing"},"quoteAmountSell":{"type":"string","description":"Quote amount sold on close"},"quoteSellPrice":{"type":"string","description":"Quote sell price on close"},"unlockUsdtAmount":{"type":"string","description":"USDT returned to main account (only when TO_USDT)"},"unlockQuoteAmount":{"type":"string","description":"Quote returned to main account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Shared profit amount"},"marginStatus":{"type":"string","description":"Margin status: `NORMAL` or `INSUFFICIENT`","enum":["NORMAL","INSUFFICIENT"],"default":"NORMAL"},"investCoin":{"type":"string","description":"Investment currency. `USDT` or quote currency (e.g. BTC)"},"investmentFrom":{"type":"string","description":"Funding source:\n`USER` - User main account,\n`LOCK_ACTIVITY` - Lock activity pool,\n`FUTURE_GRID_BONUS` - Bonus pool\n","enum":["USER","LOCK_ACTIVITY","FUTURE_GRID_BONUS"]},"lockEndTime":{"type":"number","description":"Lock end time in milliseconds"},"profitWithdrawnU":{"type":"string","description":"Profit withdrawn (user portion)"},"profitWithdrawnC":{"type":"string","description":"Profit withdrawn (charity/bonus portion)"},"profitWithdrawnP":{"type":"string","description":"Profit withdrawn (Pionex/bonus fee portion)"},"usdtInvestment":{"type":"string","description":"USDT investment amount"},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"stopLossEnabled":{"type":"boolean","description":"Stop loss enabled while paused"},"stopProfitEnabled":{"type":"boolean","description":"Take profit enabled while paused"},"triggerPausePriceUp":{"type":"string","description":"Price trigger for pause (upward)"},"triggerPausePriceDown":{"type":"string","description":"Price trigger for pause (downward)"},"triggerResumePriceUp":{"type":"string","description":"Price trigger for resume (upward), set via the resume endpoint"},"triggerResumePriceDown":{"type":"string","description":"Price trigger for resume (downward), set via the resume endpoint"},"profitReduce":{"type":"string","description":"Grid profit from position reduction (accumulated)"},"closeOrderType":{"type":"string","description":"Close order type:\n`market` - Market price close,\n`limit` - Limit price close,\n`limit_high` - Neutral grid top limit close\n","enum":["market","limit","limit_high"]},"closedBaseAmount":{"type":"string","description":"Closed position amount"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"bonusBackUsdt":{"type":"string","description":"USDT recovered from bonus on close"},"bonusBackQuote":{"type":"string","description":"Quote recovered from bonus on close"},"notionalStatus":{"type":"string","description":"Notional status: `NORMAL` or `NOTIONAL_LIMIT`","enum":["NORMAL","NOTIONAL_LIMIT"],"default":"NORMAL"},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"},"bonusFeeRatio":{"type":"string","description":"Bonus fee ratio (e.g. \"0.2\" = 20%)"},"bonusFee":{"type":"string","description":"Bonus management fee recovered on close (in quote)"},"disableChangeTp":{"type":"boolean","description":"Whether modification of take profit is disabled"},"disableInvestInTrigger":{"type":"boolean","description":"Whether trigger investment is disabled"},"investInTriggers":{"type":"array","description":"Pending trigger investment list (max 1 item)","items":{"$ref":"#/components/schemas/InvestInTrigger"}},"investOutTriggers":{"type":"array","description":"Pending trigger reduction list (max 1 item)","items":{"$ref":"#/components/schemas/InvestOutTrigger"}},"autoExpiredTime":{"type":"number","description":"Auto-close timestamp in milliseconds (for bonus orders)"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type:\n`FUTURES_MOON` - Futures moon order,\n`FULLY_HEDGING` - Fully hedged order,\n`LOAN_GRID` - Loan grid,\n`LEVERAGE_GRID` - Leverage grid,\n`FUTURE_GRID_COIN_MARGINED` - Coin-margined futures grid\n","enum":["FUTURES_MOON","FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"profitExited":{"type":"string","description":"Exited profit"},"fundingFeePayment":{"type":"string","description":"Total funding fee paid (negative value)"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close (requires original order to enable follow close)"}}},"InvestInTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger investment price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"quoteInvestment":{"type":"string","description":"Trigger investment amount"},"extraMarginAmount":{"type":"string","description":"Trigger dynamic margin"},"addTime":{"type":"number","description":"Add time in milliseconds"},"investCoin":{"type":"string","description":"Investment currency (currently only supports quote)"}}},"InvestOutTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger reduction price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"addTime":{"type":"number","description":"Add time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/order":{"get":{"tags":["Futures Grid"],"summary":"Get futures grid order","description":"Query a futures grid bot order by ID. Weight: 1.","operationId":"getFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"buOrderId","in":"query","required":true,"description":"Bot order ID","schema":{"type":"string"}},{"name":"lang","in":"query","description":"Language","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Create futures grid order > Create a new futures grid bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateFuturesGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID. Set this to the `bu_order_id` of an existing copy trading pool's lead order to join that pool: the newly created futures grid order will be attached to the pool and copied by its followers. This is the only field that makes a new order join an existing copy trading pool, so it must be a valid lead order ID — an invalid or closed value will cause the request to fail."},"buOrderData":{"$ref":"#/components/schemas/CreateFuturesGridOrderData"}}},"CreateFuturesGridOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quoteInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Investment amount"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)","enum":["-1","1"]},"lossStopType":{"type":"string","description":"Stop loss type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value (interpretation depends on lossStopType)"},"lossStopDelay":{"type":"number","description":"Stop loss delay in seconds"},"profitStopType":{"type":"string","description":"Take profit type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value (interpretation depends on profitStopType)"},"profitStopDelay":{"type":"number","description":"Take profit delay in seconds"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default), `FUTURE_GRID_BONUS`","enum":["USER","FUTURE_GRID_BONUS"]},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type (stored only)"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type","enum":["FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/create":{"post":{"tags":["Futures Grid"],"summary":"Create futures grid order","description":"Create a new futures grid bot order. Weight: 1.","operationId":"createFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuturesGridRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"buOrderData":{"type":"object","description":"Bot order data"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid parameters > Validate futures grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\ > \ > Pass a positive \`quote\_investment\` to receive full estimate fields.\ > The current market price is fetched automatically — \`open\_price\` is not required.\ > \ > \*\*Extra Margin Modes\*\* (controlled by \`extra\_margin\`):\ > \ > \| | \`extra\_margin=false\` (Manual) | \`extra\_margin=true\` (Auto-split) |\ > \|---|---|---|\ > \| \`quote\_investment\` meaning | Trading capital only | Total input (auto-split into trading capital + extra margin) |\ > \| \`extra\_margin\_amount\` | User-specified extra margin, on top of \`quote\_investment\` | Typically omitted; system auto-calculates |\ > \| \`estimate\_investment\` | = \`quote\_investment\` | < \`quote\_investment\` (trading capital portion) |\ > \| \`estimate\_extra\_margin\` | = \`extra\_margin\_amount\` | Auto-calculated (= \`quote\_investment\` − \`estimate\_investment\`) |\ > \| \`min/max\_investment\` | Range for trading capital (excl. extra margin) | Range for total input (incl. extra margin) |\ > \ > \*\*FailedWithData\*\*: For errors marked "Yes" below, the response includes a \`data\` field\ > even when \`result=false\`, containing \`min\_investment\`, \`max\_investment\`, and \`slippage\`\ > so the client can display the valid investment range.\ > \ > \*\*Validation error messages\*\* (returned in \`message\` when \`result\` is \`false\`):\ > \ > \| Message | Cause | Includes data |\ > \|---|---|---|\ > \| \`base should end with .PERP\` | \`base\` must end with \`.PERP\`, e.g. \`BTC.PERP\` | No |\ > \| \`invalid trend\` | \`trend\` must be \`long\`, \`short\`, or \`no\_trend\` | No |\ > \| \`invalid grid\_type\` | \`grid\_type\` must be \`arithmetic\` or \`geometric\` | No |\ > \| \`bottom must greater than 0\` | \`bottom\` must be a positive number | No |\ > \| \`top must greater than bottom\` | \`top\` must be strictly greater than \`bottom\` | No |\ > \| \`top must less or equal than max:{maxPrice}\` | \`top\` exceeds the symbol's maximum allowed price | No |\ > \| \`top not match quote precision\` | \`top\` has more decimal places than the symbol allows | No |\ > \| \`bottom not match quote precision\` | \`bottom\` has more decimal places than the symbol allows | No |\ > \| \`row must greater than 1\` | \`row\` must be >= 2 | No |\ > \| \`row must less than 501\` | \`row\` must be <= 500 | No |\ > \| \`invalid leverage\` | \`leverage\` is outside the symbol's allowed leverage range | No |\ > \| \`extra\_margin should greater than or equal 0\` | \`extra\_margin\_amount\` must be >= 0 | No |\ > \| \`invalid condition\_direction\` | \`condition\_direction\` must be \`""\`, \`"1"\`, or \`"-1"\` | No |\ > \| \`quote\_investment not match spending precision: max {N} decimal places\` | \`quote\_investment\` exceeds the allowed decimal precision | Yes |\ > \| \`extra\_margin\_amount not match spending precision: max {N} decimal places\` | \`extra\_margin\_amount\` exceeds the allowed decimal precision | Yes |\ > \| \`grid profit per volume less than 0\` | Grid range too narrow or \`row\` too large — profit per grid is negative | Yes |\ > \| \`less than min investment\` | \`quote\_investment\` is \`"0"\` or less than \`min\_investment\` | Yes |
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CheckFuturesGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency, must end with `.PERP`"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckFuturesGridParamsOrderData"}}},"CheckFuturesGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quote_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be greater than `bottom` and match the symbol's price precision."},"bottom":{"type":"string","description":"Grid lower price. Must be greater than 0 and match the symbol's price precision."},"row":{"type":"integer","description":"Number of grid levels (2–500)","minimum":2,"maximum":500},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"integer","description":"Leverage multiplier (1 to symbol's maximum leverage)"},"extra_margin":{"type":"boolean","description":"Controls how the investment is split between trading capital and extra margin (a safety buffer against liquidation).\n\n- `false` (default) — **Manual mode**: `quote_investment` is used entirely as trading capital (position margin + order margin + fee). Extra margin must be specified separately via `extra_margin_amount`.\n- `true` — **Auto-split mode**: `quote_investment` represents the **total input**. The system automatically splits it into trading capital and extra margin reserve. A portion is allocated as extra margin to reduce liquidation risk.\n\nThis flag also affects `min_investment` / `max_investment`:\n- `false`: the range covers trading capital only (excluding extra margin).\n- `true`: the range covers the total input (including the auto-calculated extra margin).\n","default":false},"quote_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\n\n- When `extra_margin=false`: this is the **trading capital** only (extra margin is provided separately via `extra_margin_amount`).\n- When `extra_margin=true`: this is the **total input** — the system will auto-split it into trading capital (`estimate_investment`) and extra margin (`estimate_extra_margin`).\n\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"extra_margin_amount":{"type":"string","description":"Additional margin amount on top of `quote_investment`, used as a safety buffer against liquidation. Must be >= 0. Omit or pass empty string to use 0.\n\n- When `extra_margin=false`: this value is passed through as-is. It does **not** count toward `quote_investment` or the `min_investment`/`max_investment` range, but it improves the estimated liquidation price.\n- When `extra_margin=true`: typically not needed, as the system auto-calculates extra margin from `quote_investment`. If provided, it is added on top of the auto-calculated margin and also improves the estimated liquidation price.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridCheckParamsData":{"type":"object","description":"Futures grid parameter check result data.\n\n**When result=true**: All fields are populated with full estimate data.\nLiquidation price fields are cleared when `quote_investment` is outside [`min_investment`, `max_investment`].\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"quote_investment not match spending precision: max {N} decimal places\"`,\n`\"extra_margin_amount not match spending precision: max {N} decimal places\"`,\n`\"grid profit per volume less than 0\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum allowed `quote_investment`.\n- When `extra_margin=false`: minimum trading capital (excluding extra margin).\n- When `extra_margin=true`: minimum total input (including auto-calculated extra margin).\n"},"max_investment":{"type":"string","description":"Maximum allowed `quote_investment`.\n- When `extra_margin=false`: maximum trading capital (excluding extra margin).\n- When `extra_margin=true`: maximum total input (including auto-calculated extra margin).\n"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_investment":{"type":"string","description":"Estimated amount allocated to trading capital (= position margin + order margin + fee). Does **not** include extra margin.\n- When `extra_margin=false`: equals `quote_investment` (all input goes to trading capital).\n- When `extra_margin=true`: less than `quote_investment` — the remainder goes to `estimate_extra_margin`.\n"},"estimate_extra_margin":{"type":"string","description":"Estimated extra margin — a safety buffer that reduces liquidation risk but is not used for grid trading itself.\n- When `extra_margin=false`: equals the input `extra_margin_amount` (pass-through).\n- When `extra_margin=true`: auto-calculated as `quote_investment - estimate_investment`.\n"},"estimate_fee":{"type":"string","description":"Estimated opening trading fee (included in `estimate_investment`)."},"estimate_position_occupy_margin":{"type":"string","description":"Estimated margin occupied by positions opened immediately at creation (included in `estimate_investment`)."},"estimate_order_occupy_margin":{"type":"string","description":"Estimated margin occupied by pending grid orders (included in `estimate_investment`)."},"estimate_position":{"type":"string","description":"Estimated position opened immediately at order creation. Positive = long, negative = short."},"estimate_liquidation_price_up":{"type":"string","description":"Estimated upper liquidation price. Returns `\"0\"` for long-only grids (no upper liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."},"estimate_liquidation_price_down":{"type":"string","description":"Estimated lower liquidation price. Returns `\"0\"` for short-only grids (no lower liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/checkParams":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid parameters","description":"Validate futures grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\n\nPass a positive `quote_investment` to receive full estimate fields.\nThe current market price is fetched automatically — `open_price` is not required.\n\n**Extra Margin Modes** (controlled by `extra_margin`):\n\n| | `extra_margin=false` (Manual) | `extra_margin=true` (Auto-split) |\n|---|---|---|\n| `quote_investment` meaning | Trading capital only | Total input (auto-split into trading capital + extra margin) |\n| `extra_margin_amount` | User-specified extra margin, on top of `quote_investment` | Typically omitted; system auto-calculates |\n| `estimate_investment` | = `quote_investment` | < `quote_investment` (trading capital portion) |\n| `estimate_extra_margin` | = `extra_margin_amount` | Auto-calculated (= `quote_investment` − `estimate_investment`) |\n| `min/max_investment` | Range for trading capital (excl. extra margin) | Range for total input (incl. extra margin) |\n\n**FailedWithData**: For errors marked \"Yes\" below, the response includes a `data` field\neven when `result=false`, containing `min_investment`, `max_investment`, and `slippage`\nso the client can display the valid investment range.\n\n**Validation error messages** (returned in `message` when `result` is `false`):\n\n| Message | Cause | Includes data |\n|---|---|---|\n| `base should end with .PERP` | `base` must end with `.PERP`, e.g. `BTC.PERP` | No |\n| `invalid trend` | `trend` must be `long`, `short`, or `no_trend` | No |\n| `invalid grid_type` | `grid_type` must be `arithmetic` or `geometric` | No |\n| `bottom must greater than 0` | `bottom` must be a positive number | No |\n| `top must greater than bottom` | `top` must be strictly greater than `bottom` | No |\n| `top must less or equal than max:{maxPrice}` | `top` exceeds the symbol's maximum allowed price | No |\n| `top not match quote precision` | `top` has more decimal places than the symbol allows | No |\n| `bottom not match quote precision` | `bottom` has more decimal places than the symbol allows | No |\n| `row must greater than 1` | `row` must be >= 2 | No |\n| `row must less than 501` | `row` must be <= 500 | No |\n| `invalid leverage` | `leverage` is outside the symbol's allowed leverage range | No |\n| `extra_margin should greater than or equal 0` | `extra_margin_amount` must be >= 0 | No |\n| `invalid condition_direction` | `condition_direction` must be `\"\"`, `\"1\"`, or `\"-1\"` | No |\n| `quote_investment not match spending precision: max {N} decimal places` | `quote_investment` exceeds the allowed decimal precision | Yes |\n| `extra_margin_amount not match spending precision: max {N} decimal places` | `extra_margin_amount` exceeds the allowed decimal precision | Yes |\n| `grid profit per volume less than 0` | Grid range too narrow or `row` too large — profit per grid is negative | Yes |\n| `less than min investment` | `quote_investment` is `\"0\"` or less than `min_investment` | Yes |\n","operationId":"checkFuturesGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckFuturesGridParamsRequest"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridCheckParamsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Adjust futures grid (add investment / modify range) > Add investment, modify grid range, or set trigger investment for a futures grid order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"AdjustFuturesGridRequest":{"type":"object","required":["buOrderId","type","extraMargin","openPrice"],"description":"Adjust a futures grid order. The fields controlling how the investment amount is\ntreated (`isReinvest`, `keepInvestment`, `quoteInvestment`, `adjustParamsSence`)\noverlap and interact — pick ONE intent from the table below and set exactly the\nlisted fields. Do not mix intents.\n\nInvestment-intent decision table (only relevant when `type=adjust_params`):\n\n| Intent | Set these fields |\n|----------------------------------------------------|-------------------------------------------------------------------------|\n| Only change grid range/row, keep investment fixed | `keepInvestment=true` (leave `isReinvest`/`quoteInvestment` unset) |\n| Add funds to the order | `quoteInvestment=` (do NOT rely on `isReinvest`; see its note) |\n| Reinvest current floating profit, add no new funds | `adjustParamsSence=\"reinvest\"`, `isReinvest=true`, `quoteInvestment=0` |\n\nPrecedence & hidden rules (read before setting flags):\n- `keepInvestment=true` overrides `isReinvest` — when set, `isReinvest` is ignored.\n- Passing `quoteInvestment>0` is implicitly treated as reinvest, even if you send\n `isReinvest=false`. To keep the investment untouched, use `keepInvestment=true`,\n NOT `isReinvest=false`.\n- `isReinvest=false` (without `keepInvestment`) requires current floating PnL > 0;\n otherwise the request is rejected with reason `PROFIT_LESS_THAN_ZERO`.\n- Always call `adjustParamsCheck` first with the same body to preview the outcome\n and catch these constraints before executing.\n","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Adjustment type:\n`invest_in` - Add investment,\n`adjust_params` - Modify grid range,\n`invest_in_trigger` - Trigger investment\n","enum":["invest_in","adjust_params","invest_in_trigger"]},"quoteInvestment":{"type":"number","description":"When type=invest_in: additional investment amount (must be > 0).\nWhen type=adjust_params: amount of new funds to add to the investment.\nNOTE: any value > 0 is implicitly treated as reinvest (forces isReinvest=true\ninternally), so do not send quoteInvestment>0 together with keepInvestment=true.\nLeave 0/unset for the \"keep investment\" or \"reinvest profit only\" intents.\n"},"extraMargin":{"type":"boolean","description":"true: reserve extra margin, false: no extra margin"},"openPrice":{"type":"number","description":"Current price"},"bottom":{"type":"string","description":"New grid lower price (required when type=adjust_params)"},"top":{"type":"string","description":"New grid upper price (required when type=adjust_params)"},"row":{"type":"number","description":"New grid level count (required when type=adjust_params)"},"extraMarginAmount":{"type":"number","description":"Extra margin amount to add (when type=adjust_params)"},"isRecommend":{"type":"boolean","description":"Whether using recommended parameters (when type=adjust_params)"},"isReinvest":{"type":"boolean","description":"When type=adjust_params: whether to fold current floating profit into the\ninvestment base (default false). Interacts with other fields — see the\ndecision table and precedence rules on this schema before using:\n- Ignored when keepInvestment=true.\n- Implicitly forced true when quoteInvestment>0.\n- When left false without keepInvestment, requires current PnL > 0, else the\n request is rejected with `PROFIT_LESS_THAN_ZERO`.\nFor the common \"keep investment unchanged\" intent, prefer keepInvestment=true\nover isReinvest=false.\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default) or `LOCK_ACTIVITY`","enum":["USER","LOCK_ACTIVITY"]},"condition":{"type":"string","description":"Trigger price (when type=invest_in_trigger)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]},"slippage":{"type":"string","description":"Slippage for add investment / modify range"},"adjustParamsSence":{"type":"string","description":"\"Reinvest profit only\" intent. Set to `reinvest` (only valid when\ntype=adjust_params) to keep params/funds unchanged and fold current floating\nprofit into the investment. When set to `reinvest`, you MUST also send\nisReinvest=true and quoteInvestment=0 / extraMarginAmount=0, otherwise the\nrequest is rejected. Leave empty for the other intents.\n","enum":["reinvest"]},"keepInvestment":{"type":"boolean","description":"\"Keep investment fixed\" intent (recommended for pure range/row edits).\nWhen `true` and type=adjust_params: only modify grid range/row without\nresetting the investment amount. Overrides isReinvest (isReinvest is ignored),\nskips the PnL check, but still validates the price range. Do not combine with\nquoteInvestment>0 or adjustParamsSence=reinvest.\nWhen `false` (default): investment base is recalculated after modification and\nthe PnL check applies.\n","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/adjustParams":{"post":{"tags":["Futures Grid"],"summary":"Adjust futures grid (add investment / modify range)","description":"Add investment, modify grid range, or set trigger investment for a futures grid order. Weight: 1.","operationId":"adjustFuturesGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustFuturesGridRequest"}}}},"responses":{"200":{"description":"Adjustment applied successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Reduce futures grid position > Reduce position size of a futures grid order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ReduceFuturesGridRequest":{"type":"object","required":["buOrderId","openPrice","reduceNum"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"openPrice":{"type":"string","description":"Current price"},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"slippage":{"type":"string","description":"Reduction slippage"},"condition":{"type":"string","description":"Trigger reduction price (must be > 0)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ReduceFuturesGridResponse":{"type":"object","properties":{"checkResult":{"type":"boolean","description":"Check result"},"reason":{"type":"string","description":"Failure reason:\n`LOSS_GTE_INVESTMENT` - Total equity minus dynamic margin <= 0,\n`POSITION_TOO_SMALL` - Position too small to reduce,\n`REDUCE_TOO_MUCH` - reduceNum too large,\n`REDUCE_TOO_SMALL` - reduceNum too small,\n`SYMBOL_MAINTENANCE` - Symbol under maintenance\n","enum":["LOSS_GTE_INVESTMENT","POSITION_TOO_SMALL","REDUCE_TOO_MUCH","REDUCE_TOO_SMALL","SYMBOL_MAINTENANCE"]}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduce":{"post":{"tags":["Futures Grid"],"summary":"Reduce futures grid position","description":"Reduce position size of a futures grid order. Weight: 1.","operationId":"reduceFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReduceFuturesGridRequest"}}}},"responses":{"200":{"description":"Reduction result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReduceFuturesGridResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel futures grid order > Close and cancel a futures grid bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CancelFuturesGridRequest":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeNote":{"type":"string","description":"Close note"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only (default),\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"immediate":{"type":"boolean","description":"Force-cancel an order that is stuck in the `close_position` state because its limit take-profit / stop-loss order has triggered but not yet filled. This is NOT a generic \"cancel faster\" flag.\n\n- `false` (default): normal cancellation. Use this for orders in any regular state (e.g. `running`). It runs the full close flow: update status, dispatch the close action, and settle.\n- `true`: special recovery path ONLY valid when the order is in the `close_position` state with an unfilled limit TP/SL order. It sends the close action directly with a market price. If the order is in any other state, the request is rejected with `Forbidden: invalid status`.\n\nDo not set `true` as a default \"force close\" option — for normal close-outs always use `false`."},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/cancel":{"post":{"tags":["Futures Grid"],"summary":"Cancel futures grid order","description":"Close and cancel a futures grid bot order. Weight: 1.","operationId":"cancelFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelFuturesGridRequest"}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid adjust parameters (dry-run) > Validate adjust params / invest-in parameters and return estimated data without executing.\ > Use this before calling adjustParams to preview the impact.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"AdjustFuturesGridRequest":{"type":"object","required":["buOrderId","type","extraMargin","openPrice"],"description":"Adjust a futures grid order. The fields controlling how the investment amount is\ntreated (`isReinvest`, `keepInvestment`, `quoteInvestment`, `adjustParamsSence`)\noverlap and interact — pick ONE intent from the table below and set exactly the\nlisted fields. Do not mix intents.\n\nInvestment-intent decision table (only relevant when `type=adjust_params`):\n\n| Intent | Set these fields |\n|----------------------------------------------------|-------------------------------------------------------------------------|\n| Only change grid range/row, keep investment fixed | `keepInvestment=true` (leave `isReinvest`/`quoteInvestment` unset) |\n| Add funds to the order | `quoteInvestment=` (do NOT rely on `isReinvest`; see its note) |\n| Reinvest current floating profit, add no new funds | `adjustParamsSence=\"reinvest\"`, `isReinvest=true`, `quoteInvestment=0` |\n\nPrecedence & hidden rules (read before setting flags):\n- `keepInvestment=true` overrides `isReinvest` — when set, `isReinvest` is ignored.\n- Passing `quoteInvestment>0` is implicitly treated as reinvest, even if you send\n `isReinvest=false`. To keep the investment untouched, use `keepInvestment=true`,\n NOT `isReinvest=false`.\n- `isReinvest=false` (without `keepInvestment`) requires current floating PnL > 0;\n otherwise the request is rejected with reason `PROFIT_LESS_THAN_ZERO`.\n- Always call `adjustParamsCheck` first with the same body to preview the outcome\n and catch these constraints before executing.\n","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Adjustment type:\n`invest_in` - Add investment,\n`adjust_params` - Modify grid range,\n`invest_in_trigger` - Trigger investment\n","enum":["invest_in","adjust_params","invest_in_trigger"]},"quoteInvestment":{"type":"number","description":"When type=invest_in: additional investment amount (must be > 0).\nWhen type=adjust_params: amount of new funds to add to the investment.\nNOTE: any value > 0 is implicitly treated as reinvest (forces isReinvest=true\ninternally), so do not send quoteInvestment>0 together with keepInvestment=true.\nLeave 0/unset for the \"keep investment\" or \"reinvest profit only\" intents.\n"},"extraMargin":{"type":"boolean","description":"true: reserve extra margin, false: no extra margin"},"openPrice":{"type":"number","description":"Current price"},"bottom":{"type":"string","description":"New grid lower price (required when type=adjust_params)"},"top":{"type":"string","description":"New grid upper price (required when type=adjust_params)"},"row":{"type":"number","description":"New grid level count (required when type=adjust_params)"},"extraMarginAmount":{"type":"number","description":"Extra margin amount to add (when type=adjust_params)"},"isRecommend":{"type":"boolean","description":"Whether using recommended parameters (when type=adjust_params)"},"isReinvest":{"type":"boolean","description":"When type=adjust_params: whether to fold current floating profit into the\ninvestment base (default false). Interacts with other fields — see the\ndecision table and precedence rules on this schema before using:\n- Ignored when keepInvestment=true.\n- Implicitly forced true when quoteInvestment>0.\n- When left false without keepInvestment, requires current PnL > 0, else the\n request is rejected with `PROFIT_LESS_THAN_ZERO`.\nFor the common \"keep investment unchanged\" intent, prefer keepInvestment=true\nover isReinvest=false.\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default) or `LOCK_ACTIVITY`","enum":["USER","LOCK_ACTIVITY"]},"condition":{"type":"string","description":"Trigger price (when type=invest_in_trigger)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]},"slippage":{"type":"string","description":"Slippage for add investment / modify range"},"adjustParamsSence":{"type":"string","description":"\"Reinvest profit only\" intent. Set to `reinvest` (only valid when\ntype=adjust_params) to keep params/funds unchanged and fold current floating\nprofit into the investment. When set to `reinvest`, you MUST also send\nisReinvest=true and quoteInvestment=0 / extraMarginAmount=0, otherwise the\nrequest is rejected. Leave empty for the other intents.\n","enum":["reinvest"]},"keepInvestment":{"type":"boolean","description":"\"Keep investment fixed\" intent (recommended for pure range/row edits).\nWhen `true` and type=adjust_params: only modify grid range/row without\nresetting the investment amount. Overrides isReinvest (isReinvest is ignored),\nskips the PnL check, but still validates the price range. Do not combine with\nquoteInvestment>0 or adjustParamsSence=reinvest.\nWhen `false` (default): investment base is recalculated after modification and\nthe PnL check applies.\n","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"AdjustParamsCheckResponse":{"type":"object","description":"Adjust params check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the adjustment is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"estimateInvestment":{"type":"string","description":"Estimated investment amount after adjustment"},"estimateExtraMargin":{"type":"string","description":"Estimated extra margin after adjustment"},"minInvestment":{"type":"string","description":"Minimum required investment"},"maxInvestment":{"type":"string","description":"Maximum allowed investment"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after adjustment"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after adjustment"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"estimatePerVolume":{"type":"string","description":"Estimated per-grid volume after adjustment"},"slippage":{"type":"string","description":"Recommended slippage"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/adjustParamsCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid adjust parameters (dry-run)","description":"Validate adjust params / invest-in parameters and return estimated data without executing.\nUse this before calling adjustParams to preview the impact.\nWeight: 1.\n","operationId":"adjustFuturesGridParamsCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustFuturesGridRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code, reason message, and partial estimate data.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdjustParamsCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid reduce (dry-run) > Validate reduce parameters and return estimated data without executing.\ > Use this before calling reduce to preview the impact.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ReduceFuturesGridRequest":{"type":"object","required":["buOrderId","openPrice","reduceNum"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"openPrice":{"type":"string","description":"Current price"},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"slippage":{"type":"string","description":"Reduction slippage"},"condition":{"type":"string","description":"Trigger reduction price (must be > 0)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ReduceCheckResponse":{"type":"object","description":"Reduce check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the reduction is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"maxReduceNum":{"type":"integer","description":"Maximum reduce number allowed"},"reduceAmount":{"type":"string","description":"Estimated total reduction amount"},"reduceInvestment":{"type":"string","description":"Estimated investment to be returned"},"reduceGridprofit":{"type":"string","description":"Estimated grid profit to be returned"},"reducePnl":{"type":"string","description":"Estimated PnL from reduction"},"reduceFee":{"type":"string","description":"Estimated fee for reduction"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Upward liquidation price after reduction"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Downward liquidation price after reduction"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"slippage":{"type":"string","description":"Recommended slippage"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid reduce (dry-run)","description":"Validate reduce parameters and return estimated data without executing.\nUse this before calling reduce to preview the impact.\nWeight: 1.\n","operationId":"reduceFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReduceFuturesGridRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code, reason message, and partial estimate data.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReduceCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid pause (dry-run) > Validate whether a futures grid order can be paused (\`immediate\` or \`conditional\` mode)\ > and return current plus post-trigger estimated liquidation prices without executing.\ > Does not accept \`openPrice\`; the backend uses the live market price.\ > \`triggerPausePriceUp\` / \`triggerPausePriceDown\` are independent — set either or both.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridPauseCheckRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now; `conditional` = pause on trigger price"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price (when mode=conditional). Optional; set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price (when mode=conditional). Optional."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridPauseCheckResponse":{"type":"object","description":"Pause check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be paused"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_RUNNING)"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — upward liquidation price after the upward pause triggers"},"estimateLiquidationPriceDownAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — downward liquidation price after the upward pause triggers"},"estimateLiquidationPriceUpAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — upward liquidation price after the downward pause triggers"},"estimateLiquidationPriceDownAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — downward liquidation price after the downward pause triggers"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/pauseCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid pause (dry-run)","description":"Validate whether a futures grid order can be paused (`immediate` or `conditional` mode)\nand return current plus post-trigger estimated liquidation prices without executing.\nDoes not accept `openPrice`; the backend uses the live market price.\n`triggerPausePriceUp` / `triggerPausePriceDown` are independent — set either or both.\nWeight: 1.\n","operationId":"pauseFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridPauseCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridPauseCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Pause futures grid order > Pause a running futures grid order. Runs the same validation as \`pauseCheck\`, then\ > executes asynchronously. Once paused the grid stops auto-refilling orders while the\ > position is retained; \`immediate\` mode takes effect at the live market price.\ > Does not return a \`status\` field (async processing).\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridPauseRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now (backend uses live market price, not client-supplied); `conditional` = pause on trigger price"},"stopProfitEnabled":{"type":"boolean","description":"Whether to keep take-profit active while paused"},"stopLossEnabled":{"type":"boolean","description":"Whether to keep stop-loss active while paused"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price. Set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridPauseResponse":{"type":"object","description":"Pause execution result (no status field; processed asynchronously)","properties":{"stopLossEnabled":{"type":"boolean","description":"Effective stop-loss retention state"},"stopProfitEnabled":{"type":"boolean","description":"Effective take-profit retention state"},"triggerPausePriceUp":{"type":"string","description":"Effective upward trigger price"},"triggerPausePriceDown":{"type":"string","description":"Effective downward trigger price"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/pause":{"post":{"tags":["Futures Grid"],"summary":"Pause futures grid order","description":"Pause a running futures grid order. Runs the same validation as `pauseCheck`, then\nexecutes asynchronously. Once paused the grid stops auto-refilling orders while the\nposition is retained; `immediate` mode takes effect at the live market price.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"pauseFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridPauseRequest"}}}},"responses":{"200":{"description":"Pause accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridPauseResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid resume (dry-run) > Validate whether a paused futures grid order can be resumed and return the estimated\ > liquidation prices after resuming, without executing. Order must be in \`paused\` state.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridResumeCheckRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridResumeCheckResponse":{"type":"object","description":"Resume check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be resumed"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_PAUSED)"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price after resuming"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price after resuming"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/resumeCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid resume (dry-run)","description":"Validate whether a paused futures grid order can be resumed and return the estimated\nliquidation prices after resuming, without executing. Order must be in `paused` state.\nWeight: 1.\n","operationId":"resumeFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridResumeCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridResumeCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Resume futures grid order > Resume a paused futures grid order. Runs the same validation as \`resumeCheck\`, then\ > executes. After resuming the grid restarts auto-refilling and the liquidation price\ > moves with the market.\ > \ > Supports trigger resume: set \`triggerResumePriceUp\` / \`triggerResumePriceDown\` (either\ > or both) to resume automatically once the market price crosses that level, instead of\ > resuming immediately. \`isResumeImmediate\` is optional and tri-state:\ > \- Omitted: inferred from the trigger prices — both empty resumes immediately, either set\ > triggers a conditional resume.\ > \- \`true\`: resume immediately now; any trigger prices are ignored (silently cleared, no\ > error even if they fail direction validation).\ > \- \`false\`: conditional resume, keep the given trigger price(s). Passing \`false\` with both\ > trigger prices empty cancels trigger resume and keeps the order paused.\ > \ > For a conditional resume, \`triggerResumePriceUp\` must be greater than the current market\ > price and \`triggerResumePriceDown\` must be greater than 0 and less than the current\ > market price; violating either returns HTTP 400 (see below) instead of dispatching.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridResumeRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"triggerResumePriceUp":{"type":"string","description":"Upward trigger price for a conditional resume. Must be greater than the current market price. Independent from triggerResumePriceDown — set either or both."},"triggerResumePriceDown":{"type":"string","description":"Downward trigger price for a conditional resume. Must be greater than 0 and less than the current market price."},"isResumeImmediate":{"type":"boolean","description":"Optional tri-state flag. `true` = resume immediately (trigger prices ignored). `false` = conditional resume, keep the given trigger price(s); with both trigger prices empty this cancels trigger resume and keeps the order paused. Omitted = inferred from the trigger prices (both empty -> immediate, either set -> conditional)."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridResumeResponse":{"type":"object","description":"Resume execution result","properties":{"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}},"FuturesGridResumeInvalidTriggerPriceError":{"type":"object","description":"400 body returned when triggerResumePriceUp / triggerResumePriceDown fails direction validation or fails to parse. Rejected before dispatching; the order stays paused.","properties":{"code":{"type":"integer","description":"Fixed `40000700`."},"reason":{"type":"string","description":"Fixed `P_TRADING_BOT_INVALID_TRIGGER_PRICE_PARAM`."},"message":{"type":"string","description":"Specific validation error detail."},"data":{"nullable":true,"description":"Always null."}}}},"responses":{"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/resume":{"post":{"tags":["Futures Grid"],"summary":"Resume futures grid order","description":"Resume a paused futures grid order. Runs the same validation as `resumeCheck`, then\nexecutes. After resuming the grid restarts auto-refilling and the liquidation price\nmoves with the market.\n\nSupports trigger resume: set `triggerResumePriceUp` / `triggerResumePriceDown` (either\nor both) to resume automatically once the market price crosses that level, instead of\nresuming immediately. `isResumeImmediate` is optional and tri-state:\n- Omitted: inferred from the trigger prices — both empty resumes immediately, either set\n triggers a conditional resume.\n- `true`: resume immediately now; any trigger prices are ignored (silently cleared, no\n error even if they fail direction validation).\n- `false`: conditional resume, keep the given trigger price(s). Passing `false` with both\n trigger prices empty cancels trigger resume and keeps the order paused.\n\nFor a conditional resume, `triggerResumePriceUp` must be greater than the current market\nprice and `triggerResumePriceDown` must be greater than 0 and less than the current\nmarket price; violating either returns HTTP 400 (see below) instead of dispatching.\nWeight: 1.\n","operationId":"resumeFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridResumeRequest"}}}},"responses":{"200":{"description":"Resume accepted.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridResumeResponse"}}}]}}}},"400":{"description":"Bad request. Also returned when `triggerResumePriceUp` / `triggerResumePriceDown`\nfails direction validation or fails to parse (not applicable when `isResumeImmediate`\nresolves to `true`) — in that case the body uses `FuturesGridResumeInvalidTriggerPriceError`\ninstead of the generic `ErrorResponse` shape.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/FuturesGridResumeInvalidTriggerPriceError"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid add margin (dry-run) > Validate whether the add-margin amount is valid and return the estimated liquidation\ > prices before and after the change, without executing.\ > Does not accept \`openPrice\`; the backend uses the live market price.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginCheckRequest":{"type":"object","required":["buOrderId","amount"],"description":"Shared by addMarginCheck and reduceMarginCheck; the direction is determined by the route, not a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal, serialized as an unquoted number)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginCheckResponse":{"type":"object","description":"Add/reduce margin check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the amount is valid"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / EXCEEDS_MAX_AMOUNT)"},"estimateLiquidationPriceUpBefore":{"type":"string","description":"Estimated upward liquidation price before the change"},"estimateLiquidationPriceDownBefore":{"type":"string","description":"Estimated downward liquidation price before the change"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after the change"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after the change"},"maxAmount":{"type":"string","description":"Returned by reduceMarginCheck only — max reducible margin = min(existing extra margin, total equity − 1.05× used margin, margin account balance)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/addMarginCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid add margin (dry-run)","description":"Validate whether the add-margin amount is valid and return the estimated liquidation\nprices before and after the change, without executing.\nDoes not accept `openPrice`; the backend uses the live market price.\nWeight: 1.\n","operationId":"addMarginFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Add margin to futures grid order > Transfer margin into a futures grid order. Runs the same validation as \`addMarginCheck\`,\ > then executes asynchronously. Directly affects available balance and the order's\ > liquidation price — a funds operation, call with care.\ > Does not return a \`status\` field (async processing).\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginTransferRequest":{"type":"object","required":["buOrderId","coin","amount"],"description":"Shared by addMargin and reduceMargin; the direction (in/out) is fixed server-side by the route and not exposed as a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginTransferResponse":{"type":"object","description":"Add/reduce margin execution result (no status field; processed asynchronously)","properties":{"transferId":{"type":"string","description":"Transfer record ID"},"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/addMargin":{"post":{"tags":["Futures Grid"],"summary":"Add margin to futures grid order","description":"Transfer margin into a futures grid order. Runs the same validation as `addMarginCheck`,\nthen executes asynchronously. Directly affects available balance and the order's\nliquidation price — a funds operation, call with care.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"addMarginFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginTransferRequest"}}}},"responses":{"200":{"description":"Add margin accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginTransferResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check futures grid reduce margin (dry-run) > Validate whether the reduce-margin amount is valid (subject to the \`maxAmount\` hard limit)\ > and return the estimated liquidation prices before and after the change, without executing.\ > Exceeding \`maxAmount\` returns \`checkResult=false\` with reason \`EXCEEDS\_MAX\_AMOUNT\`.\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginCheckRequest":{"type":"object","required":["buOrderId","amount"],"description":"Shared by addMarginCheck and reduceMarginCheck; the direction is determined by the route, not a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal, serialized as an unquoted number)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginCheckResponse":{"type":"object","description":"Add/reduce margin check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the amount is valid"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / EXCEEDS_MAX_AMOUNT)"},"estimateLiquidationPriceUpBefore":{"type":"string","description":"Estimated upward liquidation price before the change"},"estimateLiquidationPriceDownBefore":{"type":"string","description":"Estimated downward liquidation price before the change"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after the change"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after the change"},"maxAmount":{"type":"string","description":"Returned by reduceMarginCheck only — max reducible margin = min(existing extra margin, total equity − 1.05× used margin, margin account balance)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceMarginCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid reduce margin (dry-run)","description":"Validate whether the reduce-margin amount is valid (subject to the `maxAmount` hard limit)\nand return the estimated liquidation prices before and after the change, without executing.\nExceeding `maxAmount` returns `checkResult=false` with reason `EXCEEDS_MAX_AMOUNT`.\nWeight: 1.\n","operationId":"reduceMarginFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Reduce margin of futures grid order > Transfer margin out of a futures grid order. Runs the same validation as\ > \`reduceMarginCheck\` (including the \`maxAmount\` check), then executes asynchronously.\ > Directly reduces the order's available margin and raises liquidation risk — a funds\ > operation, call with care.\ > Does not return a \`status\` field (async processing).\ > Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginTransferRequest":{"type":"object","required":["buOrderId","coin","amount"],"description":"Shared by addMargin and reduceMargin; the direction (in/out) is fixed server-side by the route and not exposed as a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginTransferResponse":{"type":"object","description":"Add/reduce margin execution result (no status field; processed asynchronously)","properties":{"transferId":{"type":"string","description":"Transfer record ID"},"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceMargin":{"post":{"tags":["Futures Grid"],"summary":"Reduce margin of futures grid order","description":"Transfer margin out of a futures grid order. Runs the same validation as\n`reduceMarginCheck` (including the `maxAmount` check), then executes asynchronously.\nDirectly reduces the order's available margin and raises liquidation risk — a funds\noperation, call with care.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"reduceMarginFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginTransferRequest"}}}},"responses":{"200":{"description":"Reduce margin accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginTransferResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Set / update / clear take-profit & stop-loss > Set, update, or clear the take-profit and/or stop-loss of an \*\*already running\*\*\ > futures grid order. Weight: 1.\ > \ > This does NOT create triggers for a not-yet-started order — use \`create\` (fields\ > \`lossStopType\` / \`profitStopType\` etc.) for that. This endpoint mutates the\ > take-profit / stop-loss of an existing order in place.\ > \ > \*\*Request field naming\*\*: unlike the other \`futuresGrid\` endpoints (which use\ > camelCase), this endpoint takes \*\*snake\_case\*\* field names, and the trigger\ > settings are passed as a \`list\` of items — one item per trigger you want to set.\ > A single call may contain a \`stop\_loss\` item, a \`stop\_profit\` item, or both.\ > \ > \*\*\`type\`\*\* — which trigger the item configures. Only two values are accepted\ > (App-side legacy spellings such as \`stop-loss\` and the entry-trigger value\ > \`condition\` are rejected here):\ > \ > \| \`type\` | Meaning |\ > \|---|---|\ > \| \`stop\_loss\` | Configure the stop-loss trigger |\ > \| \`stop\_profit\` | Configure the take-profit trigger |\ > \ > \*\*\`stop\_type\`\*\* — decides how \`value\` (and \`limit\_price\`) is interpreted.\ > \*\*Required\*\*; unlike the App, an empty value is NOT accepted (no implicit\ > fallback to \`price\`):\ > \ > \| \`stop\_type\` | \`value\` means | \`limit\_price\` |\ > \|---|---|---|\ > \| \`price\` | Trigger price | ignored |\ > \| \`price\_limit\` | Trigger price; order is placed as a \*\*limit\*\* order at \`limit\_price\` when hit | required |\ > \| \`profit\_amount\` | Profit/loss \*\*amount\*\* in the settlement currency | ignored |\ > \| \`profit\_ratio\` | Profit/loss \*\*ratio\*\* (e.g. \`0.5\` = +50%, \`-0.2\` = −20%) | ignored |\ > \ > \*\*Clearing a trigger\*\*: pass \`value\` as an empty string \`""\` for that item to\ > remove the previously set take-profit / stop-loss.\ > \ > \*\*\`value\` validation\*\*: when \`value\` is non-empty it only needs to be a valid\ > decimal — the endpoint does not enforce a positive value. \`0\` and negative values\ > are accepted (a stop-loss expressed as a negative \`profit\_ratio\` / \`profit\_amount\`\ > is meaningful).\ > \ > \*\*Neutral grid (\`no\_trend\`) upper stop-loss\*\*: for a neutral grid, a stop-loss can\ > additionally set an \*\*upper\*\* threshold above the grid range using\ > \`stop\_high\_price\` (and \`limit\_high\_price\` when \`stop\_type=price\_limit\`). These two\ > fields apply only to a \`stop\_loss\` item on a neutral grid and only when\ > \`stop\_type\` is \`price\` or \`price\_limit\`; they are ignored otherwise.\ > \ > \*\*\`\*\_sell\_model\`\*\* — settlement currency for the position closed by the trigger.\ > Optional; when empty the order's default is used:\ > \ > \| Value | Meaning |\ > \|---|---|\ > \| \`TO\_QUOTE\` | Settle to the quote currency |\ > \| \`TO\_USDT\` | Settle to USDT |\ > \ > Use \`loss\_stop\_sell\_model\` on a \`stop\_loss\` item and \`profit\_stop\_sell\_model\` on a\ > \`stop\_profit\` item.\ > \ > \*\*Asynchronous write\*\*: a successful response only means the request was accepted\ > and forwarded. The take-profit / stop-loss is persisted onto the order record\ > asynchronously — poll \`GET /futuresGrid/order\` and read \`lossStop\` / \`profitStop\`\ > (and related fields) to confirm the update took effect.\ > \ > \*\*Restrictions\*\* (return \`result=false\` with the message shown):\ > \ > \| Message | Cause |\ > \|---|---|\ > \| \`trigger price list nil\` | \`list\` is empty |\ > \| \`invalid type: {v}, must be one of stop\_loss/stop\_profit\` | \`type\` not in the allow-list |\ > \| \`invalid stop\_type: {v}, must be one of price/price\_limit/profit\_amount/profit\_ratio\` | \`stop\_type\` missing or not in the allow-list |\ > \| \`invalid amount: {v}\` | \`value\` / \`limit\_price\` / \`limit\_high\_price\` is not a valid decimal |\ > \| \`invalid loss\_stop\_sell\_model: {v}\` | \`loss\_stop\_sell\_model\` not \`TO\_QUOTE\` / \`TO\_USDT\` |\ > \| \`invalid profit\_stop\_sell\_model: {v}\` | \`profit\_stop\_sell\_model\` not \`TO\_QUOTE\` / \`TO\_USDT\` |\ > \| \`order is disable change tp\` | The order forbids changing take-profit / stop-loss |\ > \| \`forbidden by invalid status:{s}, order\_id:{id}\` | Order is closing/unlocking/canceled |\ > \| \`forbidden for future\_grid\_bonus order\` | Bonus-funded orders cannot set a stop-loss |\ > \ > \*\*Examples\*\* — request bodies for common combinations:\ > \ > Set a stop-loss at a fixed price:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_loss", "stop\_type": "price", "value": "70000" }\ > ]\ > }\ > \`\`\`\ > \ > Set a take-profit at a fixed price:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_profit", "stop\_type": "price", "value": "150000" }\ > ]\ > }\ > \`\`\`\ > \ > Set both take-profit and stop-loss in one call:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_loss", "stop\_type": "price", "value": "70000" },\ > { "type": "stop\_profit", "stop\_type": "price", "value": "150000" }\ > ]\ > }\ > \`\`\`\ > \ > Stop-loss by loss ratio (−20%) and take-profit by profit ratio (+50%):\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_loss", "stop\_type": "profit\_ratio", "value": "-0.2" },\ > { "type": "stop\_profit", "stop\_type": "profit\_ratio", "value": "0.5" }\ > ]\ > }\ > \`\`\`\ > \ > Take-profit by profit amount, settled to USDT:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_profit", "stop\_type": "profit\_amount", "value": "500", "profit\_stop\_sell\_model": "TO\_USDT" }\ > ]\ > }\ > \`\`\`\ > \ > Take-profit as a limit order (place a limit at 149000 when 150000 is hit),\ > with a 30s trigger delay:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_profit", "stop\_type": "price\_limit", "value": "150000", "limit\_price": "149000", "stop\_delay": 30 }\ > ]\ > }\ > \`\`\`\ > \ > Neutral grid (\`no\_trend\`) — lower and upper stop-loss prices:\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_loss", "stop\_type": "price", "value": "70000", "stop\_high\_price": "160000" }\ > ]\ > }\ > \`\`\`\ > \ > Clear a previously set stop-loss (empty \`value\`):\ > \`\`\`json\ > {\ > "bu\_order\_id": "1234567890",\ > "list": \[\ > { "type": "stop\_loss", "stop\_type": "price", "value": "" }\ > ]\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridUpdateTriggerProfitLossRequest":{"type":"object","required":["bu_order_id","list"],"description":"Set / update / clear the take-profit and stop-loss of a running futures grid order.\nField names are snake_case (unlike the other futuresGrid endpoints).\n","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"list":{"type":"array","description":"One item per trigger to configure. May include a `stop_loss` item, a `stop_profit` item, or both.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"FuturesGridTriggerProfitLossItem":{"type":"object","required":["type","stop_type","value"],"description":"A single take-profit or stop-loss setting. Field names are snake_case.\nHow `value` / `limit_price` are interpreted depends on `stop_type`.\n","properties":{"type":{"type":"string","description":"Which trigger this item configures","enum":["stop_loss","stop_profit"]},"stop_type":{"type":"string","description":"How `value` is interpreted. Required (no implicit fallback):\n`price` (trigger price), `price_limit` (trigger price, closes via a limit\norder at `limit_price`), `profit_amount` (profit/loss amount),\n`profit_ratio` (profit/loss ratio).\n","enum":["price","price_limit","profit_amount","profit_ratio"]},"value":{"type":"string","description":"Trigger threshold, interpreted per `stop_type`. Empty string `\"\"` clears the\ntrigger. When non-empty it only needs to be a valid decimal — not enforced to\nbe positive; `0` and negative values are accepted (e.g. `-0.2` = a −20%\nstop-loss ratio).\n"},"limit_price":{"type":"string","description":"Limit price used to close the position when `stop_type=price_limit`. Required in that case."},"stop_delay":{"type":"integer","format":"int64","description":"Seconds to wait after the condition is first met before executing. `0` = immediate."},"loss_stop_sell_model":{"type":"string","description":"Settlement currency for a stop-loss close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"profit_stop_sell_model":{"type":"string","description":"Settlement currency for a take-profit close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"stop_high_price":{"type":"string","description":"Upper stop-loss price for a neutral grid (`no_trend`). Applies only to a\n`stop_loss` item and only when `stop_type` is `price` or `price_limit`;\nignored otherwise.\n"},"limit_high_price":{"type":"string","description":"Upper limit stop-loss price for a neutral grid, used together with `stop_high_price` when `stop_type=price_limit`."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridTriggerProfitLossResponse":{"type":"object","description":"Echo of the applied trigger settings. Persistence onto the order is asynchronous — poll `GET /futuresGrid/order` to confirm.","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"result":{"type":"integer","format":"int32","description":"RPC return code"},"list":{"type":"array","description":"Echo of the trigger settings that were applied.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/updateTriggerProfitLoss":{"post":{"tags":["Futures Grid"],"summary":"Set / update / clear take-profit & stop-loss","description":"Set, update, or clear the take-profit and/or stop-loss of an **already running**\nfutures grid order. Weight: 1.\n\nThis does NOT create triggers for a not-yet-started order — use `create` (fields\n`lossStopType` / `profitStopType` etc.) for that. This endpoint mutates the\ntake-profit / stop-loss of an existing order in place.\n\n**Request field naming**: unlike the other `futuresGrid` endpoints (which use\ncamelCase), this endpoint takes **snake_case** field names, and the trigger\nsettings are passed as a `list` of items — one item per trigger you want to set.\nA single call may contain a `stop_loss` item, a `stop_profit` item, or both.\n\n**`type`** — which trigger the item configures. Only two values are accepted\n(App-side legacy spellings such as `stop-loss` and the entry-trigger value\n`condition` are rejected here):\n\n| `type` | Meaning |\n|---|---|\n| `stop_loss` | Configure the stop-loss trigger |\n| `stop_profit` | Configure the take-profit trigger |\n\n**`stop_type`** — decides how `value` (and `limit_price`) is interpreted.\n**Required**; unlike the App, an empty value is NOT accepted (no implicit\nfallback to `price`):\n\n| `stop_type` | `value` means | `limit_price` |\n|---|---|---|\n| `price` | Trigger price | ignored |\n| `price_limit` | Trigger price; order is placed as a **limit** order at `limit_price` when hit | required |\n| `profit_amount` | Profit/loss **amount** in the settlement currency | ignored |\n| `profit_ratio` | Profit/loss **ratio** (e.g. `0.5` = +50%, `-0.2` = −20%) | ignored |\n\n**Clearing a trigger**: pass `value` as an empty string `\"\"` for that item to\nremove the previously set take-profit / stop-loss.\n\n**`value` validation**: when `value` is non-empty it only needs to be a valid\ndecimal — the endpoint does not enforce a positive value. `0` and negative values\nare accepted (a stop-loss expressed as a negative `profit_ratio` / `profit_amount`\nis meaningful).\n\n**Neutral grid (`no_trend`) upper stop-loss**: for a neutral grid, a stop-loss can\nadditionally set an **upper** threshold above the grid range using\n`stop_high_price` (and `limit_high_price` when `stop_type=price_limit`). These two\nfields apply only to a `stop_loss` item on a neutral grid and only when\n`stop_type` is `price` or `price_limit`; they are ignored otherwise.\n\n**`*_sell_model`** — settlement currency for the position closed by the trigger.\nOptional; when empty the order's default is used:\n\n| Value | Meaning |\n|---|---|\n| `TO_QUOTE` | Settle to the quote currency |\n| `TO_USDT` | Settle to USDT |\n\nUse `loss_stop_sell_model` on a `stop_loss` item and `profit_stop_sell_model` on a\n`stop_profit` item.\n\n**Asynchronous write**: a successful response only means the request was accepted\nand forwarded. The take-profit / stop-loss is persisted onto the order record\nasynchronously — poll `GET /futuresGrid/order` and read `lossStop` / `profitStop`\n(and related fields) to confirm the update took effect.\n\n**Restrictions** (return `result=false` with the message shown):\n\n| Message | Cause |\n|---|---|\n| `trigger price list nil` | `list` is empty |\n| `invalid type: {v}, must be one of stop_loss/stop_profit` | `type` not in the allow-list |\n| `invalid stop_type: {v}, must be one of price/price_limit/profit_amount/profit_ratio` | `stop_type` missing or not in the allow-list |\n| `invalid amount: {v}` | `value` / `limit_price` / `limit_high_price` is not a valid decimal |\n| `invalid loss_stop_sell_model: {v}` | `loss_stop_sell_model` not `TO_QUOTE` / `TO_USDT` |\n| `invalid profit_stop_sell_model: {v}` | `profit_stop_sell_model` not `TO_QUOTE` / `TO_USDT` |\n| `order is disable change tp` | The order forbids changing take-profit / stop-loss |\n| `forbidden by invalid status:{s}, order_id:{id}` | Order is closing/unlocking/canceled |\n| `forbidden for future_grid_bonus order` | Bonus-funded orders cannot set a stop-loss |\n\n**Examples** — request bodies for common combinations:\n\nSet a stop-loss at a fixed price:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"70000\" }\n ]\n}\n```\n\nSet a take-profit at a fixed price:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_profit\", \"stop_type\": \"price\", \"value\": \"150000\" }\n ]\n}\n```\n\nSet both take-profit and stop-loss in one call:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"70000\" },\n { \"type\": \"stop_profit\", \"stop_type\": \"price\", \"value\": \"150000\" }\n ]\n}\n```\n\nStop-loss by loss ratio (−20%) and take-profit by profit ratio (+50%):\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_loss\", \"stop_type\": \"profit_ratio\", \"value\": \"-0.2\" },\n { \"type\": \"stop_profit\", \"stop_type\": \"profit_ratio\", \"value\": \"0.5\" }\n ]\n}\n```\n\nTake-profit by profit amount, settled to USDT:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_profit\", \"stop_type\": \"profit_amount\", \"value\": \"500\", \"profit_stop_sell_model\": \"TO_USDT\" }\n ]\n}\n```\n\nTake-profit as a limit order (place a limit at 149000 when 150000 is hit),\nwith a 30s trigger delay:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_profit\", \"stop_type\": \"price_limit\", \"value\": \"150000\", \"limit_price\": \"149000\", \"stop_delay\": 30 }\n ]\n}\n```\n\nNeutral grid (`no_trend`) — lower and upper stop-loss prices:\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"70000\", \"stop_high_price\": \"160000\" }\n ]\n}\n```\n\nClear a previously set stop-loss (empty `value`):\n```json\n{\n \"bu_order_id\": \"1234567890\",\n \"list\": [\n { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"\" }\n ]\n}\n```\n","operationId":"updateTriggerProfitLossFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridUpdateTriggerProfitLossRequest"}}}},"responses":{"200":{"description":"Trigger update accepted (persisted asynchronously).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` # Spot Grid Spot Grid Bot management (private) ## Get spot grid order > Query a spot grid bot order by ID. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SpotGridOrder":{"type":"object","description":"Spot grid bot order (wraps OrderResult with GridV5OrderData)","properties":{"buOrderType":{"type":"string","description":"Order type (always `grid_v5` for spot grid)"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"note":{"type":"string","description":"Order note"},"buOrderData":{"$ref":"#/components/schemas/SpotGridOrderData"}}},"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/order":{"get":{"tags":["Spot Grid"],"summary":"Get spot grid order","description":"Query a spot grid bot order by ID. Weight: 1.","operationId":"getSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"buOrderId","in":"query","required":true,"description":"Bot order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get spot grid AI strategy > Query AI-recommended grid strategy parameters for a trading pair. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SpotGridAiStrategy":{"type":"object","description":"AI-recommended spot grid strategy","properties":{"annualized":{"type":"string","description":"Annualized return of the recommended strategy"},"totalApr":{"type":"string","description":"Total APR"},"high":{"type":"string","description":"Recommended grid upper price"},"low":{"type":"string","description":"Recommended grid lower price"},"gridCount":{"type":"integer","description":"Recommended number of grid levels"},"strategyId":{"type":"string","description":"Strategy ID"},"volatility":{"type":"string","description":"Market volatility indicator"},"maxDrawDown":{"type":"string","description":"Maximum drawdown"},"options":{"type":"array","description":"List of strategy options by time period","items":{"$ref":"#/components/schemas/SpotGridAiStrategyOption"}}}},"SpotGridAiStrategyOption":{"type":"object","description":"AI strategy option for a specific backtesting period","properties":{"period":{"type":"integer","description":"Backtesting period in days (e.g. 7, 14, 30)"},"annualized":{"type":"string","description":"Annualized return for this period"},"totalApr":{"type":"string","description":"Total APR for this period"},"high":{"type":"string","description":"Grid upper price for this period"},"low":{"type":"string","description":"Grid lower price for this period"},"gridCount":{"type":"integer","description":"Number of grid levels for this period"},"maxDrawDown":{"type":"string","description":"Maximum drawdown for this period"},"volatility":{"type":"string","description":"Volatility for this period"},"suitabilityMin":{"type":"integer","description":"Minimum suitability score"},"suitabilityMax":{"type":"integer","description":"Maximum suitability score"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/aiStrategy":{"get":{"tags":["Spot Grid"],"summary":"Get spot grid AI strategy","description":"Query AI-recommended grid strategy parameters for a trading pair. Weight: 1.","operationId":"getSpotGridAiStrategy","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"base","in":"query","required":true,"description":"Base currency (e.g. BTC)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote currency (e.g. USDT)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridAiStrategy"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Create spot grid order > Create a new spot grid bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateSpotGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"note":{"type":"string","description":"Optional order note"},"buOrderData":{"$ref":"#/components/schemas/CreateSpotGridOrderData"}}},"CreateSpotGridOrderData":{"type":"object","required":["top","bottom","row","gridType","quoteTotalInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels (2–200)"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteTotalInvestment":{"type":"string","description":"Quote currency investment amount"},"lossStopType":{"type":"string","description":"Stop loss mode:\n`price` — trigger when market price reaches `lossStop`,\n`profit_amount` — trigger when unrealized loss reaches `lossStop` amount,\n`profit_ratio` — trigger when unrealized loss reaches `lossStop` ratio (e.g. `\"-0.1\"` = -10%)\n","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"profitStopType":{"type":"string","description":"Take profit mode:\n`price` — trigger when market price reaches `profitStop`,\n`profit_amount` — trigger when realized profit reaches `profitStop` amount,\n`profit_ratio` — trigger when realized profit reaches `profitStop` ratio (e.g. `\"0.1\"` = 10%)\n","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"condition":{"type":"string","description":"Trigger price — bot starts only when price crosses this level (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"slippage":{"type":"string","description":"Open position slippage tolerance (e.g. \"0.01\" = 1%)"},"closeSellModel":{"type":"string","description":"Close sell mode on cancellation:\n`NOT_SELL` - Keep base+quote as-is, do not sell (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"],"default":"NOT_SELL"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SpotGridOrder":{"type":"object","description":"Spot grid bot order (wraps OrderResult with GridV5OrderData)","properties":{"buOrderType":{"type":"string","description":"Order type (always `grid_v5` for spot grid)"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"note":{"type":"string","description":"Order note"},"buOrderData":{"$ref":"#/components/schemas/SpotGridOrderData"}}},"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/create":{"post":{"tags":["Spot Grid"],"summary":"Create spot grid order","description":"Create a new spot grid bot order. Weight: 1.","operationId":"createSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSpotGridRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check spot grid parameters > Validate spot grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\ > \ > Pass a positive \`quote\_total\_investment\` to receive full estimate fields.\ > The current market price is fetched automatically — \`open\_price\` is not required.\ > \ > \*\*FailedWithData\*\*: For errors marked "Yes" below, the response includes a \`data\` field\ > even when \`result=false\`, containing \`min\_investment\`, \`max\_investment\`, and \`slippage\`\ > so the client can display the valid investment range.\ > \ > \*\*Validation error messages\*\* (returned in \`message\` when \`result\` is \`false\`):\ > \ > \| Message | Cause | Includes data |\ > \|---|---|---|\ > \| \`number invalid: {value}\` | \`top\` or \`bottom\` is not a valid numeric string | No |\ > \| \`number int too long: {value}\` | Integer part of \`top\` or \`bottom\` exceeds 15 digits | No |\ > \| \`number decimal too long: {value}\` | Decimal part of \`top\` or \`bottom\` exceeds 15 digits | No |\ > \| \`invalid quote total investment\` | \`quote\_total\_investment\` must be >= 0 | No |\ > \| \`bottom must be less than top\` | \`bottom\` must be strictly less than \`top\` | No |\ > \| \`row must be between 2 and 1000\` | \`row\` must be in the range \[2, 1000] | No |\ > \| \`invalid grid\_type\` | \`grid\_type\` must be \`arithmetic\` or \`geometric\` | No |\ > \| \`grid price duplicated: reduce row or widen range\` | Grid range too narrow or \`row\` too large — adjacent grid prices are identical | Yes |\ > \| \`quote\_total\_investment not match quote precision: max {N} decimal places\` | \`quote\_total\_investment\` exceeds the allowed decimal precision | Yes |\ > \| \`less than min investment\` | \`quote\_total\_investment\` is \`"0"\` or less than \`min\_investment\` | Yes |
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CheckSpotGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckSpotGridParamsOrderData"}}},"CheckSpotGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","quote_total_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be a valid numeric string, strictly greater than `bottom`."},"bottom":{"type":"string","description":"Grid lower price. Must be a valid numeric string."},"row":{"type":"integer","description":"Number of grid levels (2–1000).","minimum":2,"maximum":1000},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quote_total_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SpotGridCheckParamsData":{"type":"object","description":"Spot grid parameter check result data.\n\n**When result=true**: All fields are populated.\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"grid price duplicated: reduce row or widen range\"`,\n`\"quote_total_investment not match quote precision: max {N} decimal places\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum investment amount in quote currency"},"max_investment":{"type":"string","description":"Maximum investment amount in quote currency"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_fee":{"type":"string","description":"Estimated opening trading fee."}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/checkParams":{"post":{"tags":["Spot Grid"],"summary":"Check spot grid parameters","description":"Validate spot grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\n\nPass a positive `quote_total_investment` to receive full estimate fields.\nThe current market price is fetched automatically — `open_price` is not required.\n\n**FailedWithData**: For errors marked \"Yes\" below, the response includes a `data` field\neven when `result=false`, containing `min_investment`, `max_investment`, and `slippage`\nso the client can display the valid investment range.\n\n**Validation error messages** (returned in `message` when `result` is `false`):\n\n| Message | Cause | Includes data |\n|---|---|---|\n| `number invalid: {value}` | `top` or `bottom` is not a valid numeric string | No |\n| `number int too long: {value}` | Integer part of `top` or `bottom` exceeds 15 digits | No |\n| `number decimal too long: {value}` | Decimal part of `top` or `bottom` exceeds 15 digits | No |\n| `invalid quote total investment` | `quote_total_investment` must be >= 0 | No |\n| `bottom must be less than top` | `bottom` must be strictly less than `top` | No |\n| `row must be between 2 and 1000` | `row` must be in the range [2, 1000] | No |\n| `invalid grid_type` | `grid_type` must be `arithmetic` or `geometric` | No |\n| `grid price duplicated: reduce row or widen range` | Grid range too narrow or `row` too large — adjacent grid prices are identical | Yes |\n| `quote_total_investment not match quote precision: max {N} decimal places` | `quote_total_investment` exceeds the allowed decimal precision | Yes |\n| `less than min investment` | `quote_total_investment` is `\"0\"` or less than `min_investment` | Yes |\n","operationId":"checkSpotGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckSpotGridParamsRequest"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridCheckParamsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Adjust spot grid parameters > Modify grid range (top/bottom/row) or adjust investment for a running spot grid order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"AdjustSpotGridParamsRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"New grid upper price"},"bottom":{"type":"string","description":"New grid lower price"},"row":{"type":"integer","format":"int32","description":"New number of grid levels"},"quoteInvest":{"type":"string","description":"Additional quote investment amount"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/adjustParams":{"post":{"tags":["Spot Grid"],"summary":"Adjust spot grid parameters","description":"Modify grid range (top/bottom/row) or adjust investment for a running spot grid order. Weight: 1.","operationId":"adjustSpotGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustSpotGridParamsRequest"}}}},"responses":{"200":{"description":"Adjustment applied successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"action_id":{"type":"string","description":"Adjustment action ID"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Add investment to spot grid > Add additional investment to a running spot grid order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"InvestInSpotGridRequest":{"type":"object","required":["buOrderId","quoteInvest"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"quoteInvest":{"type":"string","description":"Additional investment amount in quote currency"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/investIn":{"post":{"tags":["Spot Grid"],"summary":"Add investment to spot grid","description":"Add additional investment to a running spot grid order. Weight: 1.","operationId":"investInSpotGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestInSpotGridRequest"}}}},"responses":{"200":{"description":"Investment added successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"action_id":{"type":"string","description":"Investment action ID"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel spot grid order > Close and cancel a spot grid bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CancelSpotGridRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeSellModel":{"type":"string","description":"Close sell mode set at creation:\n`NOT_SELL` - Keep base+quote as-is (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/cancel":{"post":{"tags":["Spot Grid"],"summary":"Cancel spot grid order","description":"Close and cancel a spot grid bot order. Weight: 1.","operationId":"cancelSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSpotGridRequest"}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Extract profit from spot grid > Extract accumulated grid profit from a running spot grid order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ProfitSpotGridRequest":{"type":"object","required":["buOrderId","amount"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"string","description":"Amount to extract"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"TransferRecord":{"type":"object","description":"Record of a profit extraction transfer","properties":{"transferId":{"type":"string","description":"Transfer ID"},"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Transfer type (e.g. `profit`)"},"direction":{"type":"string","description":"Transfer direction: `out` (extract from bot)"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"string","description":"Transfer amount"},"amountC":{"type":"string","description":"Transfer amount in platform currency"},"status":{"type":"string","description":"Transfer status"},"createTime":{"type":"integer","format":"int64","description":"Transfer timestamp in milliseconds"},"error":{"type":"string","description":"Error message (if failed)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/spotGrid/profit":{"post":{"tags":["Spot Grid"],"summary":"Extract profit from spot grid","description":"Extract accumulated grid profit from a running spot grid order. Weight: 1.","operationId":"profitSpotGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfitSpotGridRequest"}}}},"responses":{"200":{"description":"Profit extracted successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransferRecord"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Smart Copy Smart Copy Bot management (private) ## Get smart copy order > Query a smart copy bot order by ID. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Smart Copy","description":"Smart Copy Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SmartCopyOrderDetail":{"type":"object","description":"Smart copy bot order detail","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"buOrderType":{"type":"string","description":"Bot order type (always `smart_copy`)"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Source order ID (for copy trade orders)"},"copyType":{"type":"string","description":"Copy type"},"strategyId":{"type":"string","description":"Strategy ID"},"canceling":{"type":"integer","format":"int64","description":"Canceling flag"},"note":{"type":"string","description":"Order note"},"closeNote":{"type":"string","description":"Close note"},"customizeName":{"type":"string","description":"Custom name"},"buOrderData":{"$ref":"#/components/schemas/SmartCopyOrderData"}}},"SmartCopyOrderData":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"kolSignalId":{"type":"string","description":"KOL signal ID"},"quoteTotalInvestment":{"type":"string","description":"Current total investment in quote currency"},"quoteOriginalInvestment":{"type":"string","description":"Original investment amount in quote currency"},"currentQuoteAmount":{"type":"string","description":"Current quote amount in the bot account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"convertIntoEarnCoin":{"type":"integer","format":"int64","description":"Whether assets were converted to earn coin on close"},"reasonBy":{"type":"string","description":"Close reason (e.g. `user_cancel`, `create_failed`)"},"profit":{"type":"string","description":"Total profit in quote currency"},"status":{"type":"string","description":"Order data status"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Total profit shared"},"closedSharedQuote":{"type":"string","description":"Quote amount deducted for profit sharing on close"},"tradeType":{"type":"string","description":"Trade type: `futures` or `spot`","enum":["futures","spot"]},"fundingFee":{"type":"string","description":"Total funding fee paid"},"roundCount24h":{"type":"integer","format":"int64","description":"Number of completed signal rounds in the last 24 hours"},"kolName":{"type":"string","description":"KOL name"},"kolImage":{"type":"string","description":"KOL avatar URL"},"signalName":{"type":"string","description":"Signal display name"},"market":{"type":"string","description":"Market type"},"portfolio":{"type":"array","description":"Portfolio item details","items":{"$ref":"#/components/schemas/SmartCopyPortfolioItem"}}}},"SmartCopyPortfolioItem":{"type":"object","properties":{"tradeBase":{"type":"string","description":"Actual trading base currency"},"buOrderId":{"type":"string","description":"Bot order ID"},"base":{"type":"string","description":"Base currency for this portfolio item"},"signalType":{"type":"string","description":"Signal type identifier"},"signalParam":{"type":"string","description":"Signal parameters"},"percent":{"type":"string","description":"Allocation percentage"},"initPrice":{"type":"string","description":"Price at position open"},"closedPrice":{"type":"string","description":"Price at position close"},"currentBaseAmount":{"type":"string","description":"Current base amount held"},"closedBaseAmount":{"type":"string","description":"Base amount returned on close"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"totalFeeInBase":{"type":"string","description":"Total trading fees in base currency"},"totalFeeInQuote":{"type":"string","description":"Total trading fees in quote currency"},"profit":{"type":"string","description":"Profit for this portfolio item"},"roundCount":{"type":"integer","format":"int64","description":"Total completed signal rounds"},"currentRound":{"type":"integer","format":"int64","description":"Current signal round number"},"currentRoundMonth":{"type":"string","description":"Current round month label"},"status":{"type":"string","description":"Portfolio item status"},"expiredAt":{"type":"integer","format":"int64","description":"Expiry timestamp in milliseconds (0 = no expiry)"},"sharedAmount":{"type":"string","description":"Profit sharing amount for this item"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier"},"fundingFee":{"type":"string","description":"Funding fee for this item"},"qtyLong":{"type":"string","description":"Long position quantity"},"qtyShort":{"type":"string","description":"Short position quantity"},"amountLong":{"type":"string","description":"Long position amount in quote"},"amountShort":{"type":"string","description":"Short position amount in quote"},"amountSettle":{"type":"string","description":"Settlement amount"},"maintPrice":{"type":"string","description":"Maintenance margin price"},"profitRoundCount":{"type":"integer","format":"int64","description":"Number of profitable rounds"},"profitPositive":{"type":"string","description":"Total positive profit accumulated"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/smartCopy/order":{"get":{"tags":["Smart Copy"],"summary":"Get smart copy order","description":"Query a smart copy bot order by ID. Weight: 1.","operationId":"getSmartCopyOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"buOrderId","in":"query","required":true,"description":"Bot order ID (UUID, 36 chars)","schema":{"type":"string"}},{"name":"lang","in":"query","description":"Language code (e.g. en, zh)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SmartCopyOrderDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Check smart copy parameters > Validate smart copy bot creation parameters and check the maximum investment limit. Weight: 1.\ > \ > \*\*Requires \`Bot reading\` permission.\*\*\ > \ > Returns the maximum allowed investment, maximum leverage, and notional/available limits for the given base/quote/signal combination.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Smart Copy","description":"Smart Copy Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CheckSmartCopyParamsRequest":{"type":"object","required":["base","quote","leverage","quote_investment"],"properties":{"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"signal_type":{"type":"string","description":"Signal type identifier. Optional — omit to check without a specific signal."},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier (>= 1)","minimum":1},"quote_investment":{"type":"string","description":"Investment amount in quote currency to check against limits."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"CheckSmartCopyParamsData":{"type":"object","description":"Smart copy parameter check result data.","properties":{"result":{"type":"boolean","description":"Whether the investment is within limits"},"max_investment":{"type":"string","description":"Maximum allowed investment amount in quote currency"},"max_leverage":{"type":"string","description":"Maximum allowed leverage"},"notional_limit":{"type":"string","description":"Total notional limit (quote_investment * leverage ceiling)"},"available_limit":{"type":"string","description":"Remaining available notional for this base/quote/signal combination"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/smartCopy/checkParams":{"post":{"tags":["Smart Copy"],"summary":"Check smart copy parameters","description":"Validate smart copy bot creation parameters and check the maximum investment limit. Weight: 1.\n\n**Requires `Bot reading` permission.**\n\nReturns the maximum allowed investment, maximum leverage, and notional/available limits for the given base/quote/signal combination.\n","operationId":"checkSmartCopyParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckSmartCopyParamsRequest"}}}},"responses":{"200":{"description":"Check result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CheckSmartCopyParamsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Create smart copy order > Create a new smart copy bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Smart Copy","description":"Smart Copy Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateSmartCopyOrderRequest":{"type":"object","required":["base","quote","bu_order_data"],"properties":{"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"key_id":{"type":"string","description":"API Key ID. Optional — derived from the API key used for authentication when omitted."},"note":{"type":"string","description":"Optional order note"},"copy_from":{"type":"string","description":"Source order ID to copy from (for copy trade orders)"},"copy_type":{"type":"string","description":"Copy type identifier"},"bu_order_data":{"$ref":"#/components/schemas/CreateSmartCopyOrderBuOrderData"}}},"CreateSmartCopyOrderBuOrderData":{"type":"object","required":["quote_total_investment","portfolio"],"properties":{"quote_total_investment":{"type":"string","description":"Total investment amount in quote currency"},"compound":{"type":"boolean","description":"Whether to enable compound interest (reinvest profits)","default":false},"profit_stop_maker":{"type":"boolean","description":"Whether to enable profit stop maker","default":false},"portfolio":{"type":"array","description":"List of portfolio items (at least 1 required)","minItems":1,"items":{"$ref":"#/components/schemas/SmartCopyPortfolioItemRequest"}}}},"SmartCopyPortfolioItemRequest":{"type":"object","required":["base","signal_type","leverage"],"properties":{"base":{"type":"string","description":"Base currency for this portfolio item"},"signal_type":{"type":"string","description":"Signal type identifier"},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"percent":{"type":"string","description":"Allocation percentage of total investment for this item (e.g. \"1\" = 100%)"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier for this item (>= 1)","minimum":1},"profit_stop_ratio":{"type":"string","description":"Take profit ratio (e.g. \"0.5\" = 50% profit triggers close)"},"loss_stop_ratio":{"type":"string","description":"Stop loss ratio (e.g. \"-0.2\" = 20% loss triggers close)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"CreateSmartCopyOrderResponse":{"type":"object","properties":{"bu_order_id":{"type":"string","description":"Created bot order ID"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/smartCopy/create":{"post":{"tags":["Smart Copy"],"summary":"Create smart copy order","description":"Create a new smart copy bot order. Weight: 1.","operationId":"createSmartCopyOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSmartCopyOrderRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreateSmartCopyOrderResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Cancel smart copy order > Close and cancel a smart copy bot order. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Smart Copy","description":"Smart Copy Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CancelSmartCopyOrderRequest":{"type":"object","required":["bu_order_id"],"properties":{"bu_order_id":{"type":"string","description":"Bot order ID to cancel"},"close_note":{"type":"string","description":"Optional close reason note"},"convert_into_earn_coin":{"type":"boolean","description":"Whether to convert remaining assets into earn coin on close","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"CancelSmartCopyOrderResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the cancellation was accepted"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/smartCopy/cancel":{"post":{"tags":["Smart Copy"],"summary":"Cancel smart copy order","description":"Close and cancel a smart copy bot order. Weight: 1.","operationId":"cancelSmartCopyOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSmartCopyOrderRequest"}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CancelSmartCopyOrderResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Signal Custom signal listener and user-defined signal management (private) ## Push custom trading signal > Push a custom trading signal to drive smart copy orders. Weight: 1.\ > \ > \*\*Requires \`Enable trading\` permission.\*\*
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"SignalListenerRequest":{"type":"object","required":["signalType","signalParam","base","quote","time","price","data"],"properties":{"signalType":{"type":"string","description":"Signal type identifier (ASCII, max 1000 chars)"},"signalParam":{"type":"string","description":"Signal parameters (ASCII, max 5000 chars)"},"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"time":{"type":"string","format":"date-time","description":"Signal trigger time (RFC3339)"},"price":{"type":"string","description":"Price at signal trigger time (ASCII, max 30 chars)"},"data":{"$ref":"#/components/schemas/SignalListenerData"}}},"SignalListenerData":{"type":"object","required":["action","position_size","contracts"],"properties":{"action":{"type":"string","description":"Trading action","enum":["buy","sell"]},"position_size":{"type":"string","description":"Position size as a ratio or absolute value"},"contracts":{"type":"string","description":"Number of contracts"},"direction":{"type":"string","description":"Optional trading direction hint"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/listener":{"post":{"tags":["Signal"],"summary":"Push custom trading signal","description":"Push a custom trading signal to drive smart copy orders. Weight: 1.\n\n**Requires `Enable trading` permission.**\n","operationId":"signalListener","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalListenerRequest"}}}},"responses":{"200":{"description":"Signal received successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## List user custom signals > Return a paginated list of user-defined signals. Weight: 1.\ > \ > \*\*Requires \`Bot reading\` permission.\*\*
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalListResponse":{"type":"object","properties":{"pageToken":{"type":"string","description":"Pagination token for the next page. Empty string when there are no more results."},"signals":{"type":"array","description":"List of user-defined signals","items":{"$ref":"#/components/schemas/UserSignalDetail"}}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal":{"get":{"tags":["Signal"],"summary":"List user custom signals","description":"Return a paginated list of user-defined signals. Weight: 1.\n\n**Requires `Bot reading` permission.**\n","operationId":"listUserSignals","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"pageToken","in":"query","required":false,"description":"Pagination token returned by the previous response. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal list retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalListResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Create user custom signal > Create a new user-defined signal. Each user can have at most 100 signals. Weight: 1.\ > \ > \*\*Requires \`Bot trading\` permission.\*\*
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateUserSignalRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"Signal description (max 1000 chars)","maxLength":1000}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal":{"post":{"tags":["Signal"],"summary":"Create user custom signal","description":"Create a new user-defined signal. Each user can have at most 100 signals. Weight: 1.\n\n**Requires `Bot trading` permission.**\n","operationId":"createUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserSignalRequest"}}}},"responses":{"200":{"description":"Signal created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get user custom signal detail > Return detail of a specific user-defined signal including webhook URL and message template. Weight: 1.\ > \ > \*\*Requires \`Bot reading\` permission.\*\*
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/detail":{"get":{"tags":["Signal"],"summary":"Get user custom signal detail","description":"Return detail of a specific user-defined signal including webhook URL and message template. Weight: 1.\n\n**Requires `Bot reading` permission.**\n","operationId":"getUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal detail retrieved successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSignalDetail"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Edit user custom signal > Update the title and/or description of an existing user-defined signal. Weight: 1.\ > \ > \*\*Requires \`Bot trading\` permission.\*\*\ > \ > At least one of \`title\` or \`description\` must be provided.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"EditUserSignalRequest":{"type":"object","description":"At least one field must be provided.","properties":{"title":{"type":"string","description":"New signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"New signal description (max 10000 chars)","maxLength":10000}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/edit":{"post":{"tags":["Signal"],"summary":"Edit user custom signal","description":"Update the title and/or description of an existing user-defined signal. Weight: 1.\n\n**Requires `Bot trading` permission.**\n\nAt least one of `title` or `description` must be provided.\n","operationId":"editUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditUserSignalRequest"}}}},"responses":{"200":{"description":"Signal updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Delete user custom signal > Delete a user-defined signal. Weight: 1.\ > \ > \*\*Requires \`Bot trading\` permission.\*\*\ > \ > Deletion is rejected if the signal has any non-cancelled orders. Error code \`SIGNAL\_HAS\_UNCLOSED\_ORDERS\` is returned with the open order count in \`data.cnt\`.
```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Signal","description":"Custom signal listener and user-defined signal management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/signal/userSignal/delete":{"delete":{"tags":["Signal"],"summary":"Delete user custom signal","description":"Delete a user-defined signal. Weight: 1.\n\n**Requires `Bot trading` permission.**\n\nDeletion is rejected if the signal has any non-cancelled orders. Error code `SIGNAL_HAS_UNCLOSED_ORDERS` is returned with the open order count in `data.cnt`.\n","operationId":"deleteUserSignal","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"signalType","in":"query","required":true,"description":"Signal type identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Signal deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"Bad request or unclosed orders exist","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"cnt":{"type":"integer","description":"Number of unclosed orders preventing deletion"}}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # KOL KOL data endpoints (private) ## Get KOL curated copy-trade order list > Query a KOL's curated/pinned copy-trade order list by share code, with optional filters by symbol, trend, and leverage. Supports pagination and sorting. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"KOL","description":"KOL data endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"KolSelectCopyTradeListData":{"type":"object","description":"KOL curated copy-trade order list response","properties":{"total":{"type":"integer","format":"int64","description":"Total number of matching orders"},"page":{"type":"integer","format":"int64","description":"Current page number"},"hasMore":{"type":"boolean","description":"Whether more pages are available"},"filterOptions":{"$ref":"#/components/schemas/KolFilterOptions"},"kolInfo":{"$ref":"#/components/schemas/KolInfo"},"results":{"type":"array","description":"Curated copy-trade orders","items":{"$ref":"#/components/schemas/KolCopyTradeOrder"}},"topResults":{"type":"array","description":"Pinned/top copy-trade orders","items":{"$ref":"#/components/schemas/KolCopyTradeOrder"}}}},"KolFilterOptions":{"type":"object","description":"Available filter options for the KOL's orders","properties":{"symbolList":{"type":"array","description":"Available symbol filters","items":{"type":"string"}},"leverageList":{"type":"array","description":"Available leverage filters","items":{"type":"integer","format":"int64"}},"trendList":{"type":"array","description":"Available trend filters","items":{"type":"string"}}}},"KolInfo":{"type":"object","description":"KOL profile information","properties":{"nickname":{"type":"string","description":"KOL nickname"},"shareCode":{"type":"string","description":"KOL share code"},"headerImg":{"type":"string","description":"KOL header image URL"},"isShowInvestment":{"type":"boolean","description":"Whether investment amounts are shown"},"avatar":{"type":"string","description":"KOL avatar URL"},"userId":{"type":"string","description":"KOL user ID"},"isShowGroupEntry":{"type":"integer","format":"int64","description":"Whether the group entry is shown"},"groupInfoList":{"type":"array","description":"KOL community group list","items":{"$ref":"#/components/schemas/KolGroupInfo"}}}},"KolGroupInfo":{"type":"object","description":"KOL community group info","properties":{"id":{"type":"integer","format":"int64","description":"Group ID"},"userId":{"type":"string","description":"KOL user ID"},"community":{"type":"string","description":"Community name"},"rank":{"type":"integer","format":"int64","description":"Group rank"},"link":{"type":"string","description":"Community link"},"createTime":{"type":"string","description":"Creation time (RFC3339)"},"updateTime":{"type":"string","description":"Update time (RFC3339)"},"picUrl":{"type":"string","description":"Community picture URL"}}},"KolCopyTradeOrder":{"type":"object","description":"A KOL curated copy-trade order entry","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"buOrderType":{"type":"string","description":"Bot order type"},"rank":{"type":"integer","format":"int64","description":"Order rank"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"uniqueId":{"type":"string","description":"Unique identifier"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"isTop":{"type":"boolean","description":"Whether the order is pinned/top"},"buOrderData":{"$ref":"#/components/schemas/KolCopyTradeOrderData"}}},"KolCopyTradeOrderData":{"type":"object","description":"KOL copy-trade order detail data","properties":{"quoteInvestment":{"type":"string","description":"Investment amount in quote currency"},"extraMargin":{"type":"string","description":"Extra margin amount"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"gridApr":{"type":"string","description":"Grid APR"},"trend":{"type":"string","description":"Grid direction (e.g. long, short, no_trend)"},"leverage":{"type":"string","description":"Leverage multiplier"},"initPrice":{"type":"string","description":"Price at order creation"},"curPrice":{"type":"string","description":"Current price"},"rota":{"type":"string","description":"Return on total assets"},"uiExtraData":{"type":"string","description":"Frontend extra data"},"triggerTime":{"type":"integer","format":"int64","description":"Trigger timestamp in milliseconds"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/kol/selectCopyTradeList":{"get":{"tags":["KOL"],"summary":"Get KOL curated copy-trade order list","description":"Query a KOL's curated/pinned copy-trade order list by share code, with optional filters by symbol, trend, and leverage. Supports pagination and sorting. Weight: 1.","operationId":"getKolSelectCopyTradeList","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"shareCode","in":"query","required":true,"description":"KOL share code","schema":{"type":"string"}},{"name":"buOrderType","in":"query","required":true,"description":"Bot order type filter","schema":{"type":"string"}},{"name":"symbol","in":"query","description":"Trading symbol filter","schema":{"type":"string"}},{"name":"trend","in":"query","description":"Grid trend filter (e.g. long, short, no_trend)","schema":{"type":"string"}},{"name":"leverage","in":"query","description":"Leverage filter","schema":{"type":"integer","format":"int64"}},{"name":"pageToken","in":"query","description":"Pagination token","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort field","schema":{"type":"string"}},{"name":"direction","in":"query","description":"Sort direction (e.g. asc, desc)","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size","schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KolSelectCopyTradeListData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}}}} ``` ## The BotOrderListResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"BotOrderListResponse":{"type":"object","description":"Bot order list response with pagination","properties":{"nextPageToken":{"type":"string","nullable":true,"description":"Token to fetch the next page"},"previousPageToken":{"type":"string","nullable":true,"description":"Token to fetch the previous page"},"results":{"type":"array","description":"List of bot orders","items":{"$ref":"#/components/schemas/BotOrder"}}}},"BotOrder":{"type":"object","description":"Bot order result","properties":{"buOrderType":{"type":"string","description":"Bot order type. Supported values: `futures_grid`, `future_hedge_grid` (Cross Margin Futures Grid), `spot_grid`, `smart_copy`.\n"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"strategyId":{"type":"string","description":"Strategy ID"},"canceling":{"type":"integer","format":"int64","description":"Canceling flag"},"note":{"type":"string","description":"Order note"},"closeNote":{"type":"string","description":"Close note"},"customizeName":{"type":"string","description":"Custom name"},"botName":{"type":"string","description":"Bot name"},"groupId":{"type":"string","description":"Group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"buOrderData":{"type":"object","description":"Order detail data. The structure depends on `buOrderType`:\n`futures_grid` -> `FuturesGridOrderData`,\n`future_hedge_grid` -> `FutureHedgeGridOrderData`,\n`spot_grid` -> `SpotGridOrderData`,\n`smart_copy` -> `SmartCopyOrderData`\n"}}}}}} ``` ## The BotOrder object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"BotOrder":{"type":"object","description":"Bot order result","properties":{"buOrderType":{"type":"string","description":"Bot order type. Supported values: `futures_grid`, `future_hedge_grid` (Cross Margin Futures Grid), `spot_grid`, `smart_copy`.\n"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"strategyId":{"type":"string","description":"Strategy ID"},"canceling":{"type":"integer","format":"int64","description":"Canceling flag"},"note":{"type":"string","description":"Order note"},"closeNote":{"type":"string","description":"Close note"},"customizeName":{"type":"string","description":"Custom name"},"botName":{"type":"string","description":"Bot name"},"groupId":{"type":"string","description":"Group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"buOrderData":{"type":"object","description":"Order detail data. The structure depends on `buOrderType`:\n`futures_grid` -> `FuturesGridOrderData`,\n`future_hedge_grid` -> `FutureHedgeGridOrderData`,\n`spot_grid` -> `SpotGridOrderData`,\n`smart_copy` -> `SmartCopyOrderData`\n"}}}}}} ``` ## The FuturesGridOrder object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridOrder":{"type":"object","properties":{"keyId":{"type":"string","description":"API Key ID"},"userId":{"type":"string","description":"User ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"number","description":"Creation timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"groupId":{"type":"string","description":"Bound group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"note":{"type":"string","description":"Note"},"customizeName":{"type":"string","description":"Custom name"},"buOrderData":{"$ref":"#/components/schemas/FuturesGridOrderData"}}},"FuturesGridOrderData":{"type":"object","properties":{"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `condition_lock`, `open_position`, `init_grid`,\n`running`, `destroy_grid`, `close_position`, `unlock_currency`, `canceled`,\n`adjust_params`, `adjust_params_open_position`, `adjust_params_init_grid`,\n`pre_pause`, `pausing`, `paused`, `pre_resume`, `resuming`\n","enum":["prepare","lock_currency","condition_lock","open_position","init_grid","running","destroy_grid","close_position","unlock_currency","canceled","adjust_params","adjust_params_open_position","adjust_params_init_grid","pre_pause","pausing","paused","pre_resume","resuming"]},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel` - User cancelled,\n`force_liquidation` - Liquidated,\n`loss_stop` - Stop loss triggered,\n`profit_stop` - Take profit triggered,\n`not_enough_balance` - Insufficient balance during running,\n`not_enough_balance_when_lock` - Lock funds failed after order,\n`create_failed` - Order creation failed\n","enum":["user_cancel","force_liquidation","loss_stop","profit_stop","not_enough_balance","not_enough_balance_when_lock","create_failed"]},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Current price at creation"},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"type":{"type":"string","description":"Operation type (e.g. `invest_in` for adding investment)"},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Total investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraBalance":{"type":"string","description":"Extra balance"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated liquidation price (upward)"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated liquidation price (downward)"},"lossStopType":{"type":"string","description":"Stop loss type:\n`price` - By market price (default),\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`price` -> stop loss price,\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`price` - By price (default),\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`price` -> take profit price,\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"riskStatus":{"type":"string","description":"Risk status","enum":["TRADING","HOLDING","TAKEOVER","LIQUIDATION"],"default":"TRADING"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitWithdrawn":{"type":"string","description":"Total profit withdrawn"},"openQuotePrice":{"type":"string","description":"Average quote-to-USDT price for investment"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only,\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"quoteAmountBeforeSell":{"type":"string","description":"Quote amount before closing"},"quoteAmountSell":{"type":"string","description":"Quote amount sold on close"},"quoteSellPrice":{"type":"string","description":"Quote sell price on close"},"unlockUsdtAmount":{"type":"string","description":"USDT returned to main account (only when TO_USDT)"},"unlockQuoteAmount":{"type":"string","description":"Quote returned to main account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Shared profit amount"},"marginStatus":{"type":"string","description":"Margin status: `NORMAL` or `INSUFFICIENT`","enum":["NORMAL","INSUFFICIENT"],"default":"NORMAL"},"investCoin":{"type":"string","description":"Investment currency. `USDT` or quote currency (e.g. BTC)"},"investmentFrom":{"type":"string","description":"Funding source:\n`USER` - User main account,\n`LOCK_ACTIVITY` - Lock activity pool,\n`FUTURE_GRID_BONUS` - Bonus pool\n","enum":["USER","LOCK_ACTIVITY","FUTURE_GRID_BONUS"]},"lockEndTime":{"type":"number","description":"Lock end time in milliseconds"},"profitWithdrawnU":{"type":"string","description":"Profit withdrawn (user portion)"},"profitWithdrawnC":{"type":"string","description":"Profit withdrawn (charity/bonus portion)"},"profitWithdrawnP":{"type":"string","description":"Profit withdrawn (Pionex/bonus fee portion)"},"usdtInvestment":{"type":"string","description":"USDT investment amount"},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"stopLossEnabled":{"type":"boolean","description":"Stop loss enabled while paused"},"stopProfitEnabled":{"type":"boolean","description":"Take profit enabled while paused"},"triggerPausePriceUp":{"type":"string","description":"Price trigger for pause (upward)"},"triggerPausePriceDown":{"type":"string","description":"Price trigger for pause (downward)"},"triggerResumePriceUp":{"type":"string","description":"Price trigger for resume (upward), set via the resume endpoint"},"triggerResumePriceDown":{"type":"string","description":"Price trigger for resume (downward), set via the resume endpoint"},"profitReduce":{"type":"string","description":"Grid profit from position reduction (accumulated)"},"closeOrderType":{"type":"string","description":"Close order type:\n`market` - Market price close,\n`limit` - Limit price close,\n`limit_high` - Neutral grid top limit close\n","enum":["market","limit","limit_high"]},"closedBaseAmount":{"type":"string","description":"Closed position amount"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"bonusBackUsdt":{"type":"string","description":"USDT recovered from bonus on close"},"bonusBackQuote":{"type":"string","description":"Quote recovered from bonus on close"},"notionalStatus":{"type":"string","description":"Notional status: `NORMAL` or `NOTIONAL_LIMIT`","enum":["NORMAL","NOTIONAL_LIMIT"],"default":"NORMAL"},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"},"bonusFeeRatio":{"type":"string","description":"Bonus fee ratio (e.g. \"0.2\" = 20%)"},"bonusFee":{"type":"string","description":"Bonus management fee recovered on close (in quote)"},"disableChangeTp":{"type":"boolean","description":"Whether modification of take profit is disabled"},"disableInvestInTrigger":{"type":"boolean","description":"Whether trigger investment is disabled"},"investInTriggers":{"type":"array","description":"Pending trigger investment list (max 1 item)","items":{"$ref":"#/components/schemas/InvestInTrigger"}},"investOutTriggers":{"type":"array","description":"Pending trigger reduction list (max 1 item)","items":{"$ref":"#/components/schemas/InvestOutTrigger"}},"autoExpiredTime":{"type":"number","description":"Auto-close timestamp in milliseconds (for bonus orders)"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type:\n`FUTURES_MOON` - Futures moon order,\n`FULLY_HEDGING` - Fully hedged order,\n`LOAN_GRID` - Loan grid,\n`LEVERAGE_GRID` - Leverage grid,\n`FUTURE_GRID_COIN_MARGINED` - Coin-margined futures grid\n","enum":["FUTURES_MOON","FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"profitExited":{"type":"string","description":"Exited profit"},"fundingFeePayment":{"type":"string","description":"Total funding fee paid (negative value)"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close (requires original order to enable follow close)"}}},"InvestInTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger investment price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"quoteInvestment":{"type":"string","description":"Trigger investment amount"},"extraMarginAmount":{"type":"string","description":"Trigger dynamic margin"},"addTime":{"type":"number","description":"Add time in milliseconds"},"investCoin":{"type":"string","description":"Investment currency (currently only supports quote)"}}},"InvestOutTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger reduction price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"addTime":{"type":"number","description":"Add time in milliseconds"}}}}}} ``` ## The FuturesGridOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridOrderData":{"type":"object","properties":{"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `condition_lock`, `open_position`, `init_grid`,\n`running`, `destroy_grid`, `close_position`, `unlock_currency`, `canceled`,\n`adjust_params`, `adjust_params_open_position`, `adjust_params_init_grid`,\n`pre_pause`, `pausing`, `paused`, `pre_resume`, `resuming`\n","enum":["prepare","lock_currency","condition_lock","open_position","init_grid","running","destroy_grid","close_position","unlock_currency","canceled","adjust_params","adjust_params_open_position","adjust_params_init_grid","pre_pause","pausing","paused","pre_resume","resuming"]},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel` - User cancelled,\n`force_liquidation` - Liquidated,\n`loss_stop` - Stop loss triggered,\n`profit_stop` - Take profit triggered,\n`not_enough_balance` - Insufficient balance during running,\n`not_enough_balance_when_lock` - Lock funds failed after order,\n`create_failed` - Order creation failed\n","enum":["user_cancel","force_liquidation","loss_stop","profit_stop","not_enough_balance","not_enough_balance_when_lock","create_failed"]},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Current price at creation"},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"type":{"type":"string","description":"Operation type (e.g. `invest_in` for adding investment)"},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Total investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraBalance":{"type":"string","description":"Extra balance"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated liquidation price (upward)"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated liquidation price (downward)"},"lossStopType":{"type":"string","description":"Stop loss type:\n`price` - By market price (default),\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`price` -> stop loss price,\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`price` - By price (default),\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`price` -> take profit price,\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"riskStatus":{"type":"string","description":"Risk status","enum":["TRADING","HOLDING","TAKEOVER","LIQUIDATION"],"default":"TRADING"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitWithdrawn":{"type":"string","description":"Total profit withdrawn"},"openQuotePrice":{"type":"string","description":"Average quote-to-USDT price for investment"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only,\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"quoteAmountBeforeSell":{"type":"string","description":"Quote amount before closing"},"quoteAmountSell":{"type":"string","description":"Quote amount sold on close"},"quoteSellPrice":{"type":"string","description":"Quote sell price on close"},"unlockUsdtAmount":{"type":"string","description":"USDT returned to main account (only when TO_USDT)"},"unlockQuoteAmount":{"type":"string","description":"Quote returned to main account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Shared profit amount"},"marginStatus":{"type":"string","description":"Margin status: `NORMAL` or `INSUFFICIENT`","enum":["NORMAL","INSUFFICIENT"],"default":"NORMAL"},"investCoin":{"type":"string","description":"Investment currency. `USDT` or quote currency (e.g. BTC)"},"investmentFrom":{"type":"string","description":"Funding source:\n`USER` - User main account,\n`LOCK_ACTIVITY` - Lock activity pool,\n`FUTURE_GRID_BONUS` - Bonus pool\n","enum":["USER","LOCK_ACTIVITY","FUTURE_GRID_BONUS"]},"lockEndTime":{"type":"number","description":"Lock end time in milliseconds"},"profitWithdrawnU":{"type":"string","description":"Profit withdrawn (user portion)"},"profitWithdrawnC":{"type":"string","description":"Profit withdrawn (charity/bonus portion)"},"profitWithdrawnP":{"type":"string","description":"Profit withdrawn (Pionex/bonus fee portion)"},"usdtInvestment":{"type":"string","description":"USDT investment amount"},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"stopLossEnabled":{"type":"boolean","description":"Stop loss enabled while paused"},"stopProfitEnabled":{"type":"boolean","description":"Take profit enabled while paused"},"triggerPausePriceUp":{"type":"string","description":"Price trigger for pause (upward)"},"triggerPausePriceDown":{"type":"string","description":"Price trigger for pause (downward)"},"triggerResumePriceUp":{"type":"string","description":"Price trigger for resume (upward), set via the resume endpoint"},"triggerResumePriceDown":{"type":"string","description":"Price trigger for resume (downward), set via the resume endpoint"},"profitReduce":{"type":"string","description":"Grid profit from position reduction (accumulated)"},"closeOrderType":{"type":"string","description":"Close order type:\n`market` - Market price close,\n`limit` - Limit price close,\n`limit_high` - Neutral grid top limit close\n","enum":["market","limit","limit_high"]},"closedBaseAmount":{"type":"string","description":"Closed position amount"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"bonusBackUsdt":{"type":"string","description":"USDT recovered from bonus on close"},"bonusBackQuote":{"type":"string","description":"Quote recovered from bonus on close"},"notionalStatus":{"type":"string","description":"Notional status: `NORMAL` or `NOTIONAL_LIMIT`","enum":["NORMAL","NOTIONAL_LIMIT"],"default":"NORMAL"},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"},"bonusFeeRatio":{"type":"string","description":"Bonus fee ratio (e.g. \"0.2\" = 20%)"},"bonusFee":{"type":"string","description":"Bonus management fee recovered on close (in quote)"},"disableChangeTp":{"type":"boolean","description":"Whether modification of take profit is disabled"},"disableInvestInTrigger":{"type":"boolean","description":"Whether trigger investment is disabled"},"investInTriggers":{"type":"array","description":"Pending trigger investment list (max 1 item)","items":{"$ref":"#/components/schemas/InvestInTrigger"}},"investOutTriggers":{"type":"array","description":"Pending trigger reduction list (max 1 item)","items":{"$ref":"#/components/schemas/InvestOutTrigger"}},"autoExpiredTime":{"type":"number","description":"Auto-close timestamp in milliseconds (for bonus orders)"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type:\n`FUTURES_MOON` - Futures moon order,\n`FULLY_HEDGING` - Fully hedged order,\n`LOAN_GRID` - Loan grid,\n`LEVERAGE_GRID` - Leverage grid,\n`FUTURE_GRID_COIN_MARGINED` - Coin-margined futures grid\n","enum":["FUTURES_MOON","FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"profitExited":{"type":"string","description":"Exited profit"},"fundingFeePayment":{"type":"string","description":"Total funding fee paid (negative value)"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close (requires original order to enable follow close)"}}},"InvestInTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger investment price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"quoteInvestment":{"type":"string","description":"Trigger investment amount"},"extraMarginAmount":{"type":"string","description":"Trigger dynamic margin"},"addTime":{"type":"number","description":"Add time in milliseconds"},"investCoin":{"type":"string","description":"Investment currency (currently only supports quote)"}}},"InvestOutTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger reduction price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"addTime":{"type":"number","description":"Add time in milliseconds"}}}}}} ``` ## The InvestInTrigger object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"InvestInTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger investment price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"quoteInvestment":{"type":"string","description":"Trigger investment amount"},"extraMarginAmount":{"type":"string","description":"Trigger dynamic margin"},"addTime":{"type":"number","description":"Add time in milliseconds"},"investCoin":{"type":"string","description":"Investment currency (currently only supports quote)"}}}}}} ``` ## The InvestOutTrigger object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"InvestOutTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger reduction price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"addTime":{"type":"number","description":"Add time in milliseconds"}}}}}} ``` ## The FutureHedgeGridOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FutureHedgeGridOrderData":{"type":"object","description":"Order detail data for cross margin futures grid (`future_hedge_grid`).\nA hedge grid is a parent order that runs a `long` and a `short` sub-grid\nsimultaneously under one cross-margin account. The top-level fields are\naggregated across both sub-grids; per-direction detail is under `long`\nand `short`.\n","properties":{"initQuoteInvestment":{"type":"string","description":"Initial total investment amount"},"initExtraMargin":{"type":"string","description":"Initial extra margin"},"initBaseAmount":{"type":"string","description":"Initial base amount"},"placedExchangeOrderCount":{"type":"number","description":"Number of currently open exchange orders (aggregated)"},"closedExchangeOrderCount":{"type":"number","description":"Number of closed exchange orders (aggregated)"},"exchangeOrderPairedCount":{"type":"number","description":"Number of paired exchange orders (aggregated)"},"gridProfit":{"type":"string","description":"Grid profit (aggregated)"},"totalVolume":{"type":"string","description":"Total traded volume (aggregated)"},"totalFee":{"type":"string","description":"Total fees (aggregated)"},"totalFundingFee":{"type":"string","description":"Total funding fees (aggregated)"},"totalRealizedProfit":{"type":"string","description":"Total realized profit (aggregated)"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"status":{"type":"string","description":"Bot status"},"riskStatus":{"type":"string","description":"Overall risk status of the order"},"lossStopType":{"type":"string","description":"Stop loss type:\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio\n","enum":["profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio\n","enum":["profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"lossStopHigh":{"type":"string","description":"Upper stop loss value"},"profitStopDelay":{"type":"number","description":"Take profit trigger delay"},"lossStopDelay":{"type":"number","description":"Stop loss trigger delay"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Shared profit on close (in quote)"},"long":{"$ref":"#/components/schemas/FutureHedgeGridSubGrid"},"short":{"$ref":"#/components/schemas/FutureHedgeGridSubGrid"}}},"FutureHedgeGridSubGrid":{"type":"object","description":"One direction (long or short) of a cross margin futures grid hedge order.","properties":{"buOrderId":{"type":"string","description":"Sub-grid bot order ID"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"leverage":{"type":"number","description":"Leverage multiplier"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteInvestment":{"type":"string","description":"Investment amount"},"status":{"type":"string","description":"Sub-grid strategy status"},"initPrice":{"type":"string","description":"Price at creation"},"initQuoteInvestment":{"type":"string","description":"Initial investment amount"},"createTime":{"type":"number","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"number","description":"Close timestamp in milliseconds"},"closedPrice":{"type":"string","description":"Close price"},"reasonBy":{"type":"string","description":"Close reason"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Base amount"},"quoteAmount":{"type":"string","description":"Quote amount"},"placedExchangeOrderCount":{"type":"number","description":"Number of currently open exchange orders"},"closedExchangeOrderCount":{"type":"number","description":"Number of closed exchange orders"},"exchangeOrderPairedCount":{"type":"number","description":"Number of paired exchange orders"},"gridProfit":{"type":"string","description":"Grid profit"},"profitWithdrawn":{"type":"string","description":"Withdrawn grid profit"},"totalVolume":{"type":"string","description":"Total traded volume"},"totalFee":{"type":"string","description":"Total fees"},"totalFundingFee":{"type":"string","description":"Total funding fees"},"totalRealizedProfit":{"type":"string","description":"Realized profit"},"condition":{"type":"string","description":"Condition trigger price"},"conditionDirection":{"type":"string","description":"Condition order direction"},"triggerTime":{"type":"number","description":"Trigger timestamp in milliseconds"},"riskStatus":{"type":"string","description":"Risk status"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Actual liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPrice":{"type":"string","description":"Estimated liquidation price"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraMargin":{"type":"string","description":"Extra margin amount"},"trx24h":{"type":"number","description":"Transaction count in the last 24 hours"},"lossStopType":{"type":"string","description":"Stop loss type:\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio\n","enum":["profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio\n","enum":["profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"lossStopHigh":{"type":"string","description":"Upper stop loss value"},"unlockQuoteAmount":{"type":"string","description":"Quote amount returned to main account"}}}}}} ``` ## The FutureHedgeGridSubGrid object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FutureHedgeGridSubGrid":{"type":"object","description":"One direction (long or short) of a cross margin futures grid hedge order.","properties":{"buOrderId":{"type":"string","description":"Sub-grid bot order ID"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"leverage":{"type":"number","description":"Leverage multiplier"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteInvestment":{"type":"string","description":"Investment amount"},"status":{"type":"string","description":"Sub-grid strategy status"},"initPrice":{"type":"string","description":"Price at creation"},"initQuoteInvestment":{"type":"string","description":"Initial investment amount"},"createTime":{"type":"number","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"number","description":"Close timestamp in milliseconds"},"closedPrice":{"type":"string","description":"Close price"},"reasonBy":{"type":"string","description":"Close reason"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Base amount"},"quoteAmount":{"type":"string","description":"Quote amount"},"placedExchangeOrderCount":{"type":"number","description":"Number of currently open exchange orders"},"closedExchangeOrderCount":{"type":"number","description":"Number of closed exchange orders"},"exchangeOrderPairedCount":{"type":"number","description":"Number of paired exchange orders"},"gridProfit":{"type":"string","description":"Grid profit"},"profitWithdrawn":{"type":"string","description":"Withdrawn grid profit"},"totalVolume":{"type":"string","description":"Total traded volume"},"totalFee":{"type":"string","description":"Total fees"},"totalFundingFee":{"type":"string","description":"Total funding fees"},"totalRealizedProfit":{"type":"string","description":"Realized profit"},"condition":{"type":"string","description":"Condition trigger price"},"conditionDirection":{"type":"string","description":"Condition order direction"},"triggerTime":{"type":"number","description":"Trigger timestamp in milliseconds"},"riskStatus":{"type":"string","description":"Risk status"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Actual liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPrice":{"type":"string","description":"Estimated liquidation price"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraMargin":{"type":"string","description":"Extra margin amount"},"trx24h":{"type":"number","description":"Transaction count in the last 24 hours"},"lossStopType":{"type":"string","description":"Stop loss type:\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio\n","enum":["profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio\n","enum":["profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"lossStopHigh":{"type":"string","description":"Upper stop loss value"},"unlockQuoteAmount":{"type":"string","description":"Quote amount returned to main account"}}}}}} ``` ## The CreateFuturesGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateFuturesGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID. Set this to the `bu_order_id` of an existing copy trading pool's lead order to join that pool: the newly created futures grid order will be attached to the pool and copied by its followers. This is the only field that makes a new order join an existing copy trading pool, so it must be a valid lead order ID — an invalid or closed value will cause the request to fail."},"buOrderData":{"$ref":"#/components/schemas/CreateFuturesGridOrderData"}}},"CreateFuturesGridOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quoteInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Investment amount"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)","enum":["-1","1"]},"lossStopType":{"type":"string","description":"Stop loss type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value (interpretation depends on lossStopType)"},"lossStopDelay":{"type":"number","description":"Stop loss delay in seconds"},"profitStopType":{"type":"string","description":"Take profit type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value (interpretation depends on profitStopType)"},"profitStopDelay":{"type":"number","description":"Take profit delay in seconds"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default), `FUTURE_GRID_BONUS`","enum":["USER","FUTURE_GRID_BONUS"]},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type (stored only)"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type","enum":["FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close"}}}}}} ``` ## The CreateFuturesGridOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateFuturesGridOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quoteInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Investment amount"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)","enum":["-1","1"]},"lossStopType":{"type":"string","description":"Stop loss type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value (interpretation depends on lossStopType)"},"lossStopDelay":{"type":"number","description":"Stop loss delay in seconds"},"profitStopType":{"type":"string","description":"Take profit type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value (interpretation depends on profitStopType)"},"profitStopDelay":{"type":"number","description":"Take profit delay in seconds"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default), `FUTURE_GRID_BONUS`","enum":["USER","FUTURE_GRID_BONUS"]},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type (stored only)"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type","enum":["FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close"}}}}}} ``` ## The CheckFuturesGridParamsRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckFuturesGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency, must end with `.PERP`"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckFuturesGridParamsOrderData"}}},"CheckFuturesGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quote_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be greater than `bottom` and match the symbol's price precision."},"bottom":{"type":"string","description":"Grid lower price. Must be greater than 0 and match the symbol's price precision."},"row":{"type":"integer","description":"Number of grid levels (2–500)","minimum":2,"maximum":500},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"integer","description":"Leverage multiplier (1 to symbol's maximum leverage)"},"extra_margin":{"type":"boolean","description":"Controls how the investment is split between trading capital and extra margin (a safety buffer against liquidation).\n\n- `false` (default) — **Manual mode**: `quote_investment` is used entirely as trading capital (position margin + order margin + fee). Extra margin must be specified separately via `extra_margin_amount`.\n- `true` — **Auto-split mode**: `quote_investment` represents the **total input**. The system automatically splits it into trading capital and extra margin reserve. A portion is allocated as extra margin to reduce liquidation risk.\n\nThis flag also affects `min_investment` / `max_investment`:\n- `false`: the range covers trading capital only (excluding extra margin).\n- `true`: the range covers the total input (including the auto-calculated extra margin).\n","default":false},"quote_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\n\n- When `extra_margin=false`: this is the **trading capital** only (extra margin is provided separately via `extra_margin_amount`).\n- When `extra_margin=true`: this is the **total input** — the system will auto-split it into trading capital (`estimate_investment`) and extra margin (`estimate_extra_margin`).\n\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"extra_margin_amount":{"type":"string","description":"Additional margin amount on top of `quote_investment`, used as a safety buffer against liquidation. Must be >= 0. Omit or pass empty string to use 0.\n\n- When `extra_margin=false`: this value is passed through as-is. It does **not** count toward `quote_investment` or the `min_investment`/`max_investment` range, but it improves the estimated liquidation price.\n- When `extra_margin=true`: typically not needed, as the system auto-calculates extra margin from `quote_investment`. If provided, it is added on top of the auto-calculated margin and also improves the estimated liquidation price.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}}}}} ``` ## The CheckFuturesGridParamsOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckFuturesGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quote_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be greater than `bottom` and match the symbol's price precision."},"bottom":{"type":"string","description":"Grid lower price. Must be greater than 0 and match the symbol's price precision."},"row":{"type":"integer","description":"Number of grid levels (2–500)","minimum":2,"maximum":500},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"integer","description":"Leverage multiplier (1 to symbol's maximum leverage)"},"extra_margin":{"type":"boolean","description":"Controls how the investment is split between trading capital and extra margin (a safety buffer against liquidation).\n\n- `false` (default) — **Manual mode**: `quote_investment` is used entirely as trading capital (position margin + order margin + fee). Extra margin must be specified separately via `extra_margin_amount`.\n- `true` — **Auto-split mode**: `quote_investment` represents the **total input**. The system automatically splits it into trading capital and extra margin reserve. A portion is allocated as extra margin to reduce liquidation risk.\n\nThis flag also affects `min_investment` / `max_investment`:\n- `false`: the range covers trading capital only (excluding extra margin).\n- `true`: the range covers the total input (including the auto-calculated extra margin).\n","default":false},"quote_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\n\n- When `extra_margin=false`: this is the **trading capital** only (extra margin is provided separately via `extra_margin_amount`).\n- When `extra_margin=true`: this is the **total input** — the system will auto-split it into trading capital (`estimate_investment`) and extra margin (`estimate_extra_margin`).\n\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"extra_margin_amount":{"type":"string","description":"Additional margin amount on top of `quote_investment`, used as a safety buffer against liquidation. Must be >= 0. Omit or pass empty string to use 0.\n\n- When `extra_margin=false`: this value is passed through as-is. It does **not** count toward `quote_investment` or the `min_investment`/`max_investment` range, but it improves the estimated liquidation price.\n- When `extra_margin=true`: typically not needed, as the system auto-calculates extra margin from `quote_investment`. If provided, it is added on top of the auto-calculated margin and also improves the estimated liquidation price.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}}}}} ``` ## The AdjustFuturesGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"AdjustFuturesGridRequest":{"type":"object","required":["buOrderId","type","extraMargin","openPrice"],"description":"Adjust a futures grid order. The fields controlling how the investment amount is\ntreated (`isReinvest`, `keepInvestment`, `quoteInvestment`, `adjustParamsSence`)\noverlap and interact — pick ONE intent from the table below and set exactly the\nlisted fields. Do not mix intents.\n\nInvestment-intent decision table (only relevant when `type=adjust_params`):\n\n| Intent | Set these fields |\n|----------------------------------------------------|-------------------------------------------------------------------------|\n| Only change grid range/row, keep investment fixed | `keepInvestment=true` (leave `isReinvest`/`quoteInvestment` unset) |\n| Add funds to the order | `quoteInvestment=` (do NOT rely on `isReinvest`; see its note) |\n| Reinvest current floating profit, add no new funds | `adjustParamsSence=\"reinvest\"`, `isReinvest=true`, `quoteInvestment=0` |\n\nPrecedence & hidden rules (read before setting flags):\n- `keepInvestment=true` overrides `isReinvest` — when set, `isReinvest` is ignored.\n- Passing `quoteInvestment>0` is implicitly treated as reinvest, even if you send\n `isReinvest=false`. To keep the investment untouched, use `keepInvestment=true`,\n NOT `isReinvest=false`.\n- `isReinvest=false` (without `keepInvestment`) requires current floating PnL > 0;\n otherwise the request is rejected with reason `PROFIT_LESS_THAN_ZERO`.\n- Always call `adjustParamsCheck` first with the same body to preview the outcome\n and catch these constraints before executing.\n","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Adjustment type:\n`invest_in` - Add investment,\n`adjust_params` - Modify grid range,\n`invest_in_trigger` - Trigger investment\n","enum":["invest_in","adjust_params","invest_in_trigger"]},"quoteInvestment":{"type":"number","description":"When type=invest_in: additional investment amount (must be > 0).\nWhen type=adjust_params: amount of new funds to add to the investment.\nNOTE: any value > 0 is implicitly treated as reinvest (forces isReinvest=true\ninternally), so do not send quoteInvestment>0 together with keepInvestment=true.\nLeave 0/unset for the \"keep investment\" or \"reinvest profit only\" intents.\n"},"extraMargin":{"type":"boolean","description":"true: reserve extra margin, false: no extra margin"},"openPrice":{"type":"number","description":"Current price"},"bottom":{"type":"string","description":"New grid lower price (required when type=adjust_params)"},"top":{"type":"string","description":"New grid upper price (required when type=adjust_params)"},"row":{"type":"number","description":"New grid level count (required when type=adjust_params)"},"extraMarginAmount":{"type":"number","description":"Extra margin amount to add (when type=adjust_params)"},"isRecommend":{"type":"boolean","description":"Whether using recommended parameters (when type=adjust_params)"},"isReinvest":{"type":"boolean","description":"When type=adjust_params: whether to fold current floating profit into the\ninvestment base (default false). Interacts with other fields — see the\ndecision table and precedence rules on this schema before using:\n- Ignored when keepInvestment=true.\n- Implicitly forced true when quoteInvestment>0.\n- When left false without keepInvestment, requires current PnL > 0, else the\n request is rejected with `PROFIT_LESS_THAN_ZERO`.\nFor the common \"keep investment unchanged\" intent, prefer keepInvestment=true\nover isReinvest=false.\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default) or `LOCK_ACTIVITY`","enum":["USER","LOCK_ACTIVITY"]},"condition":{"type":"string","description":"Trigger price (when type=invest_in_trigger)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]},"slippage":{"type":"string","description":"Slippage for add investment / modify range"},"adjustParamsSence":{"type":"string","description":"\"Reinvest profit only\" intent. Set to `reinvest` (only valid when\ntype=adjust_params) to keep params/funds unchanged and fold current floating\nprofit into the investment. When set to `reinvest`, you MUST also send\nisReinvest=true and quoteInvestment=0 / extraMarginAmount=0, otherwise the\nrequest is rejected. Leave empty for the other intents.\n","enum":["reinvest"]},"keepInvestment":{"type":"boolean","description":"\"Keep investment fixed\" intent (recommended for pure range/row edits).\nWhen `true` and type=adjust_params: only modify grid range/row without\nresetting the investment amount. Overrides isReinvest (isReinvest is ignored),\nskips the PnL check, but still validates the price range. Do not combine with\nquoteInvestment>0 or adjustParamsSence=reinvest.\nWhen `false` (default): investment base is recalculated after modification and\nthe PnL check applies.\n","default":false}}}}}} ``` ## The ReduceFuturesGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"ReduceFuturesGridRequest":{"type":"object","required":["buOrderId","openPrice","reduceNum"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"openPrice":{"type":"string","description":"Current price"},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"slippage":{"type":"string","description":"Reduction slippage"},"condition":{"type":"string","description":"Trigger reduction price (must be > 0)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]}}}}}} ``` ## The ReduceFuturesGridResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"ReduceFuturesGridResponse":{"type":"object","properties":{"checkResult":{"type":"boolean","description":"Check result"},"reason":{"type":"string","description":"Failure reason:\n`LOSS_GTE_INVESTMENT` - Total equity minus dynamic margin <= 0,\n`POSITION_TOO_SMALL` - Position too small to reduce,\n`REDUCE_TOO_MUCH` - reduceNum too large,\n`REDUCE_TOO_SMALL` - reduceNum too small,\n`SYMBOL_MAINTENANCE` - Symbol under maintenance\n","enum":["LOSS_GTE_INVESTMENT","POSITION_TOO_SMALL","REDUCE_TOO_MUCH","REDUCE_TOO_SMALL","SYMBOL_MAINTENANCE"]}}}}}} ``` ## The CancelFuturesGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CancelFuturesGridRequest":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeNote":{"type":"string","description":"Close note"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only (default),\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"immediate":{"type":"boolean","description":"Force-cancel an order that is stuck in the `close_position` state because its limit take-profit / stop-loss order has triggered but not yet filled. This is NOT a generic \"cancel faster\" flag.\n\n- `false` (default): normal cancellation. Use this for orders in any regular state (e.g. `running`). It runs the full close flow: update status, dispatch the close action, and settle.\n- `true`: special recovery path ONLY valid when the order is in the `close_position` state with an unfilled limit TP/SL order. It sends the close action directly with a market price. If the order is in any other state, the request is rejected with `Forbidden: invalid status`.\n\nDo not set `true` as a default \"force close\" option — for normal close-outs always use `false`."},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"}}}}}} ``` ## The AdjustParamsCheckResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"AdjustParamsCheckResponse":{"type":"object","description":"Adjust params check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the adjustment is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"estimateInvestment":{"type":"string","description":"Estimated investment amount after adjustment"},"estimateExtraMargin":{"type":"string","description":"Estimated extra margin after adjustment"},"minInvestment":{"type":"string","description":"Minimum required investment"},"maxInvestment":{"type":"string","description":"Maximum allowed investment"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after adjustment"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after adjustment"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"estimatePerVolume":{"type":"string","description":"Estimated per-grid volume after adjustment"},"slippage":{"type":"string","description":"Recommended slippage"}}}}}} ``` ## The ReduceCheckResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"ReduceCheckResponse":{"type":"object","description":"Reduce check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the reduction is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"maxReduceNum":{"type":"integer","description":"Maximum reduce number allowed"},"reduceAmount":{"type":"string","description":"Estimated total reduction amount"},"reduceInvestment":{"type":"string","description":"Estimated investment to be returned"},"reduceGridprofit":{"type":"string","description":"Estimated grid profit to be returned"},"reducePnl":{"type":"string","description":"Estimated PnL from reduction"},"reduceFee":{"type":"string","description":"Estimated fee for reduction"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Upward liquidation price after reduction"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Downward liquidation price after reduction"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"slippage":{"type":"string","description":"Recommended slippage"}}}}}} ``` ## The FuturesGridPauseCheckRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridPauseCheckRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now; `conditional` = pause on trigger price"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price (when mode=conditional). Optional; set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price (when mode=conditional). Optional."}}}}}} ``` ## The FuturesGridPauseCheckResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridPauseCheckResponse":{"type":"object","description":"Pause check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be paused"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_RUNNING)"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — upward liquidation price after the upward pause triggers"},"estimateLiquidationPriceDownAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — downward liquidation price after the upward pause triggers"},"estimateLiquidationPriceUpAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — upward liquidation price after the downward pause triggers"},"estimateLiquidationPriceDownAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — downward liquidation price after the downward pause triggers"}}}}}} ``` ## The FuturesGridPauseRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridPauseRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now (backend uses live market price, not client-supplied); `conditional` = pause on trigger price"},"stopProfitEnabled":{"type":"boolean","description":"Whether to keep take-profit active while paused"},"stopLossEnabled":{"type":"boolean","description":"Whether to keep stop-loss active while paused"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price. Set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price."}}}}}} ``` ## The FuturesGridPauseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridPauseResponse":{"type":"object","description":"Pause execution result (no status field; processed asynchronously)","properties":{"stopLossEnabled":{"type":"boolean","description":"Effective stop-loss retention state"},"stopProfitEnabled":{"type":"boolean","description":"Effective take-profit retention state"},"triggerPausePriceUp":{"type":"string","description":"Effective upward trigger price"},"triggerPausePriceDown":{"type":"string","description":"Effective downward trigger price"}}}}}} ``` ## The FuturesGridResumeCheckRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridResumeCheckRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"}}}}}} ``` ## The FuturesGridResumeRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridResumeRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"triggerResumePriceUp":{"type":"string","description":"Upward trigger price for a conditional resume. Must be greater than the current market price. Independent from triggerResumePriceDown — set either or both."},"triggerResumePriceDown":{"type":"string","description":"Downward trigger price for a conditional resume. Must be greater than 0 and less than the current market price."},"isResumeImmediate":{"type":"boolean","description":"Optional tri-state flag. `true` = resume immediately (trigger prices ignored). `false` = conditional resume, keep the given trigger price(s); with both trigger prices empty this cancels trigger resume and keeps the order paused. Omitted = inferred from the trigger prices (both empty -> immediate, either set -> conditional)."}}}}}} ``` ## The FuturesGridResumeCheckResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridResumeCheckResponse":{"type":"object","description":"Resume check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be resumed"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_PAUSED)"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price after resuming"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price after resuming"}}}}}} ``` ## The FuturesGridResumeResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridResumeResponse":{"type":"object","description":"Resume execution result","properties":{"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}}}}} ``` ## The FuturesGridResumeInvalidTriggerPriceError object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridResumeInvalidTriggerPriceError":{"type":"object","description":"400 body returned when triggerResumePriceUp / triggerResumePriceDown fails direction validation or fails to parse. Rejected before dispatching; the order stays paused.","properties":{"code":{"type":"integer","description":"Fixed `40000700`."},"reason":{"type":"string","description":"Fixed `P_TRADING_BOT_INVALID_TRIGGER_PRICE_PARAM`."},"message":{"type":"string","description":"Specific validation error detail."},"data":{"nullable":true,"description":"Always null."}}}}}} ``` ## The FuturesGridMarginCheckRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridMarginCheckRequest":{"type":"object","required":["buOrderId","amount"],"description":"Shared by addMarginCheck and reduceMarginCheck; the direction is determined by the route, not a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal, serialized as an unquoted number)"}}}}}} ``` ## The FuturesGridMarginCheckResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridMarginCheckResponse":{"type":"object","description":"Add/reduce margin check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the amount is valid"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / EXCEEDS_MAX_AMOUNT)"},"estimateLiquidationPriceUpBefore":{"type":"string","description":"Estimated upward liquidation price before the change"},"estimateLiquidationPriceDownBefore":{"type":"string","description":"Estimated downward liquidation price before the change"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after the change"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after the change"},"maxAmount":{"type":"string","description":"Returned by reduceMarginCheck only — max reducible margin = min(existing extra margin, total equity − 1.05× used margin, margin account balance)"}}}}}} ``` ## The FuturesGridMarginTransferRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridMarginTransferRequest":{"type":"object","required":["buOrderId","coin","amount"],"description":"Shared by addMargin and reduceMargin; the direction (in/out) is fixed server-side by the route and not exposed as a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal)"}}}}}} ``` ## The FuturesGridMarginTransferResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridMarginTransferResponse":{"type":"object","description":"Add/reduce margin execution result (no status field; processed asynchronously)","properties":{"transferId":{"type":"string","description":"Transfer record ID"},"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}}}}} ``` ## The FuturesGridTriggerProfitLossItem object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridTriggerProfitLossItem":{"type":"object","required":["type","stop_type","value"],"description":"A single take-profit or stop-loss setting. Field names are snake_case.\nHow `value` / `limit_price` are interpreted depends on `stop_type`.\n","properties":{"type":{"type":"string","description":"Which trigger this item configures","enum":["stop_loss","stop_profit"]},"stop_type":{"type":"string","description":"How `value` is interpreted. Required (no implicit fallback):\n`price` (trigger price), `price_limit` (trigger price, closes via a limit\norder at `limit_price`), `profit_amount` (profit/loss amount),\n`profit_ratio` (profit/loss ratio).\n","enum":["price","price_limit","profit_amount","profit_ratio"]},"value":{"type":"string","description":"Trigger threshold, interpreted per `stop_type`. Empty string `\"\"` clears the\ntrigger. When non-empty it only needs to be a valid decimal — not enforced to\nbe positive; `0` and negative values are accepted (e.g. `-0.2` = a −20%\nstop-loss ratio).\n"},"limit_price":{"type":"string","description":"Limit price used to close the position when `stop_type=price_limit`. Required in that case."},"stop_delay":{"type":"integer","format":"int64","description":"Seconds to wait after the condition is first met before executing. `0` = immediate."},"loss_stop_sell_model":{"type":"string","description":"Settlement currency for a stop-loss close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"profit_stop_sell_model":{"type":"string","description":"Settlement currency for a take-profit close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"stop_high_price":{"type":"string","description":"Upper stop-loss price for a neutral grid (`no_trend`). Applies only to a\n`stop_loss` item and only when `stop_type` is `price` or `price_limit`;\nignored otherwise.\n"},"limit_high_price":{"type":"string","description":"Upper limit stop-loss price for a neutral grid, used together with `stop_high_price` when `stop_type=price_limit`."}}}}}} ``` ## The FuturesGridUpdateTriggerProfitLossRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridUpdateTriggerProfitLossRequest":{"type":"object","required":["bu_order_id","list"],"description":"Set / update / clear the take-profit and stop-loss of a running futures grid order.\nField names are snake_case (unlike the other futuresGrid endpoints).\n","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"list":{"type":"array","description":"One item per trigger to configure. May include a `stop_loss` item, a `stop_profit` item, or both.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"FuturesGridTriggerProfitLossItem":{"type":"object","required":["type","stop_type","value"],"description":"A single take-profit or stop-loss setting. Field names are snake_case.\nHow `value` / `limit_price` are interpreted depends on `stop_type`.\n","properties":{"type":{"type":"string","description":"Which trigger this item configures","enum":["stop_loss","stop_profit"]},"stop_type":{"type":"string","description":"How `value` is interpreted. Required (no implicit fallback):\n`price` (trigger price), `price_limit` (trigger price, closes via a limit\norder at `limit_price`), `profit_amount` (profit/loss amount),\n`profit_ratio` (profit/loss ratio).\n","enum":["price","price_limit","profit_amount","profit_ratio"]},"value":{"type":"string","description":"Trigger threshold, interpreted per `stop_type`. Empty string `\"\"` clears the\ntrigger. When non-empty it only needs to be a valid decimal — not enforced to\nbe positive; `0` and negative values are accepted (e.g. `-0.2` = a −20%\nstop-loss ratio).\n"},"limit_price":{"type":"string","description":"Limit price used to close the position when `stop_type=price_limit`. Required in that case."},"stop_delay":{"type":"integer","format":"int64","description":"Seconds to wait after the condition is first met before executing. `0` = immediate."},"loss_stop_sell_model":{"type":"string","description":"Settlement currency for a stop-loss close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"profit_stop_sell_model":{"type":"string","description":"Settlement currency for a take-profit close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"stop_high_price":{"type":"string","description":"Upper stop-loss price for a neutral grid (`no_trend`). Applies only to a\n`stop_loss` item and only when `stop_type` is `price` or `price_limit`;\nignored otherwise.\n"},"limit_high_price":{"type":"string","description":"Upper limit stop-loss price for a neutral grid, used together with `stop_high_price` when `stop_type=price_limit`."}}}}}} ``` ## The FuturesGridTriggerProfitLossResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridTriggerProfitLossResponse":{"type":"object","description":"Echo of the applied trigger settings. Persistence onto the order is asynchronous — poll `GET /futuresGrid/order` to confirm.","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"result":{"type":"integer","format":"int32","description":"RPC return code"},"list":{"type":"array","description":"Echo of the trigger settings that were applied.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"FuturesGridTriggerProfitLossItem":{"type":"object","required":["type","stop_type","value"],"description":"A single take-profit or stop-loss setting. Field names are snake_case.\nHow `value` / `limit_price` are interpreted depends on `stop_type`.\n","properties":{"type":{"type":"string","description":"Which trigger this item configures","enum":["stop_loss","stop_profit"]},"stop_type":{"type":"string","description":"How `value` is interpreted. Required (no implicit fallback):\n`price` (trigger price), `price_limit` (trigger price, closes via a limit\norder at `limit_price`), `profit_amount` (profit/loss amount),\n`profit_ratio` (profit/loss ratio).\n","enum":["price","price_limit","profit_amount","profit_ratio"]},"value":{"type":"string","description":"Trigger threshold, interpreted per `stop_type`. Empty string `\"\"` clears the\ntrigger. When non-empty it only needs to be a valid decimal — not enforced to\nbe positive; `0` and negative values are accepted (e.g. `-0.2` = a −20%\nstop-loss ratio).\n"},"limit_price":{"type":"string","description":"Limit price used to close the position when `stop_type=price_limit`. Required in that case."},"stop_delay":{"type":"integer","format":"int64","description":"Seconds to wait after the condition is first met before executing. `0` = immediate."},"loss_stop_sell_model":{"type":"string","description":"Settlement currency for a stop-loss close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"profit_stop_sell_model":{"type":"string","description":"Settlement currency for a take-profit close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"stop_high_price":{"type":"string","description":"Upper stop-loss price for a neutral grid (`no_trend`). Applies only to a\n`stop_loss` item and only when `stop_type` is `price` or `price_limit`;\nignored otherwise.\n"},"limit_high_price":{"type":"string","description":"Upper limit stop-loss price for a neutral grid, used together with `stop_high_price` when `stop_type=price_limit`."}}}}}} ``` ## The SpotGridOrder object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SpotGridOrder":{"type":"object","description":"Spot grid bot order (wraps OrderResult with GridV5OrderData)","properties":{"buOrderType":{"type":"string","description":"Order type (always `grid_v5` for spot grid)"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"note":{"type":"string","description":"Order note"},"buOrderData":{"$ref":"#/components/schemas/SpotGridOrderData"}}},"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}}}}} ``` ## The SpotGridOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}}}}} ``` ## The SpotGridAiStrategy object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SpotGridAiStrategy":{"type":"object","description":"AI-recommended spot grid strategy","properties":{"annualized":{"type":"string","description":"Annualized return of the recommended strategy"},"totalApr":{"type":"string","description":"Total APR"},"high":{"type":"string","description":"Recommended grid upper price"},"low":{"type":"string","description":"Recommended grid lower price"},"gridCount":{"type":"integer","description":"Recommended number of grid levels"},"strategyId":{"type":"string","description":"Strategy ID"},"volatility":{"type":"string","description":"Market volatility indicator"},"maxDrawDown":{"type":"string","description":"Maximum drawdown"},"options":{"type":"array","description":"List of strategy options by time period","items":{"$ref":"#/components/schemas/SpotGridAiStrategyOption"}}}},"SpotGridAiStrategyOption":{"type":"object","description":"AI strategy option for a specific backtesting period","properties":{"period":{"type":"integer","description":"Backtesting period in days (e.g. 7, 14, 30)"},"annualized":{"type":"string","description":"Annualized return for this period"},"totalApr":{"type":"string","description":"Total APR for this period"},"high":{"type":"string","description":"Grid upper price for this period"},"low":{"type":"string","description":"Grid lower price for this period"},"gridCount":{"type":"integer","description":"Number of grid levels for this period"},"maxDrawDown":{"type":"string","description":"Maximum drawdown for this period"},"volatility":{"type":"string","description":"Volatility for this period"},"suitabilityMin":{"type":"integer","description":"Minimum suitability score"},"suitabilityMax":{"type":"integer","description":"Maximum suitability score"}}}}}} ``` ## The SpotGridAiStrategyOption object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SpotGridAiStrategyOption":{"type":"object","description":"AI strategy option for a specific backtesting period","properties":{"period":{"type":"integer","description":"Backtesting period in days (e.g. 7, 14, 30)"},"annualized":{"type":"string","description":"Annualized return for this period"},"totalApr":{"type":"string","description":"Total APR for this period"},"high":{"type":"string","description":"Grid upper price for this period"},"low":{"type":"string","description":"Grid lower price for this period"},"gridCount":{"type":"integer","description":"Number of grid levels for this period"},"maxDrawDown":{"type":"string","description":"Maximum drawdown for this period"},"volatility":{"type":"string","description":"Volatility for this period"},"suitabilityMin":{"type":"integer","description":"Minimum suitability score"},"suitabilityMax":{"type":"integer","description":"Maximum suitability score"}}}}}} ``` ## The CreateSpotGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateSpotGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"note":{"type":"string","description":"Optional order note"},"buOrderData":{"$ref":"#/components/schemas/CreateSpotGridOrderData"}}},"CreateSpotGridOrderData":{"type":"object","required":["top","bottom","row","gridType","quoteTotalInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels (2–200)"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteTotalInvestment":{"type":"string","description":"Quote currency investment amount"},"lossStopType":{"type":"string","description":"Stop loss mode:\n`price` — trigger when market price reaches `lossStop`,\n`profit_amount` — trigger when unrealized loss reaches `lossStop` amount,\n`profit_ratio` — trigger when unrealized loss reaches `lossStop` ratio (e.g. `\"-0.1\"` = -10%)\n","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"profitStopType":{"type":"string","description":"Take profit mode:\n`price` — trigger when market price reaches `profitStop`,\n`profit_amount` — trigger when realized profit reaches `profitStop` amount,\n`profit_ratio` — trigger when realized profit reaches `profitStop` ratio (e.g. `\"0.1\"` = 10%)\n","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"condition":{"type":"string","description":"Trigger price — bot starts only when price crosses this level (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"slippage":{"type":"string","description":"Open position slippage tolerance (e.g. \"0.01\" = 1%)"},"closeSellModel":{"type":"string","description":"Close sell mode on cancellation:\n`NOT_SELL` - Keep base+quote as-is, do not sell (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"],"default":"NOT_SELL"}}}}}} ``` ## The CreateSpotGridOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateSpotGridOrderData":{"type":"object","required":["top","bottom","row","gridType","quoteTotalInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels (2–200)"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteTotalInvestment":{"type":"string","description":"Quote currency investment amount"},"lossStopType":{"type":"string","description":"Stop loss mode:\n`price` — trigger when market price reaches `lossStop`,\n`profit_amount` — trigger when unrealized loss reaches `lossStop` amount,\n`profit_ratio` — trigger when unrealized loss reaches `lossStop` ratio (e.g. `\"-0.1\"` = -10%)\n","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"profitStopType":{"type":"string","description":"Take profit mode:\n`price` — trigger when market price reaches `profitStop`,\n`profit_amount` — trigger when realized profit reaches `profitStop` amount,\n`profit_ratio` — trigger when realized profit reaches `profitStop` ratio (e.g. `\"0.1\"` = 10%)\n","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"condition":{"type":"string","description":"Trigger price — bot starts only when price crosses this level (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"slippage":{"type":"string","description":"Open position slippage tolerance (e.g. \"0.01\" = 1%)"},"closeSellModel":{"type":"string","description":"Close sell mode on cancellation:\n`NOT_SELL` - Keep base+quote as-is, do not sell (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"],"default":"NOT_SELL"}}}}}} ``` ## The CheckSpotGridParamsRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckSpotGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckSpotGridParamsOrderData"}}},"CheckSpotGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","quote_total_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be a valid numeric string, strictly greater than `bottom`."},"bottom":{"type":"string","description":"Grid lower price. Must be a valid numeric string."},"row":{"type":"integer","description":"Number of grid levels (2–1000).","minimum":2,"maximum":1000},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quote_total_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}}}}} ``` ## The CheckSpotGridParamsOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckSpotGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","quote_total_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be a valid numeric string, strictly greater than `bottom`."},"bottom":{"type":"string","description":"Grid lower price. Must be a valid numeric string."},"row":{"type":"integer","description":"Number of grid levels (2–1000).","minimum":2,"maximum":1000},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quote_total_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}}}}} ``` ## The AdjustSpotGridParamsRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"AdjustSpotGridParamsRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"New grid upper price"},"bottom":{"type":"string","description":"New grid lower price"},"row":{"type":"integer","format":"int32","description":"New number of grid levels"},"quoteInvest":{"type":"string","description":"Additional quote investment amount"}}}}}} ``` ## The InvestInSpotGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"InvestInSpotGridRequest":{"type":"object","required":["buOrderId","quoteInvest"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"quoteInvest":{"type":"string","description":"Additional investment amount in quote currency"}}}}}} ``` ## The CancelSpotGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CancelSpotGridRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeSellModel":{"type":"string","description":"Close sell mode set at creation:\n`NOT_SELL` - Keep base+quote as-is (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"}}}}}} ``` ## The ProfitSpotGridRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"ProfitSpotGridRequest":{"type":"object","required":["buOrderId","amount"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"string","description":"Amount to extract"}}}}}} ``` ## The TransferRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"TransferRecord":{"type":"object","description":"Record of a profit extraction transfer","properties":{"transferId":{"type":"string","description":"Transfer ID"},"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Transfer type (e.g. `profit`)"},"direction":{"type":"string","description":"Transfer direction: `out` (extract from bot)"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"string","description":"Transfer amount"},"amountC":{"type":"string","description":"Transfer amount in platform currency"},"status":{"type":"string","description":"Transfer status"},"createTime":{"type":"integer","format":"int64","description":"Transfer timestamp in milliseconds"},"error":{"type":"string","description":"Error message (if failed)"}}}}}} ``` ## The FuturesGridCheckParamsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"FuturesGridCheckParamsData":{"type":"object","description":"Futures grid parameter check result data.\n\n**When result=true**: All fields are populated with full estimate data.\nLiquidation price fields are cleared when `quote_investment` is outside [`min_investment`, `max_investment`].\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"quote_investment not match spending precision: max {N} decimal places\"`,\n`\"extra_margin_amount not match spending precision: max {N} decimal places\"`,\n`\"grid profit per volume less than 0\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum allowed `quote_investment`.\n- When `extra_margin=false`: minimum trading capital (excluding extra margin).\n- When `extra_margin=true`: minimum total input (including auto-calculated extra margin).\n"},"max_investment":{"type":"string","description":"Maximum allowed `quote_investment`.\n- When `extra_margin=false`: maximum trading capital (excluding extra margin).\n- When `extra_margin=true`: maximum total input (including auto-calculated extra margin).\n"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_investment":{"type":"string","description":"Estimated amount allocated to trading capital (= position margin + order margin + fee). Does **not** include extra margin.\n- When `extra_margin=false`: equals `quote_investment` (all input goes to trading capital).\n- When `extra_margin=true`: less than `quote_investment` — the remainder goes to `estimate_extra_margin`.\n"},"estimate_extra_margin":{"type":"string","description":"Estimated extra margin — a safety buffer that reduces liquidation risk but is not used for grid trading itself.\n- When `extra_margin=false`: equals the input `extra_margin_amount` (pass-through).\n- When `extra_margin=true`: auto-calculated as `quote_investment - estimate_investment`.\n"},"estimate_fee":{"type":"string","description":"Estimated opening trading fee (included in `estimate_investment`)."},"estimate_position_occupy_margin":{"type":"string","description":"Estimated margin occupied by positions opened immediately at creation (included in `estimate_investment`)."},"estimate_order_occupy_margin":{"type":"string","description":"Estimated margin occupied by pending grid orders (included in `estimate_investment`)."},"estimate_position":{"type":"string","description":"Estimated position opened immediately at order creation. Positive = long, negative = short."},"estimate_liquidation_price_up":{"type":"string","description":"Estimated upper liquidation price. Returns `\"0\"` for long-only grids (no upper liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."},"estimate_liquidation_price_down":{"type":"string","description":"Estimated lower liquidation price. Returns `\"0\"` for short-only grids (no lower liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."}}}}}} ``` ## The SpotGridCheckParamsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SpotGridCheckParamsData":{"type":"object","description":"Spot grid parameter check result data.\n\n**When result=true**: All fields are populated.\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"grid price duplicated: reduce row or widen range\"`,\n`\"quote_total_investment not match quote precision: max {N} decimal places\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum investment amount in quote currency"},"max_investment":{"type":"string","description":"Maximum investment amount in quote currency"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_fee":{"type":"string","description":"Estimated opening trading fee."}}}}}} ``` ## The CheckParamsResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckParamsResponse":{"$ref":"#/components/schemas/SpotGridCheckParamsData"},"SpotGridCheckParamsData":{"type":"object","description":"Spot grid parameter check result data.\n\n**When result=true**: All fields are populated.\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"grid price duplicated: reduce row or widen range\"`,\n`\"quote_total_investment not match quote precision: max {N} decimal places\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum investment amount in quote currency"},"max_investment":{"type":"string","description":"Maximum investment amount in quote currency"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_fee":{"type":"string","description":"Estimated opening trading fee."}}}}}} ``` ## The CheckSmartCopyParamsRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckSmartCopyParamsRequest":{"type":"object","required":["base","quote","leverage","quote_investment"],"properties":{"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"signal_type":{"type":"string","description":"Signal type identifier. Optional — omit to check without a specific signal."},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier (>= 1)","minimum":1},"quote_investment":{"type":"string","description":"Investment amount in quote currency to check against limits."}}}}}} ``` ## The CheckSmartCopyParamsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CheckSmartCopyParamsData":{"type":"object","description":"Smart copy parameter check result data.","properties":{"result":{"type":"boolean","description":"Whether the investment is within limits"},"max_investment":{"type":"string","description":"Maximum allowed investment amount in quote currency"},"max_leverage":{"type":"string","description":"Maximum allowed leverage"},"notional_limit":{"type":"string","description":"Total notional limit (quote_investment * leverage ceiling)"},"available_limit":{"type":"string","description":"Remaining available notional for this base/quote/signal combination"}}}}}} ``` ## The CreateSmartCopyOrderRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateSmartCopyOrderRequest":{"type":"object","required":["base","quote","bu_order_data"],"properties":{"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"key_id":{"type":"string","description":"API Key ID. Optional — derived from the API key used for authentication when omitted."},"note":{"type":"string","description":"Optional order note"},"copy_from":{"type":"string","description":"Source order ID to copy from (for copy trade orders)"},"copy_type":{"type":"string","description":"Copy type identifier"},"bu_order_data":{"$ref":"#/components/schemas/CreateSmartCopyOrderBuOrderData"}}},"CreateSmartCopyOrderBuOrderData":{"type":"object","required":["quote_total_investment","portfolio"],"properties":{"quote_total_investment":{"type":"string","description":"Total investment amount in quote currency"},"compound":{"type":"boolean","description":"Whether to enable compound interest (reinvest profits)","default":false},"profit_stop_maker":{"type":"boolean","description":"Whether to enable profit stop maker","default":false},"portfolio":{"type":"array","description":"List of portfolio items (at least 1 required)","minItems":1,"items":{"$ref":"#/components/schemas/SmartCopyPortfolioItemRequest"}}}},"SmartCopyPortfolioItemRequest":{"type":"object","required":["base","signal_type","leverage"],"properties":{"base":{"type":"string","description":"Base currency for this portfolio item"},"signal_type":{"type":"string","description":"Signal type identifier"},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"percent":{"type":"string","description":"Allocation percentage of total investment for this item (e.g. \"1\" = 100%)"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier for this item (>= 1)","minimum":1},"profit_stop_ratio":{"type":"string","description":"Take profit ratio (e.g. \"0.5\" = 50% profit triggers close)"},"loss_stop_ratio":{"type":"string","description":"Stop loss ratio (e.g. \"-0.2\" = 20% loss triggers close)"}}}}}} ``` ## The CreateSmartCopyOrderBuOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateSmartCopyOrderBuOrderData":{"type":"object","required":["quote_total_investment","portfolio"],"properties":{"quote_total_investment":{"type":"string","description":"Total investment amount in quote currency"},"compound":{"type":"boolean","description":"Whether to enable compound interest (reinvest profits)","default":false},"profit_stop_maker":{"type":"boolean","description":"Whether to enable profit stop maker","default":false},"portfolio":{"type":"array","description":"List of portfolio items (at least 1 required)","minItems":1,"items":{"$ref":"#/components/schemas/SmartCopyPortfolioItemRequest"}}}},"SmartCopyPortfolioItemRequest":{"type":"object","required":["base","signal_type","leverage"],"properties":{"base":{"type":"string","description":"Base currency for this portfolio item"},"signal_type":{"type":"string","description":"Signal type identifier"},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"percent":{"type":"string","description":"Allocation percentage of total investment for this item (e.g. \"1\" = 100%)"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier for this item (>= 1)","minimum":1},"profit_stop_ratio":{"type":"string","description":"Take profit ratio (e.g. \"0.5\" = 50% profit triggers close)"},"loss_stop_ratio":{"type":"string","description":"Stop loss ratio (e.g. \"-0.2\" = 20% loss triggers close)"}}}}}} ``` ## The SmartCopyPortfolioItemRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SmartCopyPortfolioItemRequest":{"type":"object","required":["base","signal_type","leverage"],"properties":{"base":{"type":"string","description":"Base currency for this portfolio item"},"signal_type":{"type":"string","description":"Signal type identifier"},"signal_param":{"type":"string","description":"Signal parameters JSON string. Optional."},"percent":{"type":"string","description":"Allocation percentage of total investment for this item (e.g. \"1\" = 100%)"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier for this item (>= 1)","minimum":1},"profit_stop_ratio":{"type":"string","description":"Take profit ratio (e.g. \"0.5\" = 50% profit triggers close)"},"loss_stop_ratio":{"type":"string","description":"Stop loss ratio (e.g. \"-0.2\" = 20% loss triggers close)"}}}}}} ``` ## The CreateSmartCopyOrderResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateSmartCopyOrderResponse":{"type":"object","properties":{"bu_order_id":{"type":"string","description":"Created bot order ID"}}}}}} ``` ## The CancelSmartCopyOrderRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CancelSmartCopyOrderRequest":{"type":"object","required":["bu_order_id"],"properties":{"bu_order_id":{"type":"string","description":"Bot order ID to cancel"},"close_note":{"type":"string","description":"Optional close reason note"},"convert_into_earn_coin":{"type":"boolean","description":"Whether to convert remaining assets into earn coin on close","default":false}}}}}} ``` ## The CancelSmartCopyOrderResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CancelSmartCopyOrderResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the cancellation was accepted"}}}}}} ``` ## The SmartCopyOrderDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SmartCopyOrderDetail":{"type":"object","description":"Smart copy bot order detail","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"buOrderType":{"type":"string","description":"Bot order type (always `smart_copy`)"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Source order ID (for copy trade orders)"},"copyType":{"type":"string","description":"Copy type"},"strategyId":{"type":"string","description":"Strategy ID"},"canceling":{"type":"integer","format":"int64","description":"Canceling flag"},"note":{"type":"string","description":"Order note"},"closeNote":{"type":"string","description":"Close note"},"customizeName":{"type":"string","description":"Custom name"},"buOrderData":{"$ref":"#/components/schemas/SmartCopyOrderData"}}},"SmartCopyOrderData":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"kolSignalId":{"type":"string","description":"KOL signal ID"},"quoteTotalInvestment":{"type":"string","description":"Current total investment in quote currency"},"quoteOriginalInvestment":{"type":"string","description":"Original investment amount in quote currency"},"currentQuoteAmount":{"type":"string","description":"Current quote amount in the bot account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"convertIntoEarnCoin":{"type":"integer","format":"int64","description":"Whether assets were converted to earn coin on close"},"reasonBy":{"type":"string","description":"Close reason (e.g. `user_cancel`, `create_failed`)"},"profit":{"type":"string","description":"Total profit in quote currency"},"status":{"type":"string","description":"Order data status"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Total profit shared"},"closedSharedQuote":{"type":"string","description":"Quote amount deducted for profit sharing on close"},"tradeType":{"type":"string","description":"Trade type: `futures` or `spot`","enum":["futures","spot"]},"fundingFee":{"type":"string","description":"Total funding fee paid"},"roundCount24h":{"type":"integer","format":"int64","description":"Number of completed signal rounds in the last 24 hours"},"kolName":{"type":"string","description":"KOL name"},"kolImage":{"type":"string","description":"KOL avatar URL"},"signalName":{"type":"string","description":"Signal display name"},"market":{"type":"string","description":"Market type"},"portfolio":{"type":"array","description":"Portfolio item details","items":{"$ref":"#/components/schemas/SmartCopyPortfolioItem"}}}},"SmartCopyPortfolioItem":{"type":"object","properties":{"tradeBase":{"type":"string","description":"Actual trading base currency"},"buOrderId":{"type":"string","description":"Bot order ID"},"base":{"type":"string","description":"Base currency for this portfolio item"},"signalType":{"type":"string","description":"Signal type identifier"},"signalParam":{"type":"string","description":"Signal parameters"},"percent":{"type":"string","description":"Allocation percentage"},"initPrice":{"type":"string","description":"Price at position open"},"closedPrice":{"type":"string","description":"Price at position close"},"currentBaseAmount":{"type":"string","description":"Current base amount held"},"closedBaseAmount":{"type":"string","description":"Base amount returned on close"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"totalFeeInBase":{"type":"string","description":"Total trading fees in base currency"},"totalFeeInQuote":{"type":"string","description":"Total trading fees in quote currency"},"profit":{"type":"string","description":"Profit for this portfolio item"},"roundCount":{"type":"integer","format":"int64","description":"Total completed signal rounds"},"currentRound":{"type":"integer","format":"int64","description":"Current signal round number"},"currentRoundMonth":{"type":"string","description":"Current round month label"},"status":{"type":"string","description":"Portfolio item status"},"expiredAt":{"type":"integer","format":"int64","description":"Expiry timestamp in milliseconds (0 = no expiry)"},"sharedAmount":{"type":"string","description":"Profit sharing amount for this item"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier"},"fundingFee":{"type":"string","description":"Funding fee for this item"},"qtyLong":{"type":"string","description":"Long position quantity"},"qtyShort":{"type":"string","description":"Short position quantity"},"amountLong":{"type":"string","description":"Long position amount in quote"},"amountShort":{"type":"string","description":"Short position amount in quote"},"amountSettle":{"type":"string","description":"Settlement amount"},"maintPrice":{"type":"string","description":"Maintenance margin price"},"profitRoundCount":{"type":"integer","format":"int64","description":"Number of profitable rounds"},"profitPositive":{"type":"string","description":"Total positive profit accumulated"}}}}}} ``` ## The SmartCopyOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SmartCopyOrderData":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"kolSignalId":{"type":"string","description":"KOL signal ID"},"quoteTotalInvestment":{"type":"string","description":"Current total investment in quote currency"},"quoteOriginalInvestment":{"type":"string","description":"Original investment amount in quote currency"},"currentQuoteAmount":{"type":"string","description":"Current quote amount in the bot account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"convertIntoEarnCoin":{"type":"integer","format":"int64","description":"Whether assets were converted to earn coin on close"},"reasonBy":{"type":"string","description":"Close reason (e.g. `user_cancel`, `create_failed`)"},"profit":{"type":"string","description":"Total profit in quote currency"},"status":{"type":"string","description":"Order data status"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Total profit shared"},"closedSharedQuote":{"type":"string","description":"Quote amount deducted for profit sharing on close"},"tradeType":{"type":"string","description":"Trade type: `futures` or `spot`","enum":["futures","spot"]},"fundingFee":{"type":"string","description":"Total funding fee paid"},"roundCount24h":{"type":"integer","format":"int64","description":"Number of completed signal rounds in the last 24 hours"},"kolName":{"type":"string","description":"KOL name"},"kolImage":{"type":"string","description":"KOL avatar URL"},"signalName":{"type":"string","description":"Signal display name"},"market":{"type":"string","description":"Market type"},"portfolio":{"type":"array","description":"Portfolio item details","items":{"$ref":"#/components/schemas/SmartCopyPortfolioItem"}}}},"SmartCopyPortfolioItem":{"type":"object","properties":{"tradeBase":{"type":"string","description":"Actual trading base currency"},"buOrderId":{"type":"string","description":"Bot order ID"},"base":{"type":"string","description":"Base currency for this portfolio item"},"signalType":{"type":"string","description":"Signal type identifier"},"signalParam":{"type":"string","description":"Signal parameters"},"percent":{"type":"string","description":"Allocation percentage"},"initPrice":{"type":"string","description":"Price at position open"},"closedPrice":{"type":"string","description":"Price at position close"},"currentBaseAmount":{"type":"string","description":"Current base amount held"},"closedBaseAmount":{"type":"string","description":"Base amount returned on close"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"totalFeeInBase":{"type":"string","description":"Total trading fees in base currency"},"totalFeeInQuote":{"type":"string","description":"Total trading fees in quote currency"},"profit":{"type":"string","description":"Profit for this portfolio item"},"roundCount":{"type":"integer","format":"int64","description":"Total completed signal rounds"},"currentRound":{"type":"integer","format":"int64","description":"Current signal round number"},"currentRoundMonth":{"type":"string","description":"Current round month label"},"status":{"type":"string","description":"Portfolio item status"},"expiredAt":{"type":"integer","format":"int64","description":"Expiry timestamp in milliseconds (0 = no expiry)"},"sharedAmount":{"type":"string","description":"Profit sharing amount for this item"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier"},"fundingFee":{"type":"string","description":"Funding fee for this item"},"qtyLong":{"type":"string","description":"Long position quantity"},"qtyShort":{"type":"string","description":"Short position quantity"},"amountLong":{"type":"string","description":"Long position amount in quote"},"amountShort":{"type":"string","description":"Short position amount in quote"},"amountSettle":{"type":"string","description":"Settlement amount"},"maintPrice":{"type":"string","description":"Maintenance margin price"},"profitRoundCount":{"type":"integer","format":"int64","description":"Number of profitable rounds"},"profitPositive":{"type":"string","description":"Total positive profit accumulated"}}}}}} ``` ## The SmartCopyPortfolioItem object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SmartCopyPortfolioItem":{"type":"object","properties":{"tradeBase":{"type":"string","description":"Actual trading base currency"},"buOrderId":{"type":"string","description":"Bot order ID"},"base":{"type":"string","description":"Base currency for this portfolio item"},"signalType":{"type":"string","description":"Signal type identifier"},"signalParam":{"type":"string","description":"Signal parameters"},"percent":{"type":"string","description":"Allocation percentage"},"initPrice":{"type":"string","description":"Price at position open"},"closedPrice":{"type":"string","description":"Price at position close"},"currentBaseAmount":{"type":"string","description":"Current base amount held"},"closedBaseAmount":{"type":"string","description":"Base amount returned on close"},"closedQuoteAmount":{"type":"string","description":"Quote amount returned on close"},"totalFeeInBase":{"type":"string","description":"Total trading fees in base currency"},"totalFeeInQuote":{"type":"string","description":"Total trading fees in quote currency"},"profit":{"type":"string","description":"Profit for this portfolio item"},"roundCount":{"type":"integer","format":"int64","description":"Total completed signal rounds"},"currentRound":{"type":"integer","format":"int64","description":"Current signal round number"},"currentRoundMonth":{"type":"string","description":"Current round month label"},"status":{"type":"string","description":"Portfolio item status"},"expiredAt":{"type":"integer","format":"int64","description":"Expiry timestamp in milliseconds (0 = no expiry)"},"sharedAmount":{"type":"string","description":"Profit sharing amount for this item"},"leverage":{"type":"integer","format":"int64","description":"Leverage multiplier"},"fundingFee":{"type":"string","description":"Funding fee for this item"},"qtyLong":{"type":"string","description":"Long position quantity"},"qtyShort":{"type":"string","description":"Short position quantity"},"amountLong":{"type":"string","description":"Long position amount in quote"},"amountShort":{"type":"string","description":"Short position amount in quote"},"amountSettle":{"type":"string","description":"Settlement amount"},"maintPrice":{"type":"string","description":"Maintenance margin price"},"profitRoundCount":{"type":"integer","format":"int64","description":"Number of profitable rounds"},"profitPositive":{"type":"string","description":"Total positive profit accumulated"}}}}}} ``` ## The KolSelectCopyTradeListData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolSelectCopyTradeListData":{"type":"object","description":"KOL curated copy-trade order list response","properties":{"total":{"type":"integer","format":"int64","description":"Total number of matching orders"},"page":{"type":"integer","format":"int64","description":"Current page number"},"hasMore":{"type":"boolean","description":"Whether more pages are available"},"filterOptions":{"$ref":"#/components/schemas/KolFilterOptions"},"kolInfo":{"$ref":"#/components/schemas/KolInfo"},"results":{"type":"array","description":"Curated copy-trade orders","items":{"$ref":"#/components/schemas/KolCopyTradeOrder"}},"topResults":{"type":"array","description":"Pinned/top copy-trade orders","items":{"$ref":"#/components/schemas/KolCopyTradeOrder"}}}},"KolFilterOptions":{"type":"object","description":"Available filter options for the KOL's orders","properties":{"symbolList":{"type":"array","description":"Available symbol filters","items":{"type":"string"}},"leverageList":{"type":"array","description":"Available leverage filters","items":{"type":"integer","format":"int64"}},"trendList":{"type":"array","description":"Available trend filters","items":{"type":"string"}}}},"KolInfo":{"type":"object","description":"KOL profile information","properties":{"nickname":{"type":"string","description":"KOL nickname"},"shareCode":{"type":"string","description":"KOL share code"},"headerImg":{"type":"string","description":"KOL header image URL"},"isShowInvestment":{"type":"boolean","description":"Whether investment amounts are shown"},"avatar":{"type":"string","description":"KOL avatar URL"},"userId":{"type":"string","description":"KOL user ID"},"isShowGroupEntry":{"type":"integer","format":"int64","description":"Whether the group entry is shown"},"groupInfoList":{"type":"array","description":"KOL community group list","items":{"$ref":"#/components/schemas/KolGroupInfo"}}}},"KolGroupInfo":{"type":"object","description":"KOL community group info","properties":{"id":{"type":"integer","format":"int64","description":"Group ID"},"userId":{"type":"string","description":"KOL user ID"},"community":{"type":"string","description":"Community name"},"rank":{"type":"integer","format":"int64","description":"Group rank"},"link":{"type":"string","description":"Community link"},"createTime":{"type":"string","description":"Creation time (RFC3339)"},"updateTime":{"type":"string","description":"Update time (RFC3339)"},"picUrl":{"type":"string","description":"Community picture URL"}}},"KolCopyTradeOrder":{"type":"object","description":"A KOL curated copy-trade order entry","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"buOrderType":{"type":"string","description":"Bot order type"},"rank":{"type":"integer","format":"int64","description":"Order rank"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"uniqueId":{"type":"string","description":"Unique identifier"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"isTop":{"type":"boolean","description":"Whether the order is pinned/top"},"buOrderData":{"$ref":"#/components/schemas/KolCopyTradeOrderData"}}},"KolCopyTradeOrderData":{"type":"object","description":"KOL copy-trade order detail data","properties":{"quoteInvestment":{"type":"string","description":"Investment amount in quote currency"},"extraMargin":{"type":"string","description":"Extra margin amount"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"gridApr":{"type":"string","description":"Grid APR"},"trend":{"type":"string","description":"Grid direction (e.g. long, short, no_trend)"},"leverage":{"type":"string","description":"Leverage multiplier"},"initPrice":{"type":"string","description":"Price at order creation"},"curPrice":{"type":"string","description":"Current price"},"rota":{"type":"string","description":"Return on total assets"},"uiExtraData":{"type":"string","description":"Frontend extra data"},"triggerTime":{"type":"integer","format":"int64","description":"Trigger timestamp in milliseconds"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)"}}}}}} ``` ## The KolFilterOptions object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolFilterOptions":{"type":"object","description":"Available filter options for the KOL's orders","properties":{"symbolList":{"type":"array","description":"Available symbol filters","items":{"type":"string"}},"leverageList":{"type":"array","description":"Available leverage filters","items":{"type":"integer","format":"int64"}},"trendList":{"type":"array","description":"Available trend filters","items":{"type":"string"}}}}}}} ``` ## The KolInfo object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolInfo":{"type":"object","description":"KOL profile information","properties":{"nickname":{"type":"string","description":"KOL nickname"},"shareCode":{"type":"string","description":"KOL share code"},"headerImg":{"type":"string","description":"KOL header image URL"},"isShowInvestment":{"type":"boolean","description":"Whether investment amounts are shown"},"avatar":{"type":"string","description":"KOL avatar URL"},"userId":{"type":"string","description":"KOL user ID"},"isShowGroupEntry":{"type":"integer","format":"int64","description":"Whether the group entry is shown"},"groupInfoList":{"type":"array","description":"KOL community group list","items":{"$ref":"#/components/schemas/KolGroupInfo"}}}},"KolGroupInfo":{"type":"object","description":"KOL community group info","properties":{"id":{"type":"integer","format":"int64","description":"Group ID"},"userId":{"type":"string","description":"KOL user ID"},"community":{"type":"string","description":"Community name"},"rank":{"type":"integer","format":"int64","description":"Group rank"},"link":{"type":"string","description":"Community link"},"createTime":{"type":"string","description":"Creation time (RFC3339)"},"updateTime":{"type":"string","description":"Update time (RFC3339)"},"picUrl":{"type":"string","description":"Community picture URL"}}}}}} ``` ## The KolGroupInfo object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolGroupInfo":{"type":"object","description":"KOL community group info","properties":{"id":{"type":"integer","format":"int64","description":"Group ID"},"userId":{"type":"string","description":"KOL user ID"},"community":{"type":"string","description":"Community name"},"rank":{"type":"integer","format":"int64","description":"Group rank"},"link":{"type":"string","description":"Community link"},"createTime":{"type":"string","description":"Creation time (RFC3339)"},"updateTime":{"type":"string","description":"Update time (RFC3339)"},"picUrl":{"type":"string","description":"Community picture URL"}}}}}} ``` ## The KolCopyTradeOrder object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolCopyTradeOrder":{"type":"object","description":"A KOL curated copy-trade order entry","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"buOrderType":{"type":"string","description":"Bot order type"},"rank":{"type":"integer","format":"int64","description":"Order rank"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"uniqueId":{"type":"string","description":"Unique identifier"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"isTop":{"type":"boolean","description":"Whether the order is pinned/top"},"buOrderData":{"$ref":"#/components/schemas/KolCopyTradeOrderData"}}},"KolCopyTradeOrderData":{"type":"object","description":"KOL copy-trade order detail data","properties":{"quoteInvestment":{"type":"string","description":"Investment amount in quote currency"},"extraMargin":{"type":"string","description":"Extra margin amount"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"gridApr":{"type":"string","description":"Grid APR"},"trend":{"type":"string","description":"Grid direction (e.g. long, short, no_trend)"},"leverage":{"type":"string","description":"Leverage multiplier"},"initPrice":{"type":"string","description":"Price at order creation"},"curPrice":{"type":"string","description":"Current price"},"rota":{"type":"string","description":"Return on total assets"},"uiExtraData":{"type":"string","description":"Frontend extra data"},"triggerTime":{"type":"integer","format":"int64","description":"Trigger timestamp in milliseconds"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)"}}}}}} ``` ## The KolCopyTradeOrderData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"KolCopyTradeOrderData":{"type":"object","description":"KOL copy-trade order detail data","properties":{"quoteInvestment":{"type":"string","description":"Investment amount in quote currency"},"extraMargin":{"type":"string","description":"Extra margin amount"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"gridApr":{"type":"string","description":"Grid APR"},"trend":{"type":"string","description":"Grid direction (e.g. long, short, no_trend)"},"leverage":{"type":"string","description":"Leverage multiplier"},"initPrice":{"type":"string","description":"Price at order creation"},"curPrice":{"type":"string","description":"Current price"},"rota":{"type":"string","description":"Return on total assets"},"uiExtraData":{"type":"string","description":"Frontend extra data"},"triggerTime":{"type":"integer","format":"int64","description":"Trigger timestamp in milliseconds"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)"}}}}}} ``` ## The SignalListenerRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SignalListenerRequest":{"type":"object","required":["signalType","signalParam","base","quote","time","price","data"],"properties":{"signalType":{"type":"string","description":"Signal type identifier (ASCII, max 1000 chars)"},"signalParam":{"type":"string","description":"Signal parameters (ASCII, max 5000 chars)"},"base":{"type":"string","description":"Base currency (e.g. BTC)"},"quote":{"type":"string","description":"Quote currency (e.g. USDT)"},"time":{"type":"string","format":"date-time","description":"Signal trigger time (RFC3339)"},"price":{"type":"string","description":"Price at signal trigger time (ASCII, max 30 chars)"},"data":{"$ref":"#/components/schemas/SignalListenerData"}}},"SignalListenerData":{"type":"object","required":["action","position_size","contracts"],"properties":{"action":{"type":"string","description":"Trading action","enum":["buy","sell"]},"position_size":{"type":"string","description":"Position size as a ratio or absolute value"},"contracts":{"type":"string","description":"Number of contracts"},"direction":{"type":"string","description":"Optional trading direction hint"}}}}}} ``` ## The SignalListenerData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"SignalListenerData":{"type":"object","required":["action","position_size","contracts"],"properties":{"action":{"type":"string","description":"Trading action","enum":["buy","sell"]},"position_size":{"type":"string","description":"Position size as a ratio or absolute value"},"contracts":{"type":"string","description":"Number of contracts"},"direction":{"type":"string","description":"Optional trading direction hint"}}}}}} ``` ## The CreateUserSignalRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"CreateUserSignalRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"Signal description (max 1000 chars)","maxLength":1000}}}}}} ``` ## The EditUserSignalRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"EditUserSignalRequest":{"type":"object","description":"At least one field must be provided.","properties":{"title":{"type":"string","description":"New signal name (max 100 chars)","maxLength":100},"description":{"type":"string","description":"New signal description (max 10000 chars)","maxLength":10000}}}}}} ``` ## The TradingViewConfig object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}}}}} ``` ## The UserSignalDetail object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}}}}} ``` ## The UserSignalListResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"components":{"schemas":{"UserSignalListResponse":{"type":"object","properties":{"pageToken":{"type":"string","description":"Pagination token for the next page. Empty string when there are no more results."},"signals":{"type":"array","description":"List of user-defined signals","items":{"$ref":"#/components/schemas/UserSignalDetail"}}}},"UserSignalDetail":{"type":"object","properties":{"signalType":{"type":"string","description":"Signal type identifier (auto-generated)"},"title":{"type":"string","description":"Signal name"},"description":{"type":"string","description":"Signal description"},"confirmConfig":{"type":"integer","description":"Whether the webhook is configured: 0 = not confirmed, 1 = confirmed","enum":[0,1]},"tradingviewConfig":{"$ref":"#/components/schemas/TradingViewConfig"}}},"TradingViewConfig":{"type":"object","properties":{"webhookUrl":{"type":"string","description":"Webhook URL to configure in TradingView"},"message":{"type":"string","description":"JSON message template to use in TradingView alert"}}}}}} ``` # Earn API REST endpoints for Pionex Earn arbitrage products.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/earn-api/general-info
## APIs

:square-terminal:

Arbitragehttps://www.pionex.com/docs/api-docs/earn-api/arbitrage
# General Info # Basic Info > **Note:** The Arbitrage API is currently in **Beta**. If you would like to use it, please contact us at with your UID and reason for applying. **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of +/-20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {...}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "ARBITRAGE_PARAMETER_ERROR", "message": "invalid amount", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions **Endpoints requiring `Enable reading` permission:** * `GET /api/v1/earn/arbitrage/fetchProducts` — List Arbitrage products * `GET /api/v1/earn/arbitrage/fetchUserBalances` — Get user Arbitrage balances **Endpoints requiring `Earn` permission:** * `POST /api/v1/earn/arbitrage/stake` — Stake into an Arbitrage product * `POST /api/v1/earn/arbitrage/unStake` — Redeem from an Arbitrage product # Arbitrage Term Arbitrage endpoints ## List Arbitrage products > Returns the list of Term Arbitrage products currently available. Requires \`View\` permission. Weight: 1.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/earn/arbitrage/fetchProducts?timestamp=1774959429596\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"tags":[{"name":"Arbitrage","description":"Term Arbitrage endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `ARBITRAGE_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `ARBITRAGE_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/arbitrage/fetchProducts":{"get":{"tags":["Arbitrage"],"summary":"List Arbitrage products","description":"Returns the list of Term Arbitrage products currently available. Requires `View` permission. Weight: 1.\n\nExample request:\n```\nGET /api/v1/earn/arbitrage/fetchProducts?timestamp=1774959429596\n```\n","operationId":"arbitrageFetchProducts","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Product list (pass-through of the upstream gRPC Products response)"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Get user Arbitrage balances > Returns the authenticated user's Term Arbitrage positions and balances. Requires \`View\` permission. Weight: 1.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/earn/arbitrage/fetchUserBalances?timestamp=1774959429596\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"tags":[{"name":"Arbitrage","description":"Term Arbitrage endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `ARBITRAGE_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `ARBITRAGE_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/arbitrage/fetchUserBalances":{"get":{"tags":["Arbitrage"],"summary":"Get user Arbitrage balances","description":"Returns the authenticated user's Term Arbitrage positions and balances. Requires `View` permission. Weight: 1.\n\nExample request:\n```\nGET /api/v1/earn/arbitrage/fetchUserBalances?timestamp=1774959429596\n```\n","operationId":"arbitrageFetchUserBalances","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"User balances (pass-through of the upstream gRPC FetchUserBalancesResponse)"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Stake into an Arbitrage product > Subscribes to a Term Arbitrage product. Requires \`Earn\` permission. Weight: 1.\ > \ > \*\*Validation:\*\*\ > \- \`amount\` must be a valid decimal amount.\ > \- \`productId\` must exist in the product list returned by \`GET /api/v1/earn/arbitrage/fetchProducts\`.\ > \- \`coin\` must be one of \`USDT\` or \`USDC\`.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "productId": "ARB-USDT-30D",\ > "coin": "USDT",\ > "amount": "100"\ > }\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "request\_id": "req-abcdef",\ > "status": "success",\ > "txid": "tx-123456"\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"tags":[{"name":"Arbitrage","description":"Term Arbitrage endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ArbitrageStakeRequest":{"type":"object","required":["productId","coin","amount"],"properties":{"productId":{"type":"string","description":"Product ID. Must exist in the product list from `/api/v1/earn/arbitrage/fetchProducts`."},"coin":{"type":"string","description":"Subscription currency. Only `USDT` or `USDC` are supported.","enum":["USDT","USDC"]},"amount":{"type":"string","description":"Subscription amount as a decimal string"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ArbitrageTxData":{"type":"object","properties":{"request_id":{"type":"string","description":"Request ID assigned by the upstream Arbitrage service"},"status":{"type":"string","description":"Transaction status (e.g. `success`)"},"txid":{"type":"string","description":"Transaction ID"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `ARBITRAGE_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `ARBITRAGE_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/arbitrage/stake":{"post":{"tags":["Arbitrage"],"summary":"Stake into an Arbitrage product","description":"Subscribes to a Term Arbitrage product. Requires `Earn` permission. Weight: 1.\n\n**Validation:**\n- `amount` must be a valid decimal amount.\n- `productId` must exist in the product list returned by `GET /api/v1/earn/arbitrage/fetchProducts`.\n- `coin` must be one of `USDT` or `USDC`.\n\nExample request body:\n```json\n{\n \"productId\": \"ARB-USDT-30D\",\n \"coin\": \"USDT\",\n \"amount\": \"100\"\n}\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"request_id\": \"req-abcdef\",\n \"status\": \"success\",\n \"txid\": \"tx-123456\"\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"arbitrageStake","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArbitrageStakeRequest"}}}},"responses":{"200":{"description":"Stake succeeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ArbitrageTxData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Redeem from an Arbitrage product > Redeems from a Term Arbitrage product. Requires \`Earn\` permission. Weight: 1.\ > \ > \*\*Validation:\*\*\ > \- \`amount\` must be a valid decimal amount.\ > \- \`productId\` must exist in the product list returned by \`GET /api/v1/earn/arbitrage/fetchProducts\`.\ > \- \`coin\` must be one of \`USDT\` or \`USDC\`.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "productId": "ARB-USDT-30D",\ > "coin": "USDT",\ > "amount": "100"\ > }\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "status": "success"\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"tags":[{"name":"Arbitrage","description":"Term Arbitrage endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ArbitrageUnStakeRequest":{"type":"object","required":["productId","coin","amount"],"properties":{"productId":{"type":"string","description":"Product ID. Must exist in the product list from `/api/v1/earn/arbitrage/fetchProducts`."},"coin":{"type":"string","description":"Redemption currency. Only `USDT` or `USDC` are supported.","enum":["USDT","USDC"]},"amount":{"type":"string","description":"Redemption amount as a decimal string"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ArbitrageUnStakeData":{"type":"object","properties":{"status":{"type":"string","description":"Transaction status (e.g. `success`)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `ARBITRAGE_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `ARBITRAGE_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/arbitrage/unStake":{"post":{"tags":["Arbitrage"],"summary":"Redeem from an Arbitrage product","description":"Redeems from a Term Arbitrage product. Requires `Earn` permission. Weight: 1.\n\n**Validation:**\n- `amount` must be a valid decimal amount.\n- `productId` must exist in the product list returned by `GET /api/v1/earn/arbitrage/fetchProducts`.\n- `coin` must be one of `USDT` or `USDC`.\n\nExample request body:\n```json\n{\n \"productId\": \"ARB-USDT-30D\",\n \"coin\": \"USDT\",\n \"amount\": \"100\"\n}\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"status\": \"success\"\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"arbitrageUnStake","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArbitrageUnStakeRequest"}}}},"responses":{"200":{"description":"Redemption succeeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ArbitrageUnStakeData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `ARBITRAGE_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}}}} ``` ## The ArbitrageStakeRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"ArbitrageStakeRequest":{"type":"object","required":["productId","coin","amount"],"properties":{"productId":{"type":"string","description":"Product ID. Must exist in the product list from `/api/v1/earn/arbitrage/fetchProducts`."},"coin":{"type":"string","description":"Subscription currency. Only `USDT` or `USDC` are supported.","enum":["USDT","USDC"]},"amount":{"type":"string","description":"Subscription amount as a decimal string"}}}}}} ``` ## The ArbitrageUnStakeRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"ArbitrageUnStakeRequest":{"type":"object","required":["productId","coin","amount"],"properties":{"productId":{"type":"string","description":"Product ID. Must exist in the product list from `/api/v1/earn/arbitrage/fetchProducts`."},"coin":{"type":"string","description":"Redemption currency. Only `USDT` or `USDC` are supported.","enum":["USDT","USDC"]},"amount":{"type":"string","description":"Redemption amount as a decimal string"}}}}}} ``` ## The ArbitrageTxData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"ArbitrageTxData":{"type":"object","properties":{"request_id":{"type":"string","description":"Request ID assigned by the upstream Arbitrage service"},"status":{"type":"string","description":"Transaction status (e.g. `success`)"},"txid":{"type":"string","description":"Transaction ID"}}}}}} ``` ## The ArbitrageUnStakeData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Arbitrage","version":"1.0.0"},"components":{"schemas":{"ArbitrageUnStakeData":{"type":"object","properties":{"status":{"type":"string","description":"Transaction status (e.g. `success`)"}}}}}} ``` # Earn Dual API REST endpoints for Dual Investment products.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/earn-dual-api/general-info
## APIs

:square-terminal:

Dualhttps://www.pionex.com/docs/api-docs/earn-dual-api/dual
# General Info # Basic Info > **Note:** The Dual Investment API is currently in **Beta**. If you would like to use it, please contact us at with your UID and reason for applying. **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of +/-20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {...}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "DUAL_PARAMETER_ERROR", "message": "invalid base quote", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions **Public endpoints (no authentication required):** * `GET /api/v1/earn/dual/symbols` — List supported trading pairs * `GET /api/v1/earn/dual/openProducts` — List open products * `GET /api/v1/earn/dual/prices` — Get product prices * `GET /api/v1/earn/dual/index` — Get underlying index price * `GET /api/v1/earn/dual/deliveryPrices` — Get historical delivery prices **Endpoints requiring `Enable reading` permission:** * `GET /api/v1/earn/dual/balances` — Get user balances * `POST /api/v1/earn/dual/invests` — Batch query investment orders * `GET /api/v1/earn/dual/records` — Get investment history **Endpoints requiring `Earn` permission:** * `POST /api/v1/earn/dual/invest` — Create investment order * `DELETE /api/v1/earn/dual/invest` — Revoke investment order * `POST /api/v1/earn/dual/collect` — Collect settled earnings # Dual Dual Investment endpoints ## List supported trading pairs > Returns all trading pairs supported by Dual Investment, optionally filtered by base currency. Weight: 1.\ > \ > Supported quote currencies include: \`USDT\`, \`USDC\`, \`USD\`, \`USDXO\`.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/earn/dual/symbols?base=BTC\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "coins": \[\ > {\ > "base": "BTC",\ > "quote": "USDT",\ > "currency": "USDT",\ > "basePrecision": 8,\ > "currencyPrecision": 8,\ > "baseMin": "0.00001",\ > "currencyMin": "1",\ > "baseMax": "80",\ > "currencyMax": "2000000"\ > }\ > ]\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[],"paths":{"/api/v1/earn/dual/symbols":{"get":{"tags":["Dual"],"summary":"List supported trading pairs","description":"Returns all trading pairs supported by Dual Investment, optionally filtered by base currency. Weight: 1.\n\nSupported quote currencies include: `USDT`, `USDC`, `USD`, `USDXO`.\n\nExample request:\n```\nGET /api/v1/earn/dual/symbols?base=BTC\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"coins\": [\n {\n \"base\": \"BTC\",\n \"quote\": \"USDT\",\n \"currency\": \"USDT\",\n \"basePrecision\": 8,\n \"currencyPrecision\": 8,\n \"baseMin\": \"0.00001\",\n \"currencyMin\": \"1\",\n \"baseMax\": \"80\",\n \"currencyMax\": \"2000000\"\n }\n ]\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"dualSymbols","parameters":[{"name":"base","in":"query","required":false,"description":"Base currency filter (e.g. `BTC`, `ETH`). Omit to return all supported pairs.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualSymbolsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualSymbolsData":{"type":"object","properties":{"coins":{"type":"array","items":{"$ref":"#/components/schemas/DualCoinSymbol"}}}},"DualCoinSymbol":{"type":"object","properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency. Supported values: `USDT`, `USDC`, `USD`, `USDXO`"},"currency":{"type":"string","description":"Investment currency (the currency used to place the order)"},"basePrecision":{"type":"integer","format":"int64","description":"Decimal precision for base currency amounts"},"currencyPrecision":{"type":"integer","format":"int64","description":"Decimal precision for investment currency amounts"},"baseMin":{"type":"string","description":"Minimum investment amount in base currency"},"currencyMin":{"type":"string","description":"Minimum investment amount in investment currency"},"baseMax":{"type":"string","description":"Maximum investment amount in base currency"},"currencyMax":{"type":"string","description":"Maximum investment amount in investment currency"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ```` ## List open products > Returns currently open Dual Investment products for a specific trading pair and type. Weight: 1.\ > \ > \*\*Type semantics:\*\*\ > \- \`DUAL\_BASE\`: invest in base currency (e.g. BTC); if price rises above strike at expiry, principal + yield are returned in base currency, otherwise converted to quote currency\ > \- \`DUAL\_CURRENCY\`: invest in quote/investment currency (e.g. USDT); if price falls below strike at expiry, principal + yield are returned in quote currency, otherwise converted to base currency\ > \ > \*\*Quote currency rules:\*\*\ > \- \`base=BTC\` or \`base=ETH\`: use \`quote=USDXO\`, \`currency=USDT\` or \`USDC\`\ > \- All other base currencies: use \`quote=USDT\`, \`currency=USDT\`\ > \ > Example request (BTC, DUAL\_BASE):\ > \`\`\`\ > GET /api/v1/earn/dual/openProducts?base=BTC\"e=USDXO\¤cy=USDT\&type=DUAL\_BASE\ > \`\`\`\ > \ > Example request (XRP, DUAL\_BASE):\ > \`\`\`\ > GET /api/v1/earn/dual/openProducts?base=XRP\"e=USDT\¤cy=USDT\&type=DUAL\_BASE\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "products": \[\ > {\ > "productId": "BTC-USDXO-260401-69000-C-USDT",\ > "base": "BTC",\ > "quote": "USDXO",\ > "currency": "USDT",\ > "type": "DUAL\_BASE",\ > "createTime": 1774686600000,\ > "expireTime": 1775030400000,\ > "strike": "69000",\ > "expired": false\ > }\ > ]\ > },\ > "timestamp": 1775025855477\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[],"paths":{"/api/v1/earn/dual/openProducts":{"get":{"tags":["Dual"],"summary":"List open products","description":"Returns currently open Dual Investment products for a specific trading pair and type. Weight: 1.\n\n**Type semantics:**\n- `DUAL_BASE`: invest in base currency (e.g. BTC); if price rises above strike at expiry, principal + yield are returned in base currency, otherwise converted to quote currency\n- `DUAL_CURRENCY`: invest in quote/investment currency (e.g. USDT); if price falls below strike at expiry, principal + yield are returned in quote currency, otherwise converted to base currency\n\n**Quote currency rules:**\n- `base=BTC` or `base=ETH`: use `quote=USDXO`, `currency=USDT` or `USDC`\n- All other base currencies: use `quote=USDT`, `currency=USDT`\n\nExample request (BTC, DUAL_BASE):\n```\nGET /api/v1/earn/dual/openProducts?base=BTC"e=USDXO¤cy=USDT&type=DUAL_BASE\n```\n\nExample request (XRP, DUAL_BASE):\n```\nGET /api/v1/earn/dual/openProducts?base=XRP"e=USDT¤cy=USDT&type=DUAL_BASE\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"products\": [\n {\n \"productId\": \"BTC-USDXO-260401-69000-C-USDT\",\n \"base\": \"BTC\",\n \"quote\": \"USDXO\",\n \"currency\": \"USDT\",\n \"type\": \"DUAL_BASE\",\n \"createTime\": 1774686600000,\n \"expireTime\": 1775030400000,\n \"strike\": \"69000\",\n \"expired\": false\n }\n ]\n },\n \"timestamp\": 1775025855477\n}\n```\n","operationId":"dualProducts","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency (e.g. `BTC`, `ETH`, `XRP`)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote currency. Use `USDXO` for BTC/ETH; use `USDT` for all other base currencies.","schema":{"type":"string","enum":["USDT","USDC","USDXO"]}},{"name":"type","in":"query","required":true,"description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","schema":{"type":"string","enum":["DUAL_BASE","DUAL_CURRENCY"]}},{"name":"currency","in":"query","required":false,"description":"Investment currency filter. For BTC/ETH pairs: `USDT` or `USDC`. For other pairs: `USDT`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualProductsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualProductsData":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/DualProduct"}}}},"DualProduct":{"type":"object","properties":{"productId":{"type":"string","description":"Unique product ID. Format: `{BASE}-{QUOTE}-{YYMMDD}-{STRIKE}-{C|P}-{CURRENCY}`. `C` = DUAL_BASE, `P` = DUAL_CURRENCY."},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"createTime":{"type":"integer","format":"int64","description":"Product creation timestamp in milliseconds"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"strike":{"type":"string","description":"Strike price — the threshold price at settlement"},"expired":{"type":"boolean","description":"Whether the product has already expired"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ```` ## Get product prices > Returns the latest yield rate and investability status for Dual Investment products. Weight: 1.\ > \ > \*\*All three parameters are required:\*\* \`base\`, \`quote\`, and \`productIds\`.\ > Omitting any one of them will return a \`DUAL\_PARAMETER\_ERROR\`.\ > \ > \`productIds\` is a comma-separated list of product IDs. Works for both \`USDT\` and \`USDXO\` quoted pairs.\ > \ > When \`canInvest\` is \`false\`, \`profit\` and \`baseSize\` will be empty strings.\ > \ > \> \*\*Workflow note:\*\* Always call this endpoint before placing an order. The \`profit\` value returned here must be passed as-is to \`POST /api/v1/earn/dual/invest\`. Submitting a stale or mismatched \`profit\` will be rejected.\ > \ > Example request (USDT pair):\ > \`\`\`\ > GET /api/v1/earn/dual/prices?base=LRC\"e=USDT\&productIds=LRC-USDT-260410-0.03-C-USDT,LRC-USDT-260410-0.02-C-USDT\ > \`\`\`\ > \ > Example request (USDXO pair):\ > \`\`\`\ > GET /api/v1/earn/dual/prices?base=ETH\"e=USDXO\&productIds=ETH-USDXO-260410-3000-C-USDT,ETH-USDXO-260410-2900-C-USDT\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "products": \[\ > {\ > "productId": "LRC-USDT-260410-0.02-C-USDT",\ > "canInvest": true,\ > "profit": "0.01242",\ > "baseSize": "8000000",\ > "updateTime": 1775026225630\ > },\ > {\ > "productId": "LRC-USDT-260410-0.03-C-USDT",\ > "canInvest": false,\ > "profit": "0",\ > "baseSize": "",\ > "updateTime": 0\ > }\ > ]\ > },\ > "timestamp": 1775026244892\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[],"paths":{"/api/v1/earn/dual/prices":{"get":{"tags":["Dual"],"summary":"Get product prices","description":"Returns the latest yield rate and investability status for Dual Investment products. Weight: 1.\n\n**All three parameters are required:** `base`, `quote`, and `productIds`.\nOmitting any one of them will return a `DUAL_PARAMETER_ERROR`.\n\n`productIds` is a comma-separated list of product IDs. Works for both `USDT` and `USDXO` quoted pairs.\n\nWhen `canInvest` is `false`, `profit` and `baseSize` will be empty strings.\n\n> **Workflow note:** Always call this endpoint before placing an order. The `profit` value returned here must be passed as-is to `POST /api/v1/earn/dual/invest`. Submitting a stale or mismatched `profit` will be rejected.\n\nExample request (USDT pair):\n```\nGET /api/v1/earn/dual/prices?base=LRC"e=USDT&productIds=LRC-USDT-260410-0.03-C-USDT,LRC-USDT-260410-0.02-C-USDT\n```\n\nExample request (USDXO pair):\n```\nGET /api/v1/earn/dual/prices?base=ETH"e=USDXO&productIds=ETH-USDXO-260410-3000-C-USDT,ETH-USDXO-260410-2900-C-USDT\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"products\": [\n {\n \"productId\": \"LRC-USDT-260410-0.02-C-USDT\",\n \"canInvest\": true,\n \"profit\": \"0.01242\",\n \"baseSize\": \"8000000\",\n \"updateTime\": 1775026225630\n },\n {\n \"productId\": \"LRC-USDT-260410-0.03-C-USDT\",\n \"canInvest\": false,\n \"profit\": \"0\",\n \"baseSize\": \"\",\n \"updateTime\": 0\n }\n ]\n },\n \"timestamp\": 1775026244892\n}\n```\n","operationId":"dualPrices","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency (e.g. `BTC`, `ETH`, `LRC`)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote currency. Use `USDXO` for BTC/ETH pairs; use `USDT` for all other base currencies.","schema":{"type":"string","enum":["USDT","USDC","USDXO"]}},{"name":"productIds","in":"query","required":true,"description":"Comma-separated product ID list. Multiple IDs are supported (e.g. `ETH-USDXO-260410-3000-C-USDT,ETH-USDXO-260410-2900-C-USDT`). Obtain IDs from `/openProducts`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualPricesData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualPricesData":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/DualPrice"}}}},"DualPrice":{"type":"object","properties":{"productId":{"type":"string","description":"Product ID"},"canInvest":{"type":"boolean","description":"Whether the product is currently open for new investment"},"profit":{"type":"string","description":"Annualized yield rate (e.g. `0.0215` = 2.15%)"},"baseSize":{"type":"string","description":"Base currency amount per unit"},"updateTime":{"type":"integer","format":"int64","description":"Last price update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ```` ## Get underlying index price > Returns the real-time index price for a Dual Investment underlying asset. Weight: 1.\ > \ > Both \`base\` and \`quote\` are required. Works for both \`USDT\` and \`USDXO\` quoted pairs.\ > \ > The index price is the reference price used at settlement to determine whether the strike price was hit.\ > \ > Example request (USDXO pair):\ > \`\`\`\ > GET /api/v1/earn/dual/index?base=BTC\"e=USDXO\ > \`\`\`\ > \ > Example request (USDT pair):\ > \`\`\`\ > GET /api/v1/earn/dual/index?base=LRC\"e=USDT\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "index": "69142.6",\ > "base": "BTC",\ > "quote": "USDXO",\ > "updateTime": 1775025942486\ > },\ > "timestamp": 1775025942754\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[],"paths":{"/api/v1/earn/dual/index":{"get":{"tags":["Dual"],"summary":"Get underlying index price","description":"Returns the real-time index price for a Dual Investment underlying asset. Weight: 1.\n\nBoth `base` and `quote` are required. Works for both `USDT` and `USDXO` quoted pairs.\n\nThe index price is the reference price used at settlement to determine whether the strike price was hit.\n\nExample request (USDXO pair):\n```\nGET /api/v1/earn/dual/index?base=BTC"e=USDXO\n```\n\nExample request (USDT pair):\n```\nGET /api/v1/earn/dual/index?base=LRC"e=USDT\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"index\": \"69142.6\",\n \"base\": \"BTC\",\n \"quote\": \"USDXO\",\n \"updateTime\": 1775025942486\n },\n \"timestamp\": 1775025942754\n}\n```\n","operationId":"dualIndex","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency (e.g. `BTC`, `ETH`, `LRC`)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote currency. Use `USDXO` for BTC/ETH pairs; use `USDT` for all other base currencies.","schema":{"type":"string","enum":["USDT","USDC","USDXO"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualIndexData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualIndexData":{"type":"object","properties":{"index":{"type":"string","description":"Current real-time index price"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ```` ## Get historical delivery prices > Returns historical settlement delivery prices for a Dual Investment pair. Weight: 1.\ > \ > The delivery price is the index price recorded at the exact moment of each product's expiry,\ > used to determine the settlement direction (base or quote currency payout).\ > \ > \`base\` is required. \`quote\` is optional but recommended to narrow results — use \`USDXO\` for BTC/ETH pairs and \`USDT\` for all other base currencies.\ > \ > Example request (BTC/USDXO):\ > \`\`\`\ > GET /api/v1/earn/dual/deliveryPrices?base=BTC\"e=USDXO\ > \`\`\`\ > \ > Example request (XRP/USDT):\ > \`\`\`\ > GET /api/v1/earn/dual/deliveryPrices?base=XRP\"e=USDT\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "prices": \[\ > {\ > "delivery": "69142.6",\ > "date": "2026-04-01",\ > "deliveryTime": 1775030400000\ > }\ > ]\ > },\ > "timestamp": 1775026529937\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[],"paths":{"/api/v1/earn/dual/deliveryPrices":{"get":{"tags":["Dual"],"summary":"Get historical delivery prices","description":"Returns historical settlement delivery prices for a Dual Investment pair. Weight: 1.\n\nThe delivery price is the index price recorded at the exact moment of each product's expiry,\nused to determine the settlement direction (base or quote currency payout).\n\n`base` is required. `quote` is optional but recommended to narrow results — use `USDXO` for BTC/ETH pairs and `USDT` for all other base currencies.\n\nExample request (BTC/USDXO):\n```\nGET /api/v1/earn/dual/deliveryPrices?base=BTC"e=USDXO\n```\n\nExample request (XRP/USDT):\n```\nGET /api/v1/earn/dual/deliveryPrices?base=XRP"e=USDT\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"prices\": [\n {\n \"delivery\": \"69142.6\",\n \"date\": \"2026-04-01\",\n \"deliveryTime\": 1775030400000\n }\n ]\n },\n \"timestamp\": 1775026529937\n}\n```\n","operationId":"deliveryPrices","parameters":[{"name":"base","in":"query","required":true,"description":"Base currency (e.g. `BTC`, `XRP`)","schema":{"type":"string"}},{"name":"quote","in":"query","required":false,"description":"Quote currency filter. Use `USDXO` for BTC/ETH pairs; use `USDT` for all other base currencies.","schema":{"type":"string","enum":["USDT","USDC","USDXO"]}},{"name":"startTime","in":"query","required":false,"description":"Start timestamp in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","required":false,"description":"End timestamp in milliseconds","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryPricesData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DeliveryPricesData":{"type":"object","properties":{"prices":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryPrice"}}}},"DeliveryPrice":{"type":"object","properties":{"delivery":{"type":"string","description":"Settlement delivery price (index price at expiry)"},"date":{"type":"string","description":"Delivery date in `YYYY-MM-DD` format"},"deliveryTime":{"type":"integer","format":"int64","description":"Delivery timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}} ```` ## Get user balances > Returns the authenticated user's Dual Investment account balances. Requires \`View\` permission. Weight: 1.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/earn/dual/balances?timestamp=1774959429596\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "balances": \[\ > {\ > "base": "BTC",\ > "coin": "USDT",\ > "free": "100.00",\ > "frozen": "50.00",\ > "updateTime": 1774959429596\ > }\ > ]\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualBalancesData":{"type":"object","properties":{"balances":{"type":"array","items":{"$ref":"#/components/schemas/DualBalance"}}}},"DualBalance":{"type":"object","properties":{"base":{"type":"string","description":"Base currency this balance is associated with"},"coin":{"type":"string","description":"The actual currency of the balance"},"free":{"type":"string","description":"Available (unlocked) balance"},"frozen":{"type":"string","description":"Frozen balance currently locked in active orders"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/balances":{"get":{"tags":["Dual"],"summary":"Get user balances","description":"Returns the authenticated user's Dual Investment account balances. Requires `View` permission. Weight: 1.\n\nExample request:\n```\nGET /api/v1/earn/dual/balances?timestamp=1774959429596\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"balances\": [\n {\n \"base\": \"BTC\",\n \"coin\": \"USDT\",\n \"free\": \"100.00\",\n \"frozen\": \"50.00\",\n \"updateTime\": 1774959429596\n }\n ]\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"dualBalances","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"merge","in":"query","required":false,"description":"When `true`, merges balances with the same coin across different base currencies","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualBalancesData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Create investment order > Creates a new Dual Investment order. Requires \`Earn\` permission. Weight: 1.\ > \ > Provide either \`baseAmount\` (invest in base currency) or \`currencyAmount\` (invest in investment currency), not both.\ > \ > \> \*\*Workflow:\*\* Call \`GET /api/v1/earn/dual/prices\` first to obtain the current \`profit\` value, then pass it unchanged to this endpoint. The \`profit\` field must match the live price — a stale or mismatched value will be rejected.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "base": "BTC",\ > "productId": "BTC-USDXO-260402-68000-P-USDT",\ > "clientDualId": "my-order-001",\ > "currencyAmount": "100",\ > "profit": "0.0039"\ > }\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "clientDualId": "my-order-001",\ > "state": "CONFIRMED"\ > },\ > "timestamp": 1775027817297\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"DualInvestRequest":{"type":"object","required":["base"],"properties":{"base":{"type":"string","description":"Base currency"},"clientDualId":{"type":"string","description":"Client-assigned order ID used as an idempotency key. Recommended to avoid duplicate orders."},"productId":{"type":"string","description":"Product ID to invest in"},"baseAmount":{"type":"string","description":"Investment amount in base currency (e.g. BTC). Mutually exclusive with `currencyAmount`."},"currencyAmount":{"type":"string","description":"Investment amount in investment currency (e.g. USDT). Mutually exclusive with `baseAmount`."},"profit":{"type":"string","description":"Expected yield rate. Must match the current price from `/prices`."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualInvestData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state after creation (e.g. `CONFIRMED`)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/invest":{"post":{"tags":["Dual"],"summary":"Create investment order","description":"Creates a new Dual Investment order. Requires `Earn` permission. Weight: 1.\n\nProvide either `baseAmount` (invest in base currency) or `currencyAmount` (invest in investment currency), not both.\n\n> **Workflow:** Call `GET /api/v1/earn/dual/prices` first to obtain the current `profit` value, then pass it unchanged to this endpoint. The `profit` field must match the live price — a stale or mismatched value will be rejected.\n\nExample request body:\n```json\n{\n \"base\": \"BTC\",\n \"productId\": \"BTC-USDXO-260402-68000-P-USDT\",\n \"clientDualId\": \"my-order-001\",\n \"currencyAmount\": \"100\",\n \"profit\": \"0.0039\"\n}\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"clientDualId\": \"my-order-001\",\n \"state\": \"CONFIRMED\"\n },\n \"timestamp\": 1775027817297\n}\n```\n","operationId":"dualInvest","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualInvestRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualInvestData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Revoke investment order > Revokes a pending Dual Investment order before it is matched. Requires \`Earn\` permission. Weight: 1.\ > \ > Parameters are passed as a JSON request body, not query string.\ > Only orders in a pending/unmatched state can be revoked.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "base": "BTC",\ > "productId": "BTC-USDXO-260402-68000-P-USDT",\ > "clientDualId": "my-order-001"\ > }\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "clientDualId": "my-order-001"\ > },\ > "timestamp": 1775027817297\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"DualRevokeInvestRequest":{"type":"object","required":["base","productId","clientDualId"],"properties":{"base":{"type":"string","description":"Base currency"},"productId":{"type":"string","description":"Product ID of the order to revoke"},"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualRevokeInvestData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/invest":{"delete":{"tags":["Dual"],"summary":"Revoke investment order","description":"Revokes a pending Dual Investment order before it is matched. Requires `Earn` permission. Weight: 1.\n\nParameters are passed as a JSON request body, not query string.\nOnly orders in a pending/unmatched state can be revoked.\n\nExample request body:\n```json\n{\n \"base\": \"BTC\",\n \"productId\": \"BTC-USDXO-260402-68000-P-USDT\",\n \"clientDualId\": \"my-order-001\"\n}\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"clientDualId\": \"my-order-001\"\n },\n \"timestamp\": 1775027817297\n}\n```\n","operationId":"dualRevokeInvest","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualRevokeInvestRequest"}}}},"responses":{"200":{"description":"Order revoked successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualRevokeInvestData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Batch query investment orders > Returns details for a batch of Dual Investment orders by client order ID list. Requires \`View\` permission. Weight: 1.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "base": "BTC",\ > "clientDualIds": \["my-order-001", "my-order-002"]\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"DualGetInvestsRequest":{"type":"object","properties":{"base":{"type":"string","description":"Base currency"},"clientDualIds":{"type":"array","items":{"type":"string"},"description":"List of client-assigned dual investment order IDs to query"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualInvestRecordsData":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DualRecord"}}}},"DualRecord":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state"},"productId":{"type":"string","description":"Product ID"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"strike":{"type":"string","description":"Strike price"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"baseAmount":{"type":"string","description":"Investment amount in base currency"},"currencyAmount":{"type":"string","description":"Investment amount in investment currency"},"profit":{"type":"string","description":"Yield rate at time of investment (e.g. `0.0215` = 2.15%)"},"baseFilled":{"type":"string","description":"Matched/filled amount in base currency"},"currencyFilled":{"type":"string","description":"Matched/filled amount in investment currency"},"settlementState":{"type":"string","description":"Settlement state"},"settlementTime":{"type":"integer","format":"int64","description":"Settlement timestamp in milliseconds"},"settlementBase":{"type":"string","description":"Currency received as principal at settlement"},"settlementCurrency":{"type":"string","description":"Currency received as earnings at settlement"},"deliveryPrice":{"type":"string","description":"Index price recorded at settlement"},"createTime":{"type":"integer","format":"int64","description":"Order creation timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/invests":{"post":{"tags":["Dual"],"summary":"Batch query investment orders","description":"Returns details for a batch of Dual Investment orders by client order ID list. Requires `View` permission. Weight: 1.\n\nExample request body:\n```json\n{\n \"base\": \"BTC\",\n \"clientDualIds\": [\"my-order-001\", \"my-order-002\"]\n}\n```\n","operationId":"dualGetInvests","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualGetInvestsRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualInvestRecordsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Get investment history > Returns paginated Dual Investment history for the authenticated user. Requires \`View\` permission. Weight: 1.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/earn/dual/records?base=BTC\"e=USDXO\&limit=10\&endTime=1775027817297\×tamp=1775027817297\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualInvestRecordsData":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DualRecord"}}}},"DualRecord":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state"},"productId":{"type":"string","description":"Product ID"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"strike":{"type":"string","description":"Strike price"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"baseAmount":{"type":"string","description":"Investment amount in base currency"},"currencyAmount":{"type":"string","description":"Investment amount in investment currency"},"profit":{"type":"string","description":"Yield rate at time of investment (e.g. `0.0215` = 2.15%)"},"baseFilled":{"type":"string","description":"Matched/filled amount in base currency"},"currencyFilled":{"type":"string","description":"Matched/filled amount in investment currency"},"settlementState":{"type":"string","description":"Settlement state"},"settlementTime":{"type":"integer","format":"int64","description":"Settlement timestamp in milliseconds"},"settlementBase":{"type":"string","description":"Currency received as principal at settlement"},"settlementCurrency":{"type":"string","description":"Currency received as earnings at settlement"},"deliveryPrice":{"type":"string","description":"Index price recorded at settlement"},"createTime":{"type":"integer","format":"int64","description":"Order creation timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/records":{"get":{"tags":["Dual"],"summary":"Get investment history","description":"Returns paginated Dual Investment history for the authenticated user. Requires `View` permission. Weight: 1.\n\nExample request:\n```\nGET /api/v1/earn/dual/records?base=BTC"e=USDXO&limit=10&endTime=1775027817297×tamp=1775027817297\n```\n","operationId":"dualInvestRecords","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"base","in":"query","required":true,"description":"Base currency (e.g. `BTC`)","schema":{"type":"string"}},{"name":"quote","in":"query","required":false,"description":"Quote currency filter (e.g. `USDT`)","schema":{"type":"string"}},{"name":"currency","in":"query","required":false,"description":"Investment currency filter (e.g. `USDT`, `BTC`)","schema":{"type":"string"}},{"name":"filter","in":"query","required":false,"description":"Status filter","schema":{"type":"string"}},{"name":"startTime","in":"query","required":false,"description":"Start timestamp in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"endTime","in":"query","required":true,"description":"End timestamp in milliseconds","schema":{"type":"integer","format":"int64"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of records to return per page","schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualInvestRecordsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Collect settled earnings > Collects settled Dual Investment earnings into the user's spot account. Requires \`Earn\` permission. Weight: 1.\ > \ > Only orders in a settled state can be collected.\ > \ > Example request body:\ > \`\`\`json\ > {\ > "base": "BTC",\ > "clientDualId": "my-order-001"\ > }\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "clientDualId": "my-order-001"\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"tags":[{"name":"Dual","description":"Dual Investment endpoints"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"DualCollectRequest":{"type":"object","required":["base","clientDualId","productId"],"properties":{"base":{"type":"string","description":"Base currency"},"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID to collect"},"productId":{"type":"string","description":"Product ID"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"DualCollectData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters. Common error code: `DUAL_PARAMETER_ERROR`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed — missing or invalid API Key / signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/earn/dual/collect":{"post":{"tags":["Dual"],"summary":"Collect settled earnings","description":"Collects settled Dual Investment earnings into the user's spot account. Requires `Earn` permission. Weight: 1.\n\nOnly orders in a settled state can be collected.\n\nExample request body:\n```json\n{\n \"base\": \"BTC\",\n \"clientDualId\": \"my-order-001\"\n}\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"clientDualId\": \"my-order-001\"\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"dualCollect","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DualCollectRequest"}}}},"responses":{"200":{"description":"Collect succeeded","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DualCollectData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Whether the request succeeded"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}}}}} ``` ## The ErrorResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code (e.g. `DUAL_PARAMETER_ERROR`)"},"message":{"type":"string","description":"Human-readable error message"},"timestamp":{"type":"integer","format":"int64"}}}}}} ``` ## The DualSymbolsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualSymbolsData":{"type":"object","properties":{"coins":{"type":"array","items":{"$ref":"#/components/schemas/DualCoinSymbol"}}}},"DualCoinSymbol":{"type":"object","properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency. Supported values: `USDT`, `USDC`, `USD`, `USDXO`"},"currency":{"type":"string","description":"Investment currency (the currency used to place the order)"},"basePrecision":{"type":"integer","format":"int64","description":"Decimal precision for base currency amounts"},"currencyPrecision":{"type":"integer","format":"int64","description":"Decimal precision for investment currency amounts"},"baseMin":{"type":"string","description":"Minimum investment amount in base currency"},"currencyMin":{"type":"string","description":"Minimum investment amount in investment currency"},"baseMax":{"type":"string","description":"Maximum investment amount in base currency"},"currencyMax":{"type":"string","description":"Maximum investment amount in investment currency"}}}}}} ``` ## The DualCoinSymbol object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualCoinSymbol":{"type":"object","properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency. Supported values: `USDT`, `USDC`, `USD`, `USDXO`"},"currency":{"type":"string","description":"Investment currency (the currency used to place the order)"},"basePrecision":{"type":"integer","format":"int64","description":"Decimal precision for base currency amounts"},"currencyPrecision":{"type":"integer","format":"int64","description":"Decimal precision for investment currency amounts"},"baseMin":{"type":"string","description":"Minimum investment amount in base currency"},"currencyMin":{"type":"string","description":"Minimum investment amount in investment currency"},"baseMax":{"type":"string","description":"Maximum investment amount in base currency"},"currencyMax":{"type":"string","description":"Maximum investment amount in investment currency"}}}}}} ``` ## The DualProductsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualProductsData":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/DualProduct"}}}},"DualProduct":{"type":"object","properties":{"productId":{"type":"string","description":"Unique product ID. Format: `{BASE}-{QUOTE}-{YYMMDD}-{STRIKE}-{C|P}-{CURRENCY}`. `C` = DUAL_BASE, `P` = DUAL_CURRENCY."},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"createTime":{"type":"integer","format":"int64","description":"Product creation timestamp in milliseconds"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"strike":{"type":"string","description":"Strike price — the threshold price at settlement"},"expired":{"type":"boolean","description":"Whether the product has already expired"}}}}}} ``` ## The DualProduct object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualProduct":{"type":"object","properties":{"productId":{"type":"string","description":"Unique product ID. Format: `{BASE}-{QUOTE}-{YYMMDD}-{STRIKE}-{C|P}-{CURRENCY}`. `C` = DUAL_BASE, `P` = DUAL_CURRENCY."},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"createTime":{"type":"integer","format":"int64","description":"Product creation timestamp in milliseconds"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"strike":{"type":"string","description":"Strike price — the threshold price at settlement"},"expired":{"type":"boolean","description":"Whether the product has already expired"}}}}}} ``` ## The DualPricesData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualPricesData":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/DualPrice"}}}},"DualPrice":{"type":"object","properties":{"productId":{"type":"string","description":"Product ID"},"canInvest":{"type":"boolean","description":"Whether the product is currently open for new investment"},"profit":{"type":"string","description":"Annualized yield rate (e.g. `0.0215` = 2.15%)"},"baseSize":{"type":"string","description":"Base currency amount per unit"},"updateTime":{"type":"integer","format":"int64","description":"Last price update timestamp in milliseconds"}}}}}} ``` ## The DualPrice object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualPrice":{"type":"object","properties":{"productId":{"type":"string","description":"Product ID"},"canInvest":{"type":"boolean","description":"Whether the product is currently open for new investment"},"profit":{"type":"string","description":"Annualized yield rate (e.g. `0.0215` = 2.15%)"},"baseSize":{"type":"string","description":"Base currency amount per unit"},"updateTime":{"type":"integer","format":"int64","description":"Last price update timestamp in milliseconds"}}}}}} ``` ## The DualIndexData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualIndexData":{"type":"object","properties":{"index":{"type":"string","description":"Current real-time index price"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}}}}} ``` ## The DeliveryPricesData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DeliveryPricesData":{"type":"object","properties":{"prices":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryPrice"}}}},"DeliveryPrice":{"type":"object","properties":{"delivery":{"type":"string","description":"Settlement delivery price (index price at expiry)"},"date":{"type":"string","description":"Delivery date in `YYYY-MM-DD` format"},"deliveryTime":{"type":"integer","format":"int64","description":"Delivery timestamp in milliseconds"}}}}}} ``` ## The DeliveryPrice object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DeliveryPrice":{"type":"object","properties":{"delivery":{"type":"string","description":"Settlement delivery price (index price at expiry)"},"date":{"type":"string","description":"Delivery date in `YYYY-MM-DD` format"},"deliveryTime":{"type":"integer","format":"int64","description":"Delivery timestamp in milliseconds"}}}}}} ``` ## The DualBalancesData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualBalancesData":{"type":"object","properties":{"balances":{"type":"array","items":{"$ref":"#/components/schemas/DualBalance"}}}},"DualBalance":{"type":"object","properties":{"base":{"type":"string","description":"Base currency this balance is associated with"},"coin":{"type":"string","description":"The actual currency of the balance"},"free":{"type":"string","description":"Available (unlocked) balance"},"frozen":{"type":"string","description":"Frozen balance currently locked in active orders"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}}}}} ``` ## The DualBalance object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualBalance":{"type":"object","properties":{"base":{"type":"string","description":"Base currency this balance is associated with"},"coin":{"type":"string","description":"The actual currency of the balance"},"free":{"type":"string","description":"Available (unlocked) balance"},"frozen":{"type":"string","description":"Frozen balance currently locked in active orders"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}}}}} ``` ## The DualInvestRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualInvestRequest":{"type":"object","required":["base"],"properties":{"base":{"type":"string","description":"Base currency"},"clientDualId":{"type":"string","description":"Client-assigned order ID used as an idempotency key. Recommended to avoid duplicate orders."},"productId":{"type":"string","description":"Product ID to invest in"},"baseAmount":{"type":"string","description":"Investment amount in base currency (e.g. BTC). Mutually exclusive with `currencyAmount`."},"currencyAmount":{"type":"string","description":"Investment amount in investment currency (e.g. USDT). Mutually exclusive with `baseAmount`."},"profit":{"type":"string","description":"Expected yield rate. Must match the current price from `/prices`."}}}}}} ``` ## The DualInvestData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualInvestData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state after creation (e.g. `CONFIRMED`)"}}}}}} ``` ## The DualRevokeInvestRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualRevokeInvestRequest":{"type":"object","required":["base","productId","clientDualId"],"properties":{"base":{"type":"string","description":"Base currency"},"productId":{"type":"string","description":"Product ID of the order to revoke"},"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}}}}} ``` ## The DualRevokeInvestData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualRevokeInvestData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}}}}} ``` ## The DualGetInvestsRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualGetInvestsRequest":{"type":"object","properties":{"base":{"type":"string","description":"Base currency"},"clientDualIds":{"type":"array","items":{"type":"string"},"description":"List of client-assigned dual investment order IDs to query"}}}}}} ``` ## The DualInvestRecordsData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualInvestRecordsData":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DualRecord"}}}},"DualRecord":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state"},"productId":{"type":"string","description":"Product ID"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"strike":{"type":"string","description":"Strike price"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"baseAmount":{"type":"string","description":"Investment amount in base currency"},"currencyAmount":{"type":"string","description":"Investment amount in investment currency"},"profit":{"type":"string","description":"Yield rate at time of investment (e.g. `0.0215` = 2.15%)"},"baseFilled":{"type":"string","description":"Matched/filled amount in base currency"},"currencyFilled":{"type":"string","description":"Matched/filled amount in investment currency"},"settlementState":{"type":"string","description":"Settlement state"},"settlementTime":{"type":"integer","format":"int64","description":"Settlement timestamp in milliseconds"},"settlementBase":{"type":"string","description":"Currency received as principal at settlement"},"settlementCurrency":{"type":"string","description":"Currency received as earnings at settlement"},"deliveryPrice":{"type":"string","description":"Index price recorded at settlement"},"createTime":{"type":"integer","format":"int64","description":"Order creation timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}}}}} ``` ## The DualRecord object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualRecord":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"},"state":{"type":"string","description":"Investment state"},"productId":{"type":"string","description":"Product ID"},"type":{"type":"string","description":"`DUAL_BASE` — invest in base currency; `DUAL_CURRENCY` — invest in quote/investment currency","enum":["DUAL_BASE","DUAL_CURRENCY"]},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"currency":{"type":"string","description":"Investment currency"},"strike":{"type":"string","description":"Strike price"},"expireTime":{"type":"integer","format":"int64","description":"Product expiry timestamp in milliseconds"},"baseAmount":{"type":"string","description":"Investment amount in base currency"},"currencyAmount":{"type":"string","description":"Investment amount in investment currency"},"profit":{"type":"string","description":"Yield rate at time of investment (e.g. `0.0215` = 2.15%)"},"baseFilled":{"type":"string","description":"Matched/filled amount in base currency"},"currencyFilled":{"type":"string","description":"Matched/filled amount in investment currency"},"settlementState":{"type":"string","description":"Settlement state"},"settlementTime":{"type":"integer","format":"int64","description":"Settlement timestamp in milliseconds"},"settlementBase":{"type":"string","description":"Currency received as principal at settlement"},"settlementCurrency":{"type":"string","description":"Currency received as earnings at settlement"},"deliveryPrice":{"type":"string","description":"Index price recorded at settlement"},"createTime":{"type":"integer","format":"int64","description":"Order creation timestamp in milliseconds"},"updateTime":{"type":"integer","format":"int64","description":"Last update timestamp in milliseconds"}}}}}} ``` ## The DualCollectRequest object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualCollectRequest":{"type":"object","required":["base","clientDualId","productId"],"properties":{"base":{"type":"string","description":"Base currency"},"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID to collect"},"productId":{"type":"string","description":"Product ID"}}}}}} ``` ## The DualCollectData object ```json {"openapi":"3.0.3","info":{"title":"Pionex Earn Open API - Dual Investment","version":"1.0.0"},"components":{"schemas":{"DualCollectData":{"type":"object","properties":{"clientDualId":{"type":"string","description":"Client-assigned dual investment order ID"}}}}}} ``` # InstFund API REST endpoints for institutional fund accounts.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/inst-fund-api/general-info
## APIs

:square-terminal:

Accounthttps://www.pionex.com/docs/api-docs/inst-fund-api/inst-fund-account

:square-terminal:

Commonhttps://www.pionex.com/docs/api-docs/inst-fund-api/inst-fund-common
# General Info # Basic Info > **Note:** The InstFund API is currently Internal and only available to onboarded institutional users. There is currently no application channel available. **Base URL:** `https://api.pionex.com` **Request Format:** * All endpoints require a Trade Token in the `Authorization` header. * GET requests: additional parameters are passed in the query string using camelCase naming. * POST requests: parameters are passed in the request body as JSON (`application/json`) using camelCase naming. **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information (JSON keys returned in camelCase) * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"totalAmount": "100", "fee": "0.5", "netAmount": "99.5"}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "BOT_INTERNAL_ERROR", "message": "internal error", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions Each API Key can be configured with **`Enable reading`** and/or **`Institutional deposit & withdrawal`** permissions. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Enable reading` permission:** * `GET /api/v1/instFund/straitsx/getAccount` — Query the InstFund virtual account * `GET /api/v1/instFund/straitsx/getWithdrawAccounts` — List bound withdraw accounts * `GET /api/v1/instFund/common/getDeposits` — Query fiat deposit history * `GET /api/v1/instFund/common/getWithdraws` — Query fiat withdrawal history * `GET /api/v1/instFund/common/getFee` — Query withdrawal fee **Endpoints requiring `Institutional deposit & withdrawal` permission:** * `POST /api/v1/instFund/straitsx/createWithdraw` — Create a fiat withdrawal request # Inst Fund Account InstFund virtual account, bound withdraw accounts, and fiat withdrawal endpoints (private) ## Query the InstFund virtual account > Returns the InstFund virtual account bound to the authenticated user. Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Account","description":"InstFund virtual account, bound withdraw accounts, and fiat withdrawal endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/straitsx/getAccount":{"get":{"tags":["InstFund - Account"],"summary":"Query the InstFund virtual account","description":"Returns the InstFund virtual account bound to the authenticated user. Weight: 1.\n","operationId":"instFundGetAccount","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Virtual account details"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ``` ## List bound withdraw accounts > Returns the list of withdraw accounts bound to the authenticated user. Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Account","description":"InstFund virtual account, bound withdraw accounts, and fiat withdrawal endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/straitsx/getWithdrawAccounts":{"get":{"tags":["InstFund - Account"],"summary":"List bound withdraw accounts","description":"Returns the list of withdraw accounts bound to the authenticated user. Weight: 1.\n","operationId":"instFundGetWithdrawAccounts","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Bound withdraw account list"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ``` ## Create a fiat withdrawal request > Creates a fiat withdrawal request against a bound withdraw account. Weight: 1.\ > \ > The request body should use camelCase keys.
```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Account","description":"InstFund virtual account, bound withdraw accounts, and fiat withdrawal endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/straitsx/createWithdraw":{"post":{"tags":["InstFund - Account"],"summary":"Create a fiat withdrawal request","description":"Creates a fiat withdrawal request against a bound withdraw account. Weight: 1.\n\nThe request body should use camelCase keys.\n","operationId":"instFundCreateWithdraw","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Withdrawal request payload (camelCase keys)","additionalProperties":true}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Withdrawal creation result"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ``` # Inst Fund Common Fiat deposit / withdrawal history and fee query endpoints (private) ## Query fiat deposit history > Returns fiat deposit history for the authenticated user. Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Common","description":"Fiat deposit / withdrawal history and fee query endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/common/getDeposits":{"get":{"tags":["InstFund - Common"],"summary":"Query fiat deposit history","description":"Returns fiat deposit history for the authenticated user. Weight: 1.\n","operationId":"instFundGetDeposits","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Deposit history"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ``` ## Query fiat withdrawal history > Returns fiat withdrawal history for the authenticated user. Weight: 1.
```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Common","description":"Fiat deposit / withdrawal history and fee query endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/common/getWithdraws":{"get":{"tags":["InstFund - Common"],"summary":"Query fiat withdrawal history","description":"Returns fiat withdrawal history for the authenticated user. Weight: 1.\n","operationId":"instFundGetWithdraws","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Withdrawal history"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ``` ## Query withdrawal fee > Query the withdrawal fee for a given amount and channel. Currently only the withdrawal direction is supported. Weight: 1.\ > \ > Example request:\ > \`\`\`\ > GET /api/v1/instFund/common/getFee?amount=100\&direction=withdraw\ > \`\`\`\ > \ > Example response:\ > \`\`\`json\ > {\ > "result": true,\ > "data": {\ > "totalAmount": "100",\ > "fee": "0.5",\ > "netAmount": "99.5"\ > },\ > "timestamp": 1774959429596\ > }\ > \`\`\`
````json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"tags":[{"name":"InstFund - Common","description":"Fiat deposit / withdrawal history and fee query endpoints (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"TradeToken","description":"Trade Token authentication. Provide the token in the `Authorization` header as `Bearer `. The Trade Token is issued by the Pionex Trade Token Service and is verified on every request.\n"}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}},"GetFeeData":{"type":"object","description":"Withdrawal fee query result","properties":{"totalAmount":{"type":"string","description":"Total amount requested"},"fee":{"type":"string","description":"Withdrawal fee"},"netAmount":{"type":"string","description":"Amount credited to the counterparty (for withdrawal: total amount minus fee)"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid Trade Token","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal error - service or business error. A human-readable `message` is returned when available.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/instFund/common/getFee":{"get":{"tags":["InstFund - Common"],"summary":"Query withdrawal fee","description":"Query the withdrawal fee for a given amount and channel. Currently only the withdrawal direction is supported. Weight: 1.\n\nExample request:\n```\nGET /api/v1/instFund/common/getFee?amount=100&direction=withdraw\n```\n\nExample response:\n```json\n{\n \"result\": true,\n \"data\": {\n \"totalAmount\": \"100\",\n \"fee\": \"0.5\",\n \"netAmount\": \"99.5\"\n },\n \"timestamp\": 1774959429596\n}\n```\n","operationId":"instFundGetFee","parameters":[{"name":"channel","in":"query","required":false,"description":"Optional channel identifier. Leave empty to use the default channel bound to your account.","schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"description":"Total amount to query the fee for (decimal string, in the quote currency U).","schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"description":"Fee direction. Only `withdraw` is currently supported; defaults to `withdraw`.","schema":{"type":"string","default":"withdraw","enum":["withdraw"]}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GetFeeData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}} ```` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}}}} ``` ## The GetFeeData object ```json {"openapi":"3.0.3","info":{"title":"Pionex InstFund Open API","version":"1.0.0"},"components":{"schemas":{"GetFeeData":{"type":"object","description":"Withdrawal fee query result","properties":{"totalAmount":{"type":"string","description":"Total amount requested"},"fee":{"type":"string","description":"Withdrawal fee"},"netAmount":{"type":"string","description":"Amount credited to the counterparty (for withdrawal: total amount minus fee)"}}}}}} ``` # Partner API REST endpoints for partners: UID verification and partner operations.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/partner-api/general-info

:square-terminal:

Start Here: UID VerificationStart Here: UID Verification
## APIs

:square-terminal:

Partnerhttps://www.pionex.com/docs/api-docs/partner-api/partner
# Start Here: UID Verification Partners can verify whether a Pionex UID belongs to a user who registered through their invitation link. Choose one of two integration options based on how you want users to complete verification. | Option | Best for | How it works | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | [Pionex-managed Community Bot](#option-1-pionex-managed-community-bot) | Partners who want a ready-to-use solution without building their own verification system. | Pionex handles the verification flow through Telegram or Discord. Verified users receive a Telegram group invitation or a Discord role. | | [Direct Partner API integration](#option-2-direct-partner-api-integration) | Partners who already have a website, application, membership system, or other user flow. | Your system submits the UID to the Partner API and handles the verification result in your own product. No Telegram or Discord bot is required. | Both options use the same partner invitation relationship and qualification rules. If you already know which API endpoint you need, go directly to the [Partner API Reference](https://www.pionex.com/docs/api-docs/partner-api/general-info) for request parameters and response schemas. ## Verification Rules A verification succeeds only when all configured conditions are met: 1. The UID contains exactly eight digits. 2. The user registered through the partner's invitation link. 3. If **Min Balance** is configured, the user's total account assets in USDT meet or exceed that value. 4. The UID has not already been verified by the same configuration. A UID may still be verified with a different configuration. ## Option 1: Pionex-Managed Community Bot Choose this option when you do not want to build or maintain your own UID verification interface. Pionex provides the user flow through Telegram or Discord. ### Request Community Bot access Community Bot is available to approved partners only. Contact Pionex customer support or your BD representative to request access. After access is enabled, **Community Bot** appears in the Partner Web navigation. ### Manage Bots Partners can create and manage up to 10 bots in **Partner Web > Community Bot**.
Community Bot management page

Manage Partner Bots in Partner Web.

| Action | Description | | ---------------- | ----------------------------------------------------------------------------------------------------- | | Enable / Disable | Start or pause the bot. | | Edit | Update the configuration. Platform and bot token cannot be changed. The bot restarts after an update. | | Records | View verification records for the bot. | | Delete | Delete the bot. | Bot statuses: | Status | Description | | -------- | ------------------------------------------------------------------- | | Running | The bot is operating normally. | | Disabled | The bot was manually paused. | | Error | The bot stopped unexpectedly, usually because its token is invalid. | ### Create a Telegram or Discord Bot Go to **Bot Management > Create Bot**.
Create Partner Bot form

Create a Telegram or Discord Partner Bot.

| Field | Required | Description | | ------------------ | ------------- | ---------------------------------------------------------------------------------------------- | | Bot Name | Yes | Display name used to identify the bot in Partner Web. | | Platform | Yes | Select `Telegram` or `Discord`. | | Bot Token | Yes | Token for the Telegram or Discord bot. | | Group Chat ID | Telegram only | Telegram group ID used to generate an invitation link after successful verification. | | Verified Role Name | Discord only | Discord role granted after successful verification. | | Signup URL | No | Pionex registration link containing your invitation code. It is shown when verification fails. | | Language | No | Default language: `en`, `zh`, `es`, or `de`. | | Min Balance | No | Minimum total account balance in USDT. Set it to `0` to skip the balance check. | #### Telegram requirements * Add the bot as an administrator of the target group. * Grant the bot permission to invite users. #### Discord requirements * Enable **MESSAGE CONTENT INTENT** and **SERVER MEMBERS INTENT**. * Grant the bot **Manage Roles** permission. * Place the bot's role above the role it will grant. * After creating the bot, run `/verify_channel #channel-name` in Discord to publish the verification button. ### Telegram User Flow 1. The user opens a private chat with the bot and sends `/start`. 2. The user selects **ALREADY PIONEX USER** and submits a UID. 3. The bot verifies the UID. 4. After successful verification, the user receives a group invitation link that is valid for one hour and can be used once. If verification fails, the bot displays the reason and the configured signup link. Users can send `/language` to change the bot language.
Telegram Partner Bot verification flow

A successful Telegram verification returns a one-time group invitation link.

### Discord User Flow 1. The user clicks the **Pionex** button in the configured verification channel. 2. The user enters a UID and confirms it within five minutes. 3. The bot verifies the UID and automatically grants the configured role. Verification messages are visible only to the user. Failed verification displays an error without granting the role.
Discord Partner Bot verification flow

A successful Discord verification grants the configured role.

Discord administrator commands: | Command | Description | | --------------------------- | --------------------------------------------- | | `/verify_channel #channel` | Publish the verification button in a channel. | | `/set_grant_role role-name` | Change the role granted after verification. | | `/admin_stats` | View verification statistics. | | `/admin_config` | View the bot configuration. | | `/help` | View available commands. | | `/status` | View verification status. | ## Option 2: Direct Partner API Integration Choose this option when you already have a website, application, membership system, or other user flow. Your backend calls the Partner API directly and decides what to do with the verification result. You do not need to create or operate a Telegram or Discord bot. Users remain in your own product throughout the verification flow. The direct integration flow is: `Your product > Submit UID to Partner API > Receive qualification result > Continue your own user flow` ### Request Partner API access Direct API integrations require a Pionex API key with the **Partner reading** permission. Follow [Create an API Key](/docs/api-docs/references/api-key-guide), enable **Partner reading** and **Enable reading**, and wait for approval. If **Partner reading** is not available, contact Pionex customer support or your BD representative.
Create an API key with Partner reading permission

Enable Partner reading when creating the API key.

### Create the Open API configuration Before calling the qualification endpoint, create an Open API configuration in Partner Web: 1. Go to **Bot Management > Create Bot**. 2. Set **Platform** to `Open API`. 3. Enter a **Bot Name**. 4. Optionally configure **Min Balance**. Set it to `0` to skip the balance check. 5. Create the bot and copy its `bot_id`. Partner Web calls this configuration an **Open API Bot**, but it is not a chat bot. It does not require a bot token, does not start a Telegram or Discord process, and does not provide a user interface. It stores the verification settings and provides the `bot_id` required by the Partner API.
Find the Partner Bot ID in Partner Web

Copy the bot ID from Partner Web for API requests.

### Call the Partner API From your backend, call `GET /api/v1/partner/kol/checkQualification` with the user's UID and the `bot_id` created above. The endpoint checks the invitation relationship and the qualification conditions stored in the Open API configuration. See [Partner API Reference](https://www.pionex.com/docs/api-docs/partner-api/general-info) for authentication, parameters, and response fields. Use `GET /api/v1/partner/kol/inviteTradeStat` when you also need the invited user's trading volume statistics. ## Troubleshooting | Applies to | Problem | Resolution | | ------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Community Bot | Bot status is `Error` | The token is usually invalid. Delete the bot and create it again with a new token. | | Community Bot | Discord role is not granted | Check **Manage Roles** permission and ensure the bot's role is above the role being granted. | | Community Bot | Telegram verification succeeds but no invitation arrives | Confirm the Group Chat ID and make sure the bot is a group administrator with permission to invite users. | | Both options | UID verification fails | Confirm that the UID has eight digits, the user registered through the partner link, and the balance requirement is met. | | Community Bot | Bot token must be changed | Tokens cannot be edited. Delete the bot and create it again. | | Both options | A user needs to verify again | A UID can be verified only once per configuration, but it can be verified with a different configuration. | # General Info # Basic Info > **Note:** The Partner API is currently Internal. There is currently no application channel available. **Base URL:** `https://api.pionex.com` **Request Format:** * For private requests, the `timestamp` parameter (in milliseconds) must be included in the query string. The timestamp is valid within a range of +/-20 seconds. * Private requests require `PIONEX-KEY` (API Key) and `PIONEX-SIGNATURE` headers. * GET requests: additional parameters are passed in the query string. * POST/DELETE requests: parameters are passed in the request body as JSON (`application/json`). * Zero-valued number parameters are disregarded. **Signature Construction:** * GET: `METHOD + PATH_URL + QUERY + TIMESTAMP` * POST/DELETE: `METHOD + PATH_URL + QUERY + TIMESTAMP + body` **Response Format:** All responses are JSON objects containing: * `result` (boolean): success indicator * `timestamp` (number): response timestamp in milliseconds * On success: `data` object with business information * On failure: `code` (string) and `message` (string) with error details Success example: ```json {"result": true, "data": {"total": 100, "list": [...]}, "timestamp": 1566691672311} ``` Failure example: ```json {"result": false, "code": "PARAMETER_ERROR", "message": "Invalid parameter", "timestamp": 1566691672311} ``` # Rate Limits * Each endpoint has a weight value that determines how many requests it counts toward the limit. * IP-based and account-based limits operate independently. * All endpoints share the 10 per second limit based on IP. * Private endpoints share the 10 per second limit based on ACCOUNT. * Exceeding the weight limit results in HTTP 429 status code. # Authentication [API Key Guide](https://www.pionex.com/docs/api-docs/references/api-key-guide) Private endpoints require HMAC SHA256 signature authentication. **Required headers:** * `PIONEX-KEY`: Your API Key * `PIONEX-SIGNATURE`: HMAC SHA256 hex signature **Required query parameter:** * `timestamp`: Current time in milliseconds (valid within +/-20 seconds) #### API Key Permissions Each API Key can be configured with **`Partner reading`** permission. Make sure your API Key has the appropriate permission enabled before calling the following endpoints. **Endpoints requiring `Partner reading` permission:** * `GET /api/v1/partner/kol/checkQualification` — Check user qualification * `GET /api/v1/partner/kol/inviteTradeStat` — Get user trading volume # Partner Partner program management (private) ## Check user qualification > Check whether a user is affiliated with the partner and verify their qualification status. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"tags":[{"name":"Partner","description":"Partner program management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key for authentication. Signature must be provided in PIONEX-SIGNATURE header."}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Request timestamp in milliseconds. Any timestamp older than 20,000 milliseconds or in the future is invalid.","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}},"CheckQualificationResponse":{"type":"object","description":"User qualification check response","properties":{"result":{"type":"boolean","description":"Whether the user is affiliated with the requesting partner"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid API key or signature","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/partner/kol/checkQualification":{"get":{"tags":["Partner"],"summary":"Check user qualification","description":"Check whether a user is affiliated with the partner and verify their qualification status. Weight: 1.","operationId":"checkUserQualification","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"uid","in":"query","required":true,"description":"The user UID to verify affiliation and qualification status","schema":{"type":"string"}},{"name":"bot_id","in":"query","required":true,"description":"The bot/partner identifier making the request","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CheckQualificationResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get user trading volume > Query user trading volume statistics for a date range. Weight: 1. ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"tags":[{"name":"Partner","description":"Partner program management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key for authentication. Signature must be provided in PIONEX-SIGNATURE header."}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Request timestamp in milliseconds. Any timestamp older than 20,000 milliseconds or in the future is invalid.","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}},"UserTradingVolumeResponse":{"type":"object","description":"User trading volume statistics response","properties":{"total":{"type":"integer","description":"The number of records returned"},"list":{"type":"array","items":{"$ref":"#/components/schemas/UserTradingStatItem"},"description":"User trading volume list"}}},"UserTradingStatItem":{"type":"object","description":"User trading volume statistic","properties":{"uid":{"type":"string","description":"User's UID"},"account":{"type":"string","description":"User's account"},"perpTradeAmount":{"type":"string","description":"Volume for perpetual trading"},"spotTradeAmount":{"type":"string","description":"Volume for spot trading"}}}},"responses":{"BadRequest":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid API key or signature","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v1/partner/kol/inviteTradeStat":{"get":{"tags":["Partner"],"summary":"Get user trading volume","description":"Query user trading volume statistics for a date range. Weight: 1.","operationId":"getUserTradingVolume","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"startTime","in":"query","required":true,"description":"Query begin time in format YYYY-MM-dd","schema":{"type":"string","format":"date"}},{"name":"endTime","in":"query","required":true,"description":"Query end time in format YYYY-MM-dd","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserTradingVolumeResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` # Models ## The BaseResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"},"code":{"type":"string","description":"Error code (present only on failure)"},"message":{"type":"string","description":"Error message (present only on failure)"}}}}}} ``` ## The CheckQualificationResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"components":{"schemas":{"CheckQualificationResponse":{"type":"object","description":"User qualification check response","properties":{"result":{"type":"boolean","description":"Whether the user is affiliated with the requesting partner"}}}}}} ``` ## The UserTradingStatItem object ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"components":{"schemas":{"UserTradingStatItem":{"type":"object","description":"User trading volume statistic","properties":{"uid":{"type":"string","description":"User's UID"},"account":{"type":"string","description":"User's account"},"perpTradeAmount":{"type":"string","description":"Volume for perpetual trading"},"spotTradeAmount":{"type":"string","description":"Volume for spot trading"}}}}}} ``` ## The UserTradingVolumeResponse object ```json {"openapi":"3.0.3","info":{"title":"Pionex Partner Open API","version":"1.0.0"},"components":{"schemas":{"UserTradingVolumeResponse":{"type":"object","description":"User trading volume statistics response","properties":{"total":{"type":"integer","description":"The number of records returned"},"list":{"type":"array","items":{"$ref":"#/components/schemas/UserTradingStatItem"},"description":"User trading volume list"}}},"UserTradingStatItem":{"type":"object","description":"User trading volume statistic","properties":{"uid":{"type":"string","description":"User's UID"},"account":{"type":"string","description":"User's account"},"perpTradeAmount":{"type":"string","description":"Volume for perpetual trading"},"spotTradeAmount":{"type":"string","description":"Volume for spot trading"}}}}}} ``` # Institution API RESTful API (`/api/v2/institution/*`) for institutional service providers to onboard and operate their bound sub-accounts: fiat deposit/withdrawal, stablecoin conversion, on-chain assets, and trading-account balances. Uses public-key (RSA / Ed25519) signature authentication.

:square-terminal:

General Infohttps://www.pionex.com/docs/api-docs/institution-api/general-info

:square-terminal:

Start Here: Onboarding & Signing GuideStart Here: Onboarding & Signing Guide
## APIs

:square-terminal:

Userhttps://www.pionex.com/docs/api-docs/institution-api/user

:square-terminal:

KYBhttps://www.pionex.com/docs/api-docs/institution-api/kyb

:square-terminal:

Deposithttps://www.pionex.com/docs/api-docs/institution-api/deposit

:square-terminal:

Payout Accounthttps://www.pionex.com/docs/api-docs/institution-api/payout-account

:square-terminal:

Payouthttps://www.pionex.com/docs/api-docs/institution-api/payout

:square-terminal:

Assethttps://www.pionex.com/docs/api-docs/institution-api/asset

:square-terminal:

Address Bookhttps://www.pionex.com/docs/api-docs/institution-api/address-book

:square-terminal:

Accounthttps://www.pionex.com/docs/api-docs/institution-api/account

:square-terminal:

Converthttps://www.pionex.com/docs/api-docs/institution-api/convert

:square-terminal:

Filehttps://www.pionex.com/docs/api-docs/institution-api/file
# Start Here: Onboarding & Signing Guide > This document is the **English** onboarding-flow and encryption/signing-algorithm guide for the **Pionex Institution Open API (v2)**. It helps institutional integrators understand the end-to-end main line — from registering a public key, creating sub-accounts, and completing KYB, through initiating deposits/payouts/conversions — and implement request signing accordingly. **This is not the complete API endpoint reference** — for the full set of endpoints, fields, and request/response structures, see `openapi_institution_v2.yaml` in the same directory. > > For the Chinese version, see `openapi_institution_v2_onboarding.md`. An institution uses **its own API Key (a pair of RSA or Ed25519 keys)** to onboard and operate the sub-accounts (`userId`) held under its name: fiat deposits/payouts, stablecoin conversion, on-chain assets, and trading-account balances. v2 uses **public-key signature authentication** (RSA or Ed25519) and identifies the target sub-account by its **`userId` (UUID)**. | General Information | Value | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Base URL | `https://api.pionex.com` | | Protocol | HTTPS | | Data format | JSON | | Field naming | camelCase (e.g. `userId`, `clientOrderId`) | | Amounts | decimal strings (e.g. `"100.50"`) — never floats, never smallest-unit integers | | Timestamps | In response bodies these are **millisecond** Unix timestamps (`int64`); the `timestamp` query parameter used for signing is in **seconds** (see below) | | Currency codes | ISO 4217 uppercase (`"USD"`); country codes ISO 3166-1 alpha-2 uppercase (`"US"`) | *** ## Part 1: Onboarding Flow ### 1. End-to-End Main Line Onboarding has two stages: * **Phases 1–4 are the onboarding main line (executed in order, none can be skipped):** authentication → create sub-account → platform KYB → channel onboarding. * Once a sub-account is usable, **deposit / fiat payout / on-chain deposit / on-chain withdrawal / conversion / balance query are independent capabilities that can be called in any order.** ![Pionex Institution Open API v2 — onboarding flow](https://4194290415-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFR2ceef8Tg60c2lMiqG0%2Fuploads%2Fgit-blob-63e6e6021b3ea5377c3c24547c910b04e738b3c4%2Fopenapi_institution_v2_onboarding.svg?alt=media) > **Key gate:** All `wire/*` endpoints (channel deposit onboarding, deposit accounts/orders, payout accounts, payouts) require the target `userId`'s **platform KYB to first reach `APPROVED`**; otherwise they return `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED`. ### 2. Step-by-Step Flow #### Phase 1 — Authentication Register your **public key** with Webot, obtain an API Key (of the form `webot_xxxxxxxx`), and implement request signing. You keep the private key yourself. See [Part 2](#part-2-encryption--signing-algorithm-authentication--signing) for details. #### Phase 2 — Create Sub-Account ``` POST /api/v2/institution/user/create ``` Create a sub-account held under your institution's name, idempotent by `clientId`. Request body: `clientId` (required, idempotency key, ≤64), `email` (required, ≤64), `entityType` (required, `CORPORATE`/`INDIVIDUAL`), `remark` (optional). The response returns `data.userId`. All subsequent operations targeting this sub-account use this `userId`. > If `P_PAY_OPEN_API_SUB_USER_ACCOUNT_CREATE_FAILED` is returned, the sub-account has been created but not fully initialized; `data.userId` returns the already-created id — resend an **exactly identical** request to complete initialization. Use `GET /api/v2/institution/users` to list all sub-accounts and obtain their `userId`. #### Phase 3 — Platform KYB ``` POST /api/v2/institution/kyb/create # submit GET /api/v2/institution/kyb # query status ``` Submit the company/representative information once. It **must reach `APPROVED`** before any channel deposit onboarding can proceed. A `userId` has only one platform KYB application; resubmitting while under review updates it, and once it is `APPROVED` it can no longer be submitted (returns `P_PAY_OPEN_API_KYB_ALREADY_APPROVED`). Submission body structure: ```json { "userId": "88001234-....", "subject": { "fields": [ { "key": "subject.legalNameEn", "value": "Acme Ltd." } ] }, "representatives": [ { "representativeRef": "PERSON-01", "fields": [ { "key": "representative.firstName", "value": "..." } ] } ], "documents": [ { "purpose": "subject.sourceOfFundsProof", "fileId": "...", "scope": "SUBJECT" }, { "purpose": "representative.passport", "fileId": "...", "scope": "REPRESENTATIVE", "representativeRef": "PERSON-01" } ] } ``` On submission, passing validation (key validity + unconditional required fields + enums) returns `SUBMITTED`; otherwise it returns `P_PAY_OPEN_API_INVALID_ARGUMENT` and nothing is persisted. #### Phase 4 — Channel Onboarding (Channel KYB) ``` GET /api/v2/institution/wire/deposit/account/requirements # query requirements first POST /api/v2/institution/wire/deposit/account/create # then submit per requirements GET /api/v2/institution/wire/deposit/account # query onboarding status ``` After platform KYB is approved, onboard a deposit account for a given channel. **`channel` currently supports `FV Bank` and `SCB/DBS Bank`.** Channel fields are **dynamic** — **call `requirements` first**, then fill in the returned `Requirement` items; do not hardcode a field list. After submission, only the onboarding `status` is returned, not an itemized list of what is missing — call `requirements` again to learn what is still missing. **Documents must be submitted in full every time.** #### Independent Capabilities After the Sub-Account Is Usable | Capability | Key endpoints | Notes | | ------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Deposit | `GET .../wire/deposit/accounts`, `.../orders`, `.../order` | Query deposit accounts (to obtain the remittance `instructions[]`) and deposit orders | | Fiat Payout | `.../wire/payout/account/*` → `.../wire/payout/order/create` | Create the payee account first, **wait until its status reaches `AVAILABLE`**, then submit the payout | | On-chain Deposit | `GET .../asset/address` | Get the sub-account's deposit address for a given `currency` + `chain` (isolated per sub-account) | | On-chain Withdrawal | `POST .../asset/withdraw`, `POST .../addressBook` | **Whitelist the address / add it to the address book first**, then withdraw | | Convert | `POST .../convert/order/create` | Stablecoin / currency conversion | | Balances | `GET .../account/balances` | Trading-account balances | ### 3. Two-Step KYB: Field-Source Differences Between Platform KYB and Channel KYB Onboarding is essentially **two-step KYB**, and the two draw their fields from different sources — this is the most commonly confused point: | Dimension | Platform KYB (`POST /kyb/create`) | Channel KYB (`wire/deposit/account/*`) | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Field source | **Fixed, documented field list** — fill in per this document's [Platform KYB Field Reference](#appendix-platform-kyb-field-reference), not obtained through an endpoint | **Dynamic** — call `GET .../wire/deposit/account/requirements` first, then fill in the returned `Requirement` items | | Precondition | None (it is step 3 of the main line) | Platform KYB must be `APPROVED` first | | `channel` | Not involved | Currently `FV Bank` / `SCB/DBS Bank` | | How to decide whether to submit an item | By the field's M/C/O marker (Mandatory/Conditional/Optional) | By `Requirement.mode`: `REQUIRED`/`OPTIONAL`/`CONDITIONAL` (when `CONDITIONAL` is uncertain, submitting is recommended; the channel makes the final decision) | | country / businessType | Provided explicitly in `subject.*` | **Do not send** `country`/`businessType`; they inherit the platform KYB's `subject.country`/`subject.businessType` | | Documents | `documents[]`; upload first to obtain a `fileId`, then reference it | Likewise upload first to obtain a `fileId`; items with `kind=DOCUMENT` are referenced via `fileId`, and **documents must be submitted in full every time** | Channel `Requirement` structure: `{ key, kind (FIELD|DOCUMENT), mode (REQUIRED|OPTIONAL|CONDITIONAL), label, regex, example, enumValues[] }`. `regex`/`example`/`enumValues` are used only for client-side validation and hints. `requirements` returns only the items the channel is **still missing** (already-provided items are omitted); representatives fill in their own `fields`/`documents`, grouped by `representativeRef`. ### 4. State-Machine Quick Reference Understanding each state helps you judge how the flow is progressing: | State machine | Values | Notes | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | **Platform KYB status** | `SUBMITTED` / `APPROVED` / `REJECTED` | Only `APPROVED` unlocks `wire/*` | | **Channel onboarding status** | `NOT_CREATED` / `SUBMITTED` / `IN_REVIEW` / `ACTION_REQUIRED` / `APPROVED` / `REJECTED` | `NOT_CREATED` means not yet onboarded (not an error) | | **Deposit account status** (DepositAccount.status) | `PENDING` (not yet remittable) / `ACTIVE` (remittable) / `UNAVAILABLE` / `CLOSED` | | | **Deposit order status** (DepositOrderStatus) | `PENDING` / `CREDITED` (credited but not settled) / `COMPLETED` (terminal) / `FAILED` (terminal) / `CANCELED` (terminal) | | | **Payout account status** (PayoutAccount.status) | `IN_REVIEW` / `AVAILABLE` / `NEEDS_UPDATE` / `UNAVAILABLE` / `DELETED` | Must reach `AVAILABLE` before a payout can be initiated | | **Payout order status** (PayoutOrderStatus) | `PENDING` / `IN_REVIEW` / `PROCESSING` / `COMPLETED` (terminal) / `FAILED` (terminal) / `RETURNED` / `REFUNDING` / `REFUNDED` | | > Business failures are returned as HTTP `200` + `result: false`. Only the authentication layer is an exception: `401` (authentication failure), `400` (request body unreadable). Terminal orders in a non-success state carry a `reason` object `{ code, message, retryable }`. *** ## Part 2: Encryption / Signing Algorithm (Authentication & Signing) Except for a few explicitly marked endpoints, every request is authenticated with your institution's API Key and a **signature**. When you apply for the API Key, you register your **public key** with Webot and keep the private key yourself. ### 1. The Two Request Headers | Header | Description | | ------------- | ----------------------------------------------------------------------------------------- | | `X-APIKEY` | Your API Key, of the form `webot_xxxxxxxx`, used to look up your registered public key. | | `X-Signature` | The result of signing the canonical string below, **Base64-encoded (standard encoding)**. | ### 2. The Two Key Types and Their Signing Methods The signing algorithm is determined by **the type of the public key you registered** — it is **not** chosen per request. Two key types are supported: | Key type | How to sign | Notes | | ----------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- | | **RSA** | **RSA-PSS** over the **SHA-256** digest | 2048–4096 bit keys. Recommended salt length is 32 (20 / 32 / 64 are all acceptable). **Not** PKCS#1 v1.5. | | **Ed25519** | Sign the message bytes **directly** | **Do not** pre-hash — EdDSA already includes SHA-512 internally. | * Public keys are registered in **PKIX/SPKI** form (`-----BEGIN PUBLIC KEY-----`). PKCS#1 "RSA PUBLIC KEY" and other algorithms (ECDSA, DSA, …) are not accepted. * RSA reference implementation: * Go: `rsa.SignPSS(rand, priv, crypto.SHA256, sha256(msg), nil)` * OpenSSL: `-sigopt rsa_padding_mode:pss` ### 3. The Required Query Parameter `timestamp` | Parameter | Type | Description | | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp` | integer | The current time, in **seconds** (Unix). Required on every signed request, and it **participates in the signature**. Must be within **±5 seconds** of server time, otherwise the request is rejected. | > `timestamp` goes in the **query string**, **even for `POST`** (a POST's business data goes in the JSON body). There is **no** `client_id` / nonce parameter. ### 4. Building the Canonical String Sign the following string: ``` {sub_path}:{sorted_query_string}:{request_body}:{timestamp} ``` | Segment | How it is built | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `sub_path` | The request path, **verbatim** (not URL-encoded), e.g. `/api/v2/institution/account/balances`. | | `sorted_query_string` | Percent-encode each key and value **separately** with `encodeURIComponent` semantics — **do not** escape `A-Za-z0-9 - _ . ! ~ * ' ( )`, use **uppercase** hexadecimal, and encode spaces as `%20` (not the form-encoding `+`). Join each into `key=value`, then **sort those `key=value` strings as a whole**, and join them with `&`. **All query parameters participate** — `timestamp` plus the business parameters (e.g. `userId`); duplicate keys are kept and sorted by value. | | `request_body` | For `POST` with a JSON body: **the raw body verbatim** (do not re-serialize). For `GET`: the empty string (so `::` appears in the canonical string). | | `timestamp` | The same second value, **appended again** at the end. | **Official examples:** ``` GET (no body): /api/v2/institution/account/balances:timestamp=1785706000&userId=88001234::1785706000 POST (JSON body): /api/v2/institution/kyb/create:timestamp=1785706000:{"userId":"88001234"}:1785706000 ``` Then `X-Signature = base64( sign( canonical_string ) )`, sent together with `X-APIKEY`. > The most common integration error is getting a parameter's source wrong (query vs. body) — be sure to check against the table above. ### 5. Permission Scopes Each API Key is granted one or more **scopes** at registration (default `read`). Every endpoint requires a specific scope; a request lacking the permission is rejected with `P_PAY_OPEN_API_PERMISSION_DENIED` and **does not enter the business logic**. * **Read endpoints** (`GET` queries — balances, orders, records, requirements, status, lists) require **read**. * **State-changing endpoints** (`POST` create/submit/update/delete — sub-account and KYB onboarding, payouts, on-chain withdrawals, conversions, address book and file writes) require the corresponding **write** scope. Contact Webot to grant your key the scopes it needs; the scopes on a key **cannot be changed by the caller.** ### 6. `userId` Parameter Rules Except for public/self endpoints (**create user**, **list users**, **`asset/currencies`**), **every endpoint requires `userId`** (the target sub-account's UUID): | Request form | Where `userId` goes | | ----------------------------------- | --------------------------------------------------------------- | | GET request | **Query string** (participates in the signature) | | POST request (JSON body) | In the **JSON body** | | File upload (`multipart/form-data`) | **Query string** (the body is multipart, so it cannot go there) | Obtain `userId` from the response of \[List Sub-Accounts] or \[Create Sub-Account]. ### 7. Base Error Codes | Error code | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | `P_PAY_OPEN_API_INVALID_ARGUMENT` | Request parameter missing or invalid. | | `P_PAY_OPEN_API_UNAUTHENTICATED` | Authentication failed (missing key, bad signature, etc.). Returns HTTP `401`. | | `P_PAY_OPEN_API_PERMISSION_DENIED` | The API Key lacks permission for this endpoint. | | `P_PAY_OPEN_API_NOT_FOUND` | Resource does not exist, or does not belong to this user. | | `P_PAY_OPEN_API_ALREADY_EXISTS` | Resource already exists (e.g. the address is already in the address book). | | `P_PAY_OPEN_API_SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable; retry later. | | `P_PAY_OPEN_API_TIMEOUT` | Request timed out; retry later. | | `P_PAY_OPEN_API_INTERNAL_ERROR` | Internal error. | | `P_PAY_OPEN_API_OPERATION_NOT_SUPPORTED` | The channel does not support this operation. Do not retry. | | `P_PAY_OPEN_API_CHANNEL_NOT_SUPPORTED_IN_REGION` | The requested `channel` is not available for your onboarding. Do not retry with the same channel. | | `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED` | Platform KYB is not yet `APPROVED` — the `wire/*` gate. | *** ## Appendix: Platform KYB Field Reference > The platform KYB field list is **fixed and documented**, and applies to companies registered in **Hong Kong (HK)** or **other jurisdictions**. The following are the canonical fields and documents accepted by `POST /kyb/create`. The full field schema is also in `openapi_institution_v2.yaml`. **Requirement markers:** **M** = Mandatory (missing it fails validation with `P_PAY_OPEN_API_INVALID_ARGUMENT`); **C** = Conditional (required when the trigger condition in the description is met); **O** = Optional (providing it speeds up review; missing it does not block). The `HK`/`Other` columns give the marker for each jurisdiction (`subject.country`), and `N/A` means the jurisdiction ignores the field. Files are submitted via `documents[]`, using the document's canonical key as `purpose` and the `fileId` as the value. ### Subject Fields (`subject.*`) | Key | HK | Other | Rule | | ---------------------------------------------------------- | :-: | :---: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject.country` | M | M | Registration jurisdiction, ISO alpha-2 country code, e.g. `HK`. | | `subject.legalNameEn` | M | M | Legal English name, ≤200, must match the registration document exactly (including `Limited`/`Ltd.`/`Inc.` suffixes). Non-Latin names require an official English translation. | | `subject.legalNameCn` | O | N/A | Legal Chinese name, ≤100. HK companies registered in Chinese should provide it; not applicable to Other. | | `subject.registrationNo` | M | M | HK: Business Registration number; Other: IRS EIN (format `XX-XXXXXXX`). ≤32. | | `subject.registrationNoType` | M | M | `BRN` (HK) / `EIN` (Other), must match `subject.country`. | | `subject.businessType` | M | M | Organizational form (see enum). Also determines which formation document Other requires. | | `subject.incorporationDate` | M | M | `yyyy-MM-dd`. Incorporation < 6 months may enter enhanced due diligence. | | `subject.incorporationState` | N/A | M | Other state code (e.g. `DE`, `CA`), Other only. | | `subject.email` | M | M | Official business email, ≤128. Free email domains (gmail/qq/163…) trigger manual review. | | `subject.phone.countryCode` | C | C | International calling code without `+` (e.g. `852`, `1`). Required when a phone is provided. | | `subject.phone.number` | C | C | Required when a phone is provided, ≤20. | | `subject.website` | O | O | Must include the scheme (`https://`), ≤256. Recommended for e-commerce/platform businesses. | | `subject.registeredAddress.addressLine2` | O | O | Room/floor/unit, ≤200. | | `subject.registeredAddress.city` | M | M | ≤100. | | `subject.registeredAddress.state` | O | M | 2-letter state code (e.g. `NY`). Required for Other; may be omitted for HK. | | `subject.registeredAddress.postalCode` | O | M | Required for Other; HK has no postal code. | | `subject.registeredAddress.countryCode` | M | M | ISO 3166-1 alpha-2. | | `subject.operatingAddressSameAsRegistered` | M | M | `true`/`false`. When `true`, omit `operatingAddress`. | | `subject.operatingAddress.*` | C | C | Sub-fields same as `registeredAddress`. Required when the above is `false`. | | `subject.businessDescription` | M | M | A concrete description of the products/services, ≤500. Vague terms ("trading", "consulting") will be asked to elaborate. | | `subject.accountPurpose.cryptoTrading` etc. | O | O | Each `accountPurpose.*` is `true`/`false`: `cryptoTrading`/`fiatDeposit`/`fiatWithdrawal`/`cardIssuing`/`crossBorderPayment`/`fxConversion`/`payroll`/`other`. At least one should be `true`; explain `other` in `businessDescription`. | | `subject.monthlyDepositLimit.amount` | M | M | Decimal string, ≤2 decimal places, USD recommended. | | `subject.monthlyDepositLimit.currency` | M | M | ISO 4217. | | `subject.monthlyWithdrawalLimit.amount` | M | M | Decimal string, ≤2 decimal places. | | `subject.monthlyWithdrawalLimit.currency` | M | M | ISO 4217. | | `subject.pepDeclaration.hasPepRelation` | M | M | `true`/`false`. Whether a director/shareholder/UBO (or a close relative) is a politically exposed person. | | `subject.pepDeclaration.description` | C | C | Required when `hasPepRelation = true`, ≤500 (name, position, tenure). | | `subject.ownershipDeclaration.hasShareholderOver25Percent` | C | C | `true`/`false`. Required when no ownership-structure proof document is submitted. When `true`, `representatives[]` must include at least one `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`. | | `subject.ownershipDeclaration.hasNomineeShareholder` | O | O | `true`/`false`. When `true`, the ultimate beneficiary must be disclosed. | | `subject.highRiskCountryExposure.involved` | O | O | `true`/`false`. Whether the business involves FATF high-risk jurisdictions. | | `subject.highRiskCountryExposure.description` | C | C | Required when `involved = true`, ≤500. | | `subject.termsAgreed` | M | M | Must be `true`, otherwise the application is rejected. | | `subject.dataUsageAgreed` | M | M | Must be `true` (authorizes third-party data verification). | | `subject.serviceAgreementType` | M | M | `FULL`/`RECIPIENT` (see enum). | | `subject.signerPersonRefId` | M | M | Must equal the `representativeRef` of the person designated as the authorized signer. | | `subject.agreedAt` | M | M | ISO 8601 (e.g. `2026-08-25T10:12:33Z`). | | `subject.deviceData.ipAddress` | M | M | The signer's public IP at the time of consent (IPv6-compatible), ≤45. | | `subject.deviceData.userAgent` | M | M | The signer's User-Agent, ≤512. | ### Subject Documents (`subject.*`, value is a `fileId`) | Key | HK | Other | Description | | ---------------------------------------------------------------------------------------------- | :-: | :---: | --------------------------------------------------------------------------------------------------------------- | | `subject.businessRegistrationCertificate` | M | N/A | Business Registration certificate (BR). | | `subject.businessFormation` | M | M | Certificate of incorporation (HK CI / Other Certificate of Incorporation). | | `subject.incorporationFormNnc1` | C | N/A | Incorporation form NNC1. **Note 1**. | | `subject.annualReturnNar1` | C | N/A | Annual return NAR1. **Note 1**. | | `subject.einConfirmationLetter` | N/A | M | IRS EIN confirmation letter (CP575 / 147C). | | `subject.bylaws` | N/A | C | Bylaws — when `businessType` is a corporation subtype (`B_/C_/CLOSE_/S_CORPORATION`). **Note 4**. | | `subject.operatingAgreement` | N/A | C | Bylaws — when `businessType = LLC`, or the consolidated fallback when businessType is not provided. **Note 4**. | | `subject.partnershipAgreement` | N/A | C | Bylaws — when `businessType = LLP`/`LP`/`GENERAL_PARTNERSHIP`. **Note 4**. | | `subject.registerOfDirectors` | C | C | Register of directors. **Note 2**. | | `subject.ownershipProof` | C | C | Register of shareholders. **Note 2**. | | `subject.shareholdingStructureChart` | C | C | Shareholding structure chart. **Note 2, Note 3**. | | `subject.certificateOfGoodStanding` | N/A | O | Certificate of good standing. | | `subject.financialStatements` | O | O | Financial statements. | | `subject.authorizationLetter` | O | O | Authorization letter. | | `subject.sourceOfFundsProof` | M | M | Source-of-funds proof — see **Note 5**. | | `subject.supportiveOther` | O | O | Other supporting materials. | | `subject.bankStatement` / `utilityBill` / `leaseAgreement` / `taxNotice` / `addressProofOther` | O | O | Address proof (bank statement / utility bill / lease agreement / tax notice / other). | **Conditional rules:** * **Note 1 (HK formation documents):** Submit at least one of `incorporationFormNnc1` / `annualReturnNar1`. For companies incorporated over a year ago, prefer `annualReturnNar1` (most recent directors/shareholders/address). * **Note 2 (ownership and directors):** Submit at least one of `registerOfDirectors` / `ownershipProof` / `shareholdingStructureChart` that fully shows directors and ownership. If already reflected by NNC1/NAR1 (HK) or the formation documents (Other), it may be omitted, in which case `subject.ownershipDeclaration.*` may also be omitted. * **Note 3:** If none of the above can show the complete ownership chain (e.g. multi-layer holdings), the supplement stage will request a `shareholdingStructureChart`. * **Note 4 (Other formation documents):** Submit the matching formation document per `businessType` — corporation subtype → `bylaws`; `LLC` → `operatingAgreement`; `LLP`/`LP`/`GENERAL_PARTNERSHIP` → `partnershipAgreement`. Submit only one, matching the actual organizational form. (When the type is unclear, `operatingAgreement` serves as the fallback.) * **Note 5 (source of funds):** Mandatory. Acceptable: company bank statements for the last 6 months, audited financial statements, key trade contracts + invoices, proof of capital contribution, investment agreements + receipts, etc. Multiple files are allowed (at least one). An account-balance screenshot alone is insufficient — it must show the chain by which the funds were formed. * **Address proof:** Required when `operatingAddressSameAsRegistered = false`, or when the submitted registration documents do not state the address. Provide it using the `subject.*` address-proof keys listed above; it must have been issued within the last 3 months. ### Representative Fields (`representative.*`) One group per person, distinguished by the **`representativeRef` attribute** of the `representatives[]` entry (**not** a key inside `fields[]`). | Key | HK | Other | Rule | | ------------------------------------------------- | :-: | :---: | ------------------------------------------------------------------------------------------------------------------------------------- | | `representativeRef` (attribute, not a fields key) | M | M | A stable per-person id in your system, kept unchanged across supplements. `subject.signerPersonRefId` references this value. | | `representative.role.responsibility` | O | O | **Single-value** enum: `ULTIMATE_BENEFICIAL_OWNER`/`AUTHORIZED_REPRESENTATIVE`/`DIRECTOR`. | | `representative.firstName` | M | M | English first name, ≤100, must match the ID document exactly. | | `representative.middleName` | O | O | English middle name, ≤100; fill in if the ID document has one. | | `representative.lastName` | M | M | English last name, ≤100, must match the ID document. | | `representative.fullNameCn` | O | N/A | Chinese name, ≤50. HK: fill in if the ID document has a Chinese name. | | `representative.jobTitle` | M | M | Position (e.g. Director, CEO), ≤100. | | `representative.birthDate` | M | M | `yyyy-MM-dd`, must match the ID document, must be ≥ 18 years old. | | `representative.nationality` | M | M | ISO 3166-1 alpha-2. | | `representative.ownershipPercentage` | C | C | Required when `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`. `0.01`–`100`, ≤2 decimal places; the actual look-through percentage. | | `representative.residentialAddress.addressLine1` | M | M | Actual residential address (not temporary), ≤200. | | `representative.residentialAddress.addressLine2` | O | O | ≤200. | | `representative.residentialAddress.city` | M | M | ≤100. | | `representative.residentialAddress.state` | O | M | Required for Other (2-letter state code). | | `representative.residentialAddress.postalCode` | O | M | Required for Other. | | `representative.residentialAddress.countryCode` | M | M | ISO 3166-1 alpha-2. | | `representative.email` | M | M | Required for each person, ≤128 (used for verification-code delivery). | | `representative.phone.countryCode` / `.number` | O | O | Recommended for the primary contact. | | `representative.identityDocument.ssn` | N/A | M | Other: each person's individual tax number (SSN/ITIN); not applicable to HK. | | `representative.identityDocument.idType` | M | M | See enum. | | `representative.identityDocument.idNumber` | M | M | ≤64. | | `representative.identityDocument.issuingCountry` | M | M | ISO 3166-1 alpha-2. | | `representative.identityDocument.issueDate` | O | O | `yyyy-MM-dd`. | | `representative.identityDocument.expiryDate` | M | M | `yyyy-MM-dd`. Use `9999-12-31` for permanent documents; expired documents fail validation. | | `representative.ownershipAttestedAt` | C | C | ISO 8601. Required when `subject.ownershipDeclaration.hasShareholderOver25Percent` has a value. | ### Representative Documents (`representative.*`, value is a `fileId`) Route the ID document file by `identityDocument.idType` (see the idType routing note in the enum). | Key | Req | Description | | ----------------------------------------------------------- | :-: | -------------------------------------------------------------------------------------------- | | `representative.passport` | C | Passport photo page (front only) — when `idType = PASSPORT`. | | `representative.idCardFront` / `idCardBack` | C | Both front and back of card-type documents are required — see idType routing. | | `representative.driversLicenseFront` / `driversLicenseBack` | C | Both front and back required when `idType = DRIVERS_LICENSE`. | | `representative.taxIdDocument` | C | Tax-number proof (SSN/ITIN), provided by Other persons together with `identityDocument.ssn`. | | `representative.proofOfAddress` | C | Required when the residential address differs from the address on the ID document. | | `representative.photoHoldingId` | O | Requested by risk control in cases of suspected fraud. | | `representative.liveSelfie` | O | Same as above. | | `representative.appointmentDocument` | O | Appointment/authorization document. | | `representative.nameChangeCertificate` | C | Required when the name on the ID document differs from the declared name. | | `representative.supportiveOther` | O | Other supporting materials. | ### Enums * **`subject.country`**: `HK`, `Other`. * **`subject.registrationNoType`**: `BRN` (HK), `EIN` (Other). * **`subject.businessType`** (single list, not split by jurisdiction): `B_CORPORATION`, `C_CORPORATION`, `CLOSE_CORPORATION`, `S_CORPORATION`, `LLC`, `LLP`, `LP`, `GENERAL_PARTNERSHIP`, `SOLE_PROPRIETOR`, `TRUST`, `COOPERATIVE`, `NONPROFIT_CORPORATION`, `OTHER`. (`OTHER` requires a description; the subset actually allowed per channel/country is returned by `requirements`.) * **`subject.serviceAgreementType`**: `FULL` (direct service relationship), `RECIPIENT` (recipient only, no direct relationship). * **`representative.role.responsibility`** (single value): `ULTIMATE_BENEFICIAL_OWNER`, `AUTHORIZED_REPRESENTATIVE`, `DIRECTOR`. * **`representative.identityDocument.idType`**: `PASSPORT`, `DRIVERS_LICENSE`, `NATIONAL_ID`, `STATE_OR_PROVINCIAL_ID`, `PERMANENT_RESIDENCY_ID`, `MATRICULATE_ID`, `MILITARY_ID`, `VISA`. * **ID document files routed by idType:** `PASSPORT` → `passport`; `DRIVERS_LICENSE` → `driversLicenseFront` + `driversLicenseBack`; all other government IDs (`NATIONAL_ID`/`STATE_OR_PROVINCIAL_ID`/`PERMANENT_RESIDENCY_ID`/`MATRICULATE_ID`/`MILITARY_ID`/`VISA`) → `idCardFront` + `idCardBack`. * **Address proof** (which `subject.*` document key to use): bank statement → `bankStatement`; utility bill → `utilityBill`; lease agreement → `leaseAgreement`; tax notice → `taxNotice`; other → `addressProofOther`. ### File Limits | Limit | Value | | ------------------------------ | ---------------------------------------------------------- | | Max files per submission | 30 | | Max bytes per file | 12,582,912 (12 MB) | | Max total bytes per submission | 104,857,600 (100 MB) | | Allowed content types | `application/pdf`, `image/jpeg`, `image/png`, `image/heic` | ### Role Integrity and Cross-Field Rules If any of the following is not satisfied, the request is rejected with `P_PAY_OPEN_API_INVALID_ARGUMENT`: * **Registration type matches jurisdiction:** `HK` ⇒ `registrationNoType = BRN`; `Other` ⇒ `EIN`. * **Other state required:** `Other` requires `subject.incorporationState`. * **Operating address required:** when `operatingAddressSameAsRegistered = false`, `operatingAddress` must be provided. * **Every representative has an `email`.** * **Beneficial-owner ownership:** when `hasShareholderOver25Percent = true` (or the ownership documents show a holder ≥25%), at least one representative has `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`; each such role's `ownershipPercentage` is in `(0, 100]`, and the total is ≤ 100. * **ID document not expired**; card-type documents and `DRIVERS_LICENSE` must have a **back** file. * **Age ≥ 18** (determined from `birthDate`). * **Other formation document matches `businessType`** (see Note 4). * **Each Other representative has an individual tax number** (`identityDocument.ssn`). * **Required company documents are complete** (per the matrix); source-of-funds proof is complete; ownership information is resolvable (via ownership documents or `ownershipDeclaration.*`). * **Consent items accepted:** both `termsAgreed` and `dataUsageAgreed` are `true`. # General Info # Basic Info > **Note:** The Institution API is currently Internal and only available to onboarded institutional providers. There is currently no self-service application channel available. **Base URL:** `https://api.pionex.com` **Protocol:** HTTPS **Data Format:** JSON **Field Naming:** camelCase (e.g. `userId`, `clientOrderId`). **Amounts:** decimal strings (e.g. `"100.50"`) - never float, never minor-unit integers. **Timestamps:** millisecond Unix timestamp (`int64`) in **response bodies**; the signature `timestamp` query parameter is in **seconds** (see Authentication). **Currency codes:** ISO 4217 uppercase (`"USD"`); country codes ISO 3166-1 alpha-2 uppercase (`"US"`). # Response Envelope All endpoints return a uniform envelope. Success: ```json { "result": true, "timestamp": 1785706000000, "data": { } } ``` Failure: ```json { "result": false, "timestamp": 1785706000000, "code": "P_PAY_OPEN_API_INVALID_ARGUMENT", "message": "..." } ``` Business failures are returned as HTTP `200` with `result: false`. The only two exceptions come from the authentication layer: `401` (authentication failed) and `400` (request body could not be read). # The userId Parameter Except for public/self endpoints (create user, list users, `asset/currencies`), **every endpoint requires `userId`** - the UUID of the target sub-account: * **GET requests:** pass `userId` in the query string (it participates in the signature). * **POST requests with a JSON body:** pass `userId` in the JSON request body. * **File upload** (`multipart/form-data`): pass `userId` in the query string. Obtain `userId` values from *List Sub-Accounts* (or the response of *Create Sub-Account*). # Authentication Every request (except where noted) is authenticated with your institution API Key and a **signature**. Apply for an API Key by registering your **public key** with Pionex; you keep the private key. --- [Next Page](https://www.pionex.com/docs/llms-full.txt/1)