[//]:content-type-MARKDOWN-DONOT-DELETE **Changes to Futures Size-Related Field Types** To enhance the flexibility of future trading and fully support fractional quantity orders, Gate will implement a phased upgrade for the USDT perpetual contract APIs. This upgrade will affect the parsing logic of order quantity (size) related fields in both REST API and WebSocket. Please assess and adjust your strategy logic in advance according to the phased plan to ensure your trading remains unaffected. ### 1.1 Upgrade Plan Overview (Divided into 3 Phases) **1. Phase 1: Field Type Compatibility Upgrade (Launched on December 9, 2025)** - Completed underlying data structure adjustments. - Modified the data type of contract quantity-related fields from Integer to String. - The system is currently in compatibility mode. By including the X-Gate-Size-Decimal field in the request header, compatibility processing for the contract lot quantity field is achieved. | Header Parameter | Description | Remarks | | :--- | :--- | :--- | | X-Gate-Size-Decimal = 1 | size-related field types change from Integer to String | 1. Supports receiving decimal data. | | X-Gate-Size-Decimal = 0 Or, not using this header field By default, this field is unused. | size-related field types remain Integer | 1. Does not support receiving decimal data.
2. Precision handling - Truncates towards zero (downwards). | * If the X-Gate-Size-Decimal header is not set, the size field will continue to accept and return the Integer type by default. **2. Phase 2: Fractional Quantity Ordering Capability Launch** 1. The system capability for fractional lot ordering on USDT perpetual contracts is scheduled to launch on December 30, 2025. During this phase, only the underlying system capabilities and API support will be enabled. No contracts will be practically opened for fractional lot ordering at this time, and the actual order placement rules for users will remain unchanged. 2. Starting from late January 2026, the fractional lot ordering functionality will be gradually rolled out to contracts. Specific contracts and timelines for the rollout will be announced by the platform in subsequent notices. 3. For users still using the old field type without adaptation, the following issues may arise: * Abnormal precision parsing in contract depth data. * Inconsistent order precision. * Abnormal precision in filled orders. ***Therefore, all API users are reminded to complete field type adaptation as much as possible by the end of January 2026.*** **3. Phase 3: Full Enablement for All USDT-Margined Perpetual Contracts and Mandatory Migration to String Field Types** 1. All contract trading pairs will fully support fractional lot order placement. 2. At a specified time, the system will default to returning String type and adjust the default value of the header (X-Gate-Size-Decimal), switching the default parsing behavior from 0 to 1 to provide a short transition period for users who have not yet completed adaptation. 3. After the transition period, the X-Gate-Size-Decimal header field will be officially deprecated, and its configuration will no longer take effect. 4. All order quantity-related fields will uniformly use the String type to ensure precision and compatibility. The legacy Integer type will no longer be supported. 5. The specific effective date will be announced in advance via official notice. Please ensure all adaptations are completed beforehand. ### 1.2 Detailed Explanation of Phase 1 Upgrade 1.Both REST and WebSocket APIs have introduced a new header field, X-Gate-Size-Decimal , to control the precision of quantity-related fields. | Header Parameter | Description | Remarks | | :--- | :--- | :--- | | X-Gate-Size-Decimal = 1 | size-related field types change from Integer to String | 1. Supports receiving decimal data. | | X-Gate-Size-Decimal = 0 Or, not using this header field By default, this field is unused. | size-related field types remain Integer| 1. Does not support receiving decimal data.
2. Precision handling - Truncates towards zero (downwards). | Recommendation: Clients should promptly adapt to the change in contract quantity field types. Once the contract officially supports fractional quantity ordering, they can quickly experience and utilize this functionality. 2.Reference Example for Setting Header Rest ``` # Set request headers headers = { 'KEY': API_KEY, 'Timestamp': timestamp, 'SIGN': signature, # Enable decimal size 'X-Gate-Size-Decimal': '1', 'Content-Type': 'application/json', 'Accept': 'application/json' } ``` Websocket ``` # Set request headers # Enable decimal size headers['X-Gate-Size-Decimal'] = '1' ``` ### 1.3 Future Size Field Type Changes **1. Rest Related Fields** | Interface Type | Endpoint | Field | Remarks | | :--- | :--- | :--- | :--- | | Public | 1. Query All Futures Info
GET /futures/settle/contracts
2. Query Single Future Info
GET /futures/settle/contracts/contract
| Minimum order size allowed by the contract 'order_size_min' Maximum order size allowed by the contract 'order_size_max' Historical cumulative trading volume 'trade_size' Current total long position size 'position_size' | 1. Using header field
X-Gate-Size-Decimal=1
, the type of the above fields will change from
Integer
to
String
.
2. Clients need to adjust the acceptance type for these fields.
| | Public | 1. Query futures market depth information
GET /futures/settle/order_book | Size
's'
|
| | Public | 1. Futures market transaction records
GET /futures/settle/trades | Trading Size 'size' |
| | Public | 1. Futures market K-line chart
GET /futures/settle/candlesticks | size volume (contract size)
'v' |
| | Public | 1. Futures statistics
GET /futures/settle/contract_stats
| Long liquidation size (contracts) 'long_liq_size' Short liquidation size (contracts) 'short_liq_size' Total open interest size (contracts) 'open_interest' Top trader long/short position ratio 'top_lsr_size' Top trader long size
'top_long_size'
Top trader short size 'top_short_size' Top taker long size 'long_taker_size'
Top taker short size 'short_taker_size' |
| | Public | 1. Query liquidation order history
GET /futures/settle/liq_orders | Position size 'size' Liquidation order price 'order_size' System liquidation order maker size 'left' |
| | Private | 1. Get user position list
GET /futures/settle/positions
2. Get single position information
GET /futures/settle/positions/contract
3. Update position margin
POST /futures/settle/positions/contract/margin
4. Update position leverage
POST /futures/settle/positions/contract/leverage
5. Switch Position Margin Mode
POST /futures/settle/positions/cross_mode
6. Switch Between Cross and Isolated Margin Modes Under Hedge Mode
POST /futures/settle/dual_comp/positions/cross_mode
7. Update position risk limit
POST /futures/settle/positions/contract/risk_limit
8. Set position mode
POST /futures/settle/dual_mode
9. Get position information in Hedge Mode
GET /futures/settle/dual_comp/positions/contract
10. Update position margin in Hedge Mode
POST /futures/settle/dual_comp/positions/contract/margin
11. Update position leverage in Hedge Mode
POST /futures/settle/dual_comp/positions/contract/leverage
12. Update position risk limit in Hedge Mode
POST /futures/settle/dual_comp/positions/contract/risk_limit | Position Size 'size'

|
| | Private | 1. Place futures order
POST /futures/settle/orders
2. Query futures order list GET /futures/settle/orders
1. Cancel all orders with 'open' status
DELETE /futures/settle/orders
2. Query futures order list by time range
GET /futures/settle/orders_timerange
3. Place batch futures orders
POST /futures/settle/batch_orders
4. Query single order details
GET /futures/settle/orders/order_id
5. Cancel single order
DELETE /futures/settle/orders/order_id
6. Amend single order
PUT /futures/settle/orders/order_id
7. Level-based BBO Contract Order Placement
POST /futures/settle/bbo_orders | Trading quantity. 'size' Display size for iceberg orders 'iceberg' Unfilled quantity 'left' |
| | Private | 1. Query personal trading records
GET /futures/settle/my_trades
2. Query personal trading records by time range
GET /futures/settle/my_trades_timerange | Trading Size 'size' Size of closed positions: 'close_size' |
| | Private | 1. Query position close history
GET /futures/settle/position_close
| Max Trade Size 'max_size' Cumulative closed position volume 'accum_size' |
| | Private | 1. Query liquidation history
GET /futures/settle/liquidates
| Position Size 'size' Liquidation Order Pending Size 'left' |
| | Private | 1. Query ADL auto-deleveraging order information GET /futures/settle/auto_deleverages

| Trade Size 'trade_size' Position Size After ADL 'position_size' |
| | Private | 1. Query auto order list
GET /futures/settle/price_orders
2. Cancel all auto orders
DELETE /futures/settle/price_orders
3. Query single auto order details
GET /futures/settle/price_orders/order_id
4. Cancel single auto order
DELETE /futures/settle/price_orders/order_id
5. Modify a Single Auto Order
PUT /futures/settle/price_orders/order_id | New field: 'amount' (string type).

| 1. New field:
amount
(string type).
2. The original field
size
(int ) and the new field
amount
(string) will be compatible.
| **2. Websocket Related Fields** | Channel Type | Channel | Fields | Remarks | | :--- | :--- | :--- | :--- | | Public | 1. Public Trades Channel
futures.trades
| Filled Size 'size'

| 1. Using header field
X-Gate-Size-Decimal=1
, the type of the above fields will change from
Integer
to
String
.
2. Clients need to adjust the acceptance type for these fields.
| | Public | 1. Ticker Channel
futures.tickers | Total Size 'total_size' |
| | Public | 1. BBO Channel
futures.book_ticker | Best Bid Size 'A' Best Ask Size
'B' |
| | Public | 1. Depth Update Channel
futures.order_book_update | Ask Side Pending Size 'a.s'
Bid Side Pending Size 'b.s' |
| | Public | 1. Full Depth Channel
futures.order_book

| Ask Side Pending Size
a.s
Bid Side Pending Size
b.s |
| | Public | 1. Depth V2 Channel
futures.obu | [price,size] 'size' May push decimal size |
| | Public | 1. Candlestick Channel
futures.candlesticks | Volume 'v' |
| | Public | 1. Public Liquidations Channel
futures.public_liquidates | Liquidation Order Size 'size' |
| | Public | 1. Contract Statistics Channel
futures.contract_stats | Long Liquidation Size 'long_liq_size'
Short Liquidation Size 'short_liq_size'
Total Open Interest 'open_interest' |
| | Private | 1. Private Orders Channel
futures.orders | Iceberg Display Size 'iceberg'
Remaining Tradeable Size 'left'
Order Size 'size' |
| | Private | 1. Private Trades Channel
futures.usertrades | Filled Size 'size' |
| | Private | 1. Private ADL Channel futures.auto_deleverages | Position Size 'position_size'
Trade Size 'trade_size' |
| | Private | 1. Positions Channel
futures.positions | Position Size 'size' |
| | Private | 1. Price Trigger Orders Channel
futures.autoorders
| New field: 'amount' (string type). | 1. New field:
amount
(string type).
2. The original field
size
(
Integer
type) and the new field
amount
(String) will be compatible. | | Private | 1. Liquidation Orders Channel
futures.liquidates
| Remaining Tradeable Size 'left'
Position Size 'size' | 1. Using header field
X-Gate-Size-Decimal=1
, the type of the above fields will change from
Integer
to
String
.
2. Clients need to adjust the acceptance type for these fields.
| | Private | 1. Order Placement
futures.order_place
2. Batch Order Placement
futures.order_batch_place
3. Order Cancellation
futures.order_cancel
4. Batch Cancel by ID
futures.order_cancel_cp
5. Order Amendment
futures.order_amend
6. Query Order List
futures.order_list
7. Query Order Details
futures.order_status
| Order Size 'size'
Remaining Tradeable Size 'left' Iceberg Display Quantity 'iceberg' |
| ### 1.4 Querying Future Information Supporting Decimal Order Placement 1.Set Header X-Gate-Size-Decimal=1 2.Request the Contract Information endpoint ``` curl --location 'https://api.gateio.ws/api/v4/futures/usdt/contracts' \ --header 'X-Gate-Size-Decimal: 1' ``` 3.Return Field order_size_min: If the value is a decimal, it indicates that the corresponding futures support decimal order placement. ### 1.5 Additional Information API Update Log: https://www.gate.com/docs/developers/apiv4/en/#changelog For any questions, please contact API technical support or refer to the API documentation. Thank you for your support and understanding
Gate Team December 18, 2025 **Gateway to Crypto** Trade over 4,200 cryptocurrencies safely, quickly, and easily on Gate **Take Action Now** Sign up and claim up to $10,000 in welcome rewards Invite friends and earn a 40% commission **Stay Connected** Visit Gate's official website Download the Gate App | Desktop Follow us on X (Twitter) to get more bonuses Join our Telegram community to discuss trending topics Engage with our global community for the latest insights **Transparency & Security** Check our 100% Proof of Reserves

Gate Announcement on USDT Perpetual Contract Order Quantity Field Type Changes and Feature Rollout Plan

Gate Announcement on USDT Perpetual Contract Order Quantity Field Type Changes and Feature Rollout Plan