RPI Order Introduction
A Retail Price Improvement (RPI) order is a specialized order type designed exclusively for approved market makers. It matches only with non-algorithmic orders placed via the App or Web interface, providing retail traders with more targeted market liquidity and better execution prices. Meanwhile, it protects market makers' liquidity-providing orders from being matched against algorithmic orders, maintaining overall market fairness and integrity.
I. What Is an RPI Order?
An RPI order is a special limit order that can only be submitted via OpenAPI by whitelisted market makers. It features four core characteristics:
•Targeted Matching: Matches exclusively with non-algorithmic orders submitted via the App and Web interfaces. It does not match with API orders (including other RPI orders) or grid bot orders.
• Lowest priority: At the same price level, RPI orders will only participate in matching after all non-RPI orders have been executed.
•Maker Only: These are passive limit orders that always provide liquidity to the order book, never taking liquidity.
•Visibility Difference: Displayed normally on the App and Web interfaces; invisible in the public API order book.
II. Who Can Submit RPI Orders?
RPI orders can only be submitted via OpenAPI by approved, whitelisted market makers, and are strictly restricted to whitelisted trading pairs.
• Submissions by non-whitelisted market makers will trigger the message: "RPI orders are only available to approved market makers."
• Submissions on non-whitelisted trading pairs will trigger the message: "RPI orders are only supported for specific trading pairs."
III. How to Submit RPI Orders?
RPI orders can only be submitted via OpenAPI, supporting both REST and WebSocket methods. When placing an order, the order type (type) must be set as a limit order (buy-limit or sell-limit), and the time-in-force field must be set to rpi. All other parameters remain identical to standard limit orders.
REST Method
The spot, batch, and margin order placement endpoints all support RPI orders (the type must be buy-limit or sell-limit). Simply add the time-in-force field (with the value rpi) to the existing request parameters:
• Spot Order Placement: POST /v1/order/orders/place
• Batch Order Placement: POST /v1/order/batch-orders
• Margin Order Placement: POST /v1/order/auto/place
Request Example (Spot RPI Buy Order):
{
"account-id": "12345",
"symbol": "btcusdt",
"type": "buy-limit",
"amount": "0.01",
"price": "50000",
"time-in-force": "rpi"
}
WebSocket Method
The WebSocket trading channels also support RPI order placement, using the same parameters as the REST API:
• Spot Order Placement: Channel create-order
• Batch Order Placement: Channel create-batchorder
• Margin Order Placement: Channel create-margin-order
Common Error Codes
| Error Code |
Description |
|
|
The current account is not on the RPI whitelist and is not authorized to submit RPI orders. |
|
|
This trading pair is not on the RPI whitelist and does not support RPI order submission. |
|
|
The type must be buy-limit or sell-limit. |
|
|
The RPI feature is currently disabled. Please contact the operations team to confirm the launch schedule. |
Which Trading Pairs Support RPI Orders?
Call the Get All Trading Pairs endpoint GET /v2/settings/common/symbol. Each trading pair in the response includes an enable_rpi field (boolean). A value of true indicates that RPI support is enabled for the trading pair, while a value of false indicates that it is not supported.
Response Example (key fields only):
{
"status": "ok",
"data": [
{ "sc": "btcusdt", "dn": "BTC/USDT", "enable_rpi": true },
{ "sc": "ethusdt", "dn": "ETH/USDT", "enable_rpi": false }
]
}
If an RPI order request is submitted for a trading pair that does not support RPI, the system will return the error code order-rpi-symbol-not-allowed.
IV. Matching Scope
Orders That Can Be Matched with RPI Orders
• Source: APP / Web interface
• Types: Market orders, limit orders, advanced limit-FOK, advanced limit-IOC, take-profit/stop-loss orders, market/limit orders triggered by conditional orders
• Special: Copy trading / follow trading orders and iceberg orders are treated as regular orders and can be matched normally
Orders Not Eligible for RPI Matching
• All API orders (including other RPI orders and conditional orders triggered via API channels)
• Grid bot orders
V. Trading Rules
| Rule Item |
Description |
| Supported Products |
Spot (including Margin) |
| Order Mechanism |
Identical to standard limit orders (same margin requirements, minimum/maximum order sizes, and price limits) |
| Supported Operations |
Batch order placement, modification (price/quantity), cancellation, batch order cancellation, and partial order execution |
| Incompatibility |
Cannot be combined with conditional orders (TP/SL, trigger order, etc.) |
| Price Limit |
At order placement, orders cannot cross the price of non-RPI orders on the opposite side; otherwise, they will be canceled |
Price Limit Example
•Submitting an RPI buy order at a price of 99 → Accepted.
•Submitting an RPI buy order at a price of 102 → Rejected, as it crosses the non-RPI order at Ask 2 (price 102)
| Level |
Price |
Quantity |
| Ask 2 |
102 |
25 |
| Ask 1 |
100 (RPI) |
15 |
| Bid 1 |
99 (RPI) |
10 |
| Bid 2 |
98 |
20 |
VI. Order Visibility
| Module |
Scenario |
Description |
| Order Book |
APP / Web |
RPI orders are displayed normally without special tags; automatically hidden when prices cross. Hidden orders remain active in the matching engine and can be executed when conditions are met. |
| OpenAPI |
Not visible. |
|
| Personal Order History |
APP / Web |
Market makers can view RPI orders and the "RPI" tag in current and historical order records; regular users' orders show no special tags. |
| OpenAPI |
RPI orders are displayed normally and can be distinguished from regular orders. |
Price-Cross Hiding Examples
Example 1: Two RPI orders with crossed prices (buy price ≥ sell price) → Both sides are hidden.
| / |
Price |
Quantity |
Visible |
| Ask 4 |
1,005 |
20 |
Yes |
| Ask 3 |
1,003 (RPI) |
15 |
Yes |
| Ask 2 |
1,001 (RPI) |
10 |
No |
| Ask 1 |
999 (RPI) |
5 |
No |
| Bid 1 |
1,002 (RPI) |
10 |
No |
| Bid 2 |
1,000 (RPI) |
20 |
No |
| Bid 3 |
998 |
25 |
Yes |
| Bid 4 |
997 (RPI) |
30 |
Yes |
Example 2: RPI order crosses with an API order or grid strategy order → RPI order is hidden; the counterparty order is displayed normally
| / |
Price |
Quantity |
Visible |
| Ask 4 |
1,005 |
20 |
Yes |
| Ask 3 |
1,003 (RPI) |
15 |
Yes |
| Ask 2 |
1,001 (RPI) |
10 |
No |
| Ask 1 |
999 (RPI) |
5 |
No |
| Bid 1 |
1,002 (Grid Bots) |
10 |
Yes |
| Bid 2 |
1,000 (API) |
20 |
Yes |
| Bid 3 |
998 |
25 |
Yes |
| Bid 4 |
997 (RPI) |
30 |
Yes |
VII. Fee Structure
RPI orders are subject to an exclusive RPI maker fee rate, which replaces the market maker's original maker fee rate. Non-RPI orders continue to be charged at the original fee rate.
The exclusive RPI fee rate can be queried via the endpoint GET /v2/reference/transact-fee-rate. A new rpiFeeRate field is added to the response parameters, representing the current effective RPI maker fee rate. Alternatively, you may consult the HTX Market Maker Operations team directly.
VIII. API Endpoint and Data Stream Updates
To support the RPI order mechanism, existing endpoints have been adjusted according to the following rules.
REST Market Data
| Endpoint Name |
HTTP Request |
Description of Changes |
| Order Book Depth |
|
Adds an optional parameter includeRpi (Boolean, default false). When set to true, unaggregated depth data (step0) will include RPI orders. Other aggregated tiers remain unaffected. |
| Full Order Book Depth |
|
Same as above, with the addition of the includeRpi parameter |
| Recent Market Trades |
|
The response for each trade adds an isRpiTrade (Boolean) field; true indicates the execution was generated by an RPI order. |
| Recent Trade History |
|
Same as above, with the addition of the isRpiTrade field |
| Latest Tickers for All Trading Pairs |
|
No structural changes; RPI executions are factored into the metrics normally. |
| Merged Ticker Details |
|
No structural changes; RPI executions are factored into the metrics normally. |
| 24-Hour Market Details |
|
No structural changes; RPI executions are factored into the metrics normally. |
| Candlestick (K-Line) Data |
|
No structural changes; RPI executions are factored into the metrics normally. |
WebSocket Market Data Stream
| Channel |
Includes RPI Orders |
Description |
|
|
No |
Best Bid/Offer tick-by-tick data; RPI orders are excluded from calculations. |
|
|
No |
Market depth quotes, RPI pending orders are not included in the push |
|
|
Yes (New) |
Adds a new push channel to aggregate RPI pending orders. The protocol is consistent with the depth channel, allowing market makers to independently subscribe to full depth data including RPI. |
|
|
No |
Incremental MBP depth; RPI orders are not included in the push. |
|
|
No |
Full MBP snapshot; RPI orders are not included in the push. |
Order Placement and Query Endpoints (REST)
| Endpoint Name |
HTTP Request |
Description of Changes |
| Place Spot Orders |
|
Adds the time-in-force field (value: rpi). |
| Place Batch Orders |
|
Adds the time-in-force field (value: rpi). |
| Place Margin Order |
|
Adds the time-in-force field (value: rpi). |
| Query Current Open Orders |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). |
| Query Order Details |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). A new canceled-source enum value rpi_cancel is added, indicating the order was canceled by the system due to price crossing with a non-RPI order. |
| Query by clientOrderId |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). A new canceled-source enum value rpi_cancel is added, indicating the order was canceled by the system due to price crossing with a non-RPI order. |
| Trade Details |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). A new canceled-source enum value rpi_cancel is added, indicating the order was canceled by the system due to price crossing with a non-RPI order. |
| Search Order History |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). A new canceled-source enum value rpi_cancel is added, indicating the order was canceled by the system due to price crossing with a non-RPI order. |
| Order History in the Past 48 Hours |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). A new canceled-source enum value rpi_cancel is added, indicating the order was canceled by the system due to price crossing with a non-RPI order. |
| Current and Historical Trades |
|
A new time-in-force field is added to the response (value rpi indicates an RPI order). |
Order Push (WebSocket)
| Channel |
Description |
Description of Changes |
|
|
Order update push |
A new time-in-force field is added (value: rpi), enabling real-time differentiation between RPI orders and regular orders. |
|
|
Post-clearing trade and order cancellation updates |
A new time-in-force field is added (value: rpi); a new canceled-source enum value rpi_cancel is added, enabling real-time identification of cancellations triggered by price crossing. |
The above concludes the RPI Order documentation.
