Announcements 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

2025-12-18 11:53:58 UTC 25097 Read

[//]: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.

* 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.

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 3. Cancel all orders with 'open' status DELETE /futures/settle/orders 4. Query futures order list by time range GET /futures/settle/orders_timerange 5. Place batch futures orders POST /futures/settle/batch_orders 6. Query single order details GET /futures/settle/orders/order_id 7. Cancel single order DELETE /futures/settle/orders/order_id 8. Amend single order PUT /futures/settle/orders/order_id 9. 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**

### 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

<sp>
Gate Team
December 18, 2025
<sp>
**Gateway to Crypto**
Trade over %Amount_of_Currency% cryptocurrencies safely, quickly, and easily on Gate
**Take Action Now**
<a href="https://www.gate.com/signup" target="_blank">Sign up</a> and claim up to $10,000 in welcome rewards
<a href="https://www.gate.com/referral" target="_blank">Invite friends</a> and earn a 40% commission
**Stay Connected**
<a href="https://www.gate.com/" target="_blank">Visit Gate's official website</a>
<a href="https://www.gate.com/mobileapp?ch=ann48788" target="_blank">Download the Gate App | Desktop</a>
<a href="https://x.com/Gate" rel="nofollow noopener noreferrer" target="_blank">Follow us on X (Twitter)</a> to get more bonuses
<a href="https://t.me/GateCom_EN" rel="nofollow noopener noreferrer" target="_blank">Join our Telegram community</a> to discuss trending topics
<a href="https://www.gate.com/community" target="_blank">Engage with our global community</a> for the latest insights
**Transparency & Security**
<a href="https://www.gate.com/proof-of-reserves" target="_blank">Check our 100% Proof of Reserves</a>

Change & Chart Start-End Time

Rise/Fall Color

Pay With

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

Select language and region

Select your region

Fiat Currencies