Futures

Get Futures Exchanges

Request class: FutureExchangeRequest

Parameters

Parameter	Type	Required	Description
secType	string	Yes	Security type. Only `FUT` (futures) is supported.
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

Returns a list of FutureExchangeItem objects with the following fields:

Name	Type	Description
code	string	Exchange code
name	string	Exchange name
zoneId	string	Exchange time zone

Example

FutureExchangeResponse response = client.execute(FutureExchangeRequest.newRequest(SecType.FUT.name()));
System.out.println(response.getFutureExchangeItems());

Example Response

[
  {
    "code": "SGX",
    "name": "SGX",
    "zoneId": "Singapore"
  },
  {
    "code": "HKEX",
    "name": "HKEX",
    "zoneId": "Asia/Hong_Kong"
  },
  {
    "code": "CBOE",
    "name": "CBOE",
    "zoneId": "America/Chicago"
  }
]

Rate Limit

The base rate limit is 10 requests/min.

Get Tradable Contracts by Exchange

Request class: FutureContractByExchCodeRequest

Parameters

Parameter	Type	Required	Description
exchangeCode	string	Yes	Exchange code
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

Returns a list of FutureContractItem objects with the following fields:

Name	Type	Description
type	string	Futures product code, such as `CL`.
trade	boolean	Whether the contract is tradable.
continuous	boolean	Whether this is a continuous contract.
name	string	Localized contract name, based on the `lang` parameter.
currency	string	Trading currency
ibCode	string	Trading contract code used for placing orders, e.g., CL
contractCode	string	Contract code, e.g., CL1901
contractMonth	string	Contract delivery month
lastTradingDate	string	Last trading date in the contract's expiration month. Most futures use this as the settlement date; some products, such as Euro futures, have the same first notice date and last trading date. Cash-settled futures allow opening positions until the final trading cutoff. For physically settled futures, opening positions is restricted beginning three trading days before the earlier of the final trading cutoff and the first notice date.
lastTradingTimestamp	Long	Exact cutoff time on the last trading day
firstNoticeDate	string	First date on which a physically settled contract may enter delivery. New long positions cannot be opened after this date, and existing long positions are normally closed three trading days beforehand. Empty for contracts without physical delivery, such as index futures.
lastBiddingCloseTime	long	Bidding close time
multiplier	BigDecimal	Contract multiplier
exchangeCode	string	Exchange code
exchange	string	Exchange
minTick	BigDecimal	Minimum price increment. For example, at price 2000 with `minTick` 100, 2100 and 2200 follow the tick size, while 2005 does not
productWorth	string	Contract size
deliveryMode	string	Delivery mode
productType	string	Contract type
productScale	string	Contract specification
timeZone	string	Time zone

Example Request

FutureBatchContractResponse response = client.execute(FutureContractByExchCodeRequest.newRequest("CME"));
System.out.println(response.getFutureContractItems());

Example Response

[
  {
    "type": "MEUR",
    "name": "E-Micro EUR/USD - main",
    "ibCode": "M6E",
    "contractCode": "MEURmain",
    "contractMonth": "",
    "exchangeCode": "GLOBEX",
    "multiplier": 12500,
    "minTick": 0.0001,
    "lastTradingDate": "",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "MEUR",
    "name": "E-Micro EUR/USD - Jun 2022",
    "ibCode": "M6E",
    "contractCode": "MEUR2206",
    "contractMonth": "202206",
    "exchangeCode": "GLOBEX",
    "multiplier": 12500,
    "minTick": 0.0001,
    "lastTradingDate": "20220613",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "MEUR",
    "name": "E-Micro EUR/USD - Mar 2022",
    "ibCode": "M6E",
    "contractCode": "MEUR2203",
    "contractMonth": "202203",
    "exchangeCode": "GLOBEX",
    "multiplier": 12500,
    "minTick": 0.0001,
    "lastTradingDate": "20220314",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CHF",
    "name": "Swiss Franc - Jun 2022",
    "ibCode": "CHF",
    "contractCode": "CHF2206",
    "contractMonth": "202206",
    "exchangeCode": "GLOBEX",
    "multiplier": 125000,
    "minTick": 0.0001,
    "lastTradingDate": "20220613",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CHF",
    "name": "Swiss Franc - main",
    "ibCode": "CHF",
    "contractCode": "CHFmain",
    "contractMonth": "",
    "exchangeCode": "GLOBEX",
    "multiplier": 125000,
    "minTick": 0.0001,
    "lastTradingDate": "",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CHF",
    "name": "Swiss Franc - Dec 2022",
    "ibCode": "CHF",
    "contractCode": "CHF2212",
    "contractMonth": "202212",
    "exchangeCode": "GLOBEX",
    "multiplier": 125000,
    "minTick": 0.0001,
    "lastTradingDate": "20221219",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  }
]

Rate Limit

The base rate limit is 120 requests/min.

Get Futures Contract

Request class: FutureContractByConCodeRequest

Around the first notice date or final settlement date, liquidity generally shifts from the expiring contract to the next contract month. Consider rolling the position or trading the next contract month before the first notice date or as the last trading date approaches, for both long and short positions.

Parameters

Parameter	Type	Required	Description
contractCode	string	Yes	Contract symbol, e.g., CN1901
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

FutureContractItem object

FutureContractItem fields:

Name	Type	Description
type	string	Futures contract trading variety, e.g., CL
trade	boolean	Whether the contract is tradable
continuous	boolean	Whether this is a continuous contract
name	string	Contract name, available in Chinese and English, returned based on lang parameter
currency	string	Trading currency
ibCode	string	Trading contract code used for placing orders, e.g., CL
contractCode	string	Contract code, e.g., CL1901
contractMonth	string	Contract delivery month
lastTradingDate	string	Last trading date in the contract's expiration month. Most futures use this as the settlement date; some products, such as Euro futures, have the same first notice date and last trading date. Cash-settled futures allow opening positions until the final trading cutoff. For physically settled futures, opening positions is restricted beginning three trading days before the earlier of the final trading cutoff and the first notice date.
firstNoticeDate	string	First date on which a physically settled contract may enter delivery. New long positions cannot be opened after this date, and existing long positions are normally closed three trading days beforehand. Empty for contracts without physical delivery, such as index futures.
lastBiddingCloseTime	long	Bidding close time
lastTradingTimestamp	Long	Exact cutoff time on the last trading day
multiplier	BigDecimal	Contract multiplier
exchangeCode	string	Exchange code
exchange	string	Exchange
minTick	BigDecimal	Minimum price increment. For example, at price 2000 with `minTick` 100, 2100 and 2200 follow the tick size, while 2005 does not
productWorth	string	Contract size
deliveryMode	string	Delivery mode
productType	string	Contract type
productScale	string	Contract specification
timeZone	string	Time zone

Example

FutureContractResponse response = client.execute(FutureContractByConCodeRequest.newRequest("CN2203"));
System.out.println(response.getFutureContractItem());

Example Response

{
  "type": "CL",
  "name": "Light  Crude Oil - Mar 2022",
  "ibCode": "CL",
  "contractCode": "CL2203",
  "contractMonth": "202203",
  "exchangeCode": "NYMEX",
  "multiplier": "1000",
  "minTick": 0.01,
  "lastTradingDate": "20220222",
  "firstNoticeDate": "20220224",
  "lastBiddingCloseTime": 0,
  "currency": "USD",
  "continuous": false,
  "trade": true
}

Rate Limit

The base rate limit is 120 requests/min.

Query Current Main Contract for Specified Symbol

Request class: FutureCurrentContractRequest

Description

Query main contract for the specified symbol

Input Parameters:

Parameter	Type	Required	Description
type	string	Yes	Futures contract trading variety, e.g., CL
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

FutureContractItem object

FutureContractItem fields:

Name	Type	Description
type	string	Futures contract trading variety, e.g., CL
trade	boolean	Whether the contract is tradable
continuous	boolean	Whether this is a continuous contract
name	string	Contract name, available in Chinese and English, returned based on lang parameter
currency	string	Trading currency
ibCode	string	Trading contract code used for placing orders, e.g., CL
contractCode	string	Contract code, e.g., CL1901
contractMonth	string	Contract delivery month
lastTradingDate	string	Last trading date in the contract's expiration month. Most futures use this as the settlement date; some products, such as Euro futures, have the same first notice date and last trading date. Cash-settled futures allow opening positions until the final trading cutoff. For physically settled futures, opening positions is restricted beginning three trading days before the earlier of the final trading cutoff and the first notice date.
lastTradingTimestamp	Long	Exact cutoff time on the last trading day
firstNoticeDate	string	First date on which a physically settled contract may enter delivery. New long positions cannot be opened after this date, and existing long positions are normally closed three trading days beforehand. Empty for contracts without physical delivery, such as index futures.
lastBiddingCloseTime	long	Bidding close time
multiplier	BigDecimal	Contract multiplier
exchangeCode	string	Exchange code
exchange	string	Exchange
minTick	BigDecimal	Minimum price increment. For example, at price 2000 with `minTick` 100, 2100 and 2200 follow the tick size, while 2005 does not
productWorth	string	Contract size
deliveryMode	string	Delivery mode
productType	string	Contract type
productScale	string	Contract specification
timeZone	string	Time zone

Example Request

FutureContractResponse response = client.execute(FutureCurrentContractRequest.newRequest("CL"));
System.out.println(response.getFutureContractItem());

Example Response

{
  "type": "CL",
  "name": "Light Crude Oil - Mar 2022",
  "ibCode": "CL",
  "contractCode": "CL2203",
  "contractMonth": "202203",
  "exchangeCode": "NYMEX",
  "multiplier": 1000,
  "minTick": 0.01,
  "lastTradingDate": "20220222",
  "firstNoticeDate": "20220224",
  "lastBiddingCloseTime": 0,
  "currency": "USD",
  "continuous": false,
  "trade": true
}

Rate Limit

The base rate limit is 120 requests/min.

Query All Contracts of Specified Symbol

Request class: FutureContractsRequest

Parameters

Parameter	Type	Required	Description
type	string	Yes	Futures contract trading variety, e.g., CL
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

List of FutureContractItem objects

FutureContractItem fields:

Name	Type	Description
type	string	Futures contract trading variety, e.g., CL
trade	boolean	Whether the contract is tradable
continuous	boolean	Whether this is a continuous contract
name	string	Contract name, available in Chinese and English, returned based on lang parameter
currency	string	Trading currency
ibCode	string	Trading contract code used for placing orders, e.g., CL
contractCode	string	Contract code, e.g., CL1901
contractMonth	string	Contract delivery month
lastTradingDate	string	Last trading date in the contract's expiration month. Most futures use this as the settlement date; some products, such as Euro futures, have the same first notice date and last trading date. Cash-settled futures allow opening positions until the final trading cutoff. For physically settled futures, opening positions is restricted beginning three trading days before the earlier of the final trading cutoff and the first notice date.
lastTradingTimestamp	Long	Exact cutoff time on the last trading day
firstNoticeDate	string	First date on which a physically settled contract may enter delivery. New long positions cannot be opened after this date, and existing long positions are normally closed three trading days beforehand. Empty for contracts without physical delivery, such as index futures.
lastBiddingCloseTime	long	Bidding close time
multiplier	BigDecimal	Contract multiplier
exchangeCode	string	Exchange code
exchange	string	Exchange
minTick	BigDecimal	Minimum price increment. For example, at price 2000 with `minTick` 100, 2100 and 2200 follow the tick size, while 2005 does not
productWorth	string	Contract size
deliveryMode	string	Delivery mode
productType	string	Contract type
productScale	string	Contract specification
timeZone	string	Time zone

Example Request

FutureContractsResponse contractResponse = client.execute(FutureContractsRequest.newRequest("CN"));
System.out.println(contractResponse.getFutureContractItems());

Example Response

[
  {
    "type": "CN",
    "name": "China A50 Index - Aug 2022",
    "ibCode": "XINA50",
    "contractCode": "CN2208",
    "contractMonth": "202208",
    "exchangeCode": "SGX",
    "multiplier": 1,
    "minTick": 1,
    "lastTradingDate": "20220830",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CN",
    "name": "China A50 Index - Sep 2022",
    "ibCode": "XINA50",
    "contractCode": "CN2209",
    "contractMonth": "202209",
    "exchangeCode": "SGX",
    "multiplier": 1,
    "minTick": 1,
    "lastTradingDate": "20220929",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CN",
    "name": "China A50 Index - Oct 2022",
    "ibCode": "XINA50",
    "contractCode": "CN2210",
    "contractMonth": "202210",
    "exchangeCode": "SGX",
    "multiplier": 1,
    "minTick": 1,
    "lastTradingDate": "20221028",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CN",
    "name": "China A50 Index - Dec 2022",
    "ibCode": "XINA50",
    "contractCode": "CN2212",
    "contractMonth": "202212",
    "exchangeCode": "SGX",
    "multiplier": 1,
    "minTick": 1,
    "lastTradingDate": "20221229",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  },
  {
    "type": "CN",
    "name": "China A50 Index - Mar 2023",
    "ibCode": "XINA50",
    "contractCode": "CN2303",
    "contractMonth": "202303",
    "exchangeCode": "SGX",
    "multiplier": 1,
    "minTick": 1,
    "lastTradingDate": "20230330",
    "firstNoticeDate": "",
    "lastBiddingCloseTime": 0,
    "currency": "USD",
    "continuous": false,
    "trade": true
  }
]

Query Continuous Contracts of Specified Symbol

Request class: FutureContinuousContractRequest

Parameters

Parameter	Type	Required	Description
type	string	Yes	Futures contract trading variety, e.g., CL
lang	`Language`	No	Language for returned names: `zh_CN`, `zh_TW`, or `en_US`. If omitted, the `ClientConfig` default is used; its initial value is `en_US`.

Response

FutureContractItem object

FutureContractItem fields:

Name	Type	Description
type	string	Futures contract trading variety, e.g., CL
trade	boolean	Whether the contract is tradable
continuous	boolean	Whether this is a continuous contract
name	string	Contract name, available in Chinese and English, returned based on lang parameter
currency	string	Trading currency
ibCode	string	Trading contract code used for placing orders, e.g., CL
contractCode	string	Contract code, e.g., CL1901
contractMonth	string	Contract delivery month
lastTradingDate	string	Last trading date in the contract's expiration month. Most futures use this as the settlement date; some products, such as Euro futures, have the same first notice date and last trading date. Cash-settled futures allow opening positions until the final trading cutoff. For physically settled futures, opening positions is restricted beginning three trading days before the earlier of the final trading cutoff and the first notice date.
lastTradingTimestamp	Long	Exact cutoff time on the last trading day
firstNoticeDate	string	First date on which a physically settled contract may enter delivery. New long positions cannot be opened after this date, and existing long positions are normally closed three trading days beforehand. Empty for contracts without physical delivery, such as index futures.
lastBiddingCloseTime	long	Bidding close time
multiplier	BigDecimal	Contract multiplier
exchangeCode	string	Exchange code
exchange	string	Exchange
minTick	BigDecimal	Minimum price increment. For example, at price 2000 with `minTick` 100, 2100 and 2200 follow the tick size, while 2005 does not
productWorth	string	Contract size
deliveryMode	string	Delivery mode
productType	string	Contract type
productScale	string	Contract specification
timeZone	string	Time zone

Example Request

FutureContractResponse cl = client.execute(FutureContinuousContractRequest.newRequest("CL"));
System.out.println(cl.getFutureContractItem());

Example Response

{
  "type": "ES",
  "name": "E-mini S&P 500 - main",
  "ibCode": "ES",
  "contractCode": "ESmain",
  "contractMonth": "",
  "exchangeCode": "GLOBEX",
  "multiplier": 50,
  "minTick": 0.25,
  "lastTradingDate": "",
  "firstNoticeDate": "",
  "lastBiddingCloseTime": 0,
  "currency": "USD",
  "continuous": false,
  "trade": true
}

Rate Limit

The base rate limit is 120 requests/min.

Query Historical Main Futures Contract Codes

Request class: FutureHistoryMainContractRequest

Parameters

Parameter	Type	Required	Description
contractCodes	`List<String>`	Yes	Main futures contract codes, maximum 50, e.g. `ESmain`
beginTime	`Long` or string	Yes	Start time (exclusive), as a millisecond timestamp or `yyyy-MM-dd` through the string overload
endTime	`Long` or string	Yes	End time (inclusive), as a millisecond timestamp or `yyyy-MM-dd` through the string overload
zoneId	`TimeZoneId`	No	Time zone for the string overload; defaults to the `ClientConfig` time zone

Response

FutureHistoryMainContractItem object

FutureHistoryMainContractItem fields:

Name	Type	Description
contractCode	string	Futures main contract code
mainReferItems	array	Historical contract list of main contract, see `FutureHistoryContractItem` field description below

Historical contract data mainReferItems attributes:

Name	Type	Description
time	long	Date timestamp
referContractCode	string	Futures contract corresponding to main continuous contract

Example Request

List<String> contractCodes = new ArrayList<>();
contractCodes.add("ESmain");
FutureHistoryMainContractRequest request = FutureHistoryMainContractRequest.newRequest(contractCodes,
  "2023-06-01", "2023-10-05", TimeZoneId.NewYork);
FutureHistoryMainContractResponse response = client.execute(request);
if (response.isSuccess()) {
  System.out.println(JSONObject.toJSONString(response));
} else {
  System.out.println(response.getMessage());
}

Example Response

{
    "code":0,
    "data":[
        {
            "contractCode":"ESmain",
            "mainReferItems":[
                {
                    "referContractCode":"ES2312",
                    "time":1696453200000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1696366800000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1696280400000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1696021200000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695934800000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695848400000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695762000000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695675600000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695416400000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695330000000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695243600000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695157200000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1695070800000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1694811600000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1694725200000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1694638800000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1694552400000
                },
                {
                    "referContractCode":"ES2312",
                    "time":1694466000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1694206800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1694120400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1694034000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693947600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693602000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693515600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693429200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693342800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1693256400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692997200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692910800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692824400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692738000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692651600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692392400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692306000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692219600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692133200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1692046800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691787600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691701200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691614800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691528400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691442000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691182800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691096400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1691010000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690923600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690837200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690578000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690491600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690405200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690318800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1690232400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689973200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689886800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689800400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689714000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689627600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689368400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689282000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689195600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689109200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1689022800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688763600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688677200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688590800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688404500000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688158800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1688072400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687986000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687899600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687813200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687554000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687467600000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687381200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1687294800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1686949200000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1686862800000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1686776400000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1686690000000
                },
                {
                    "referContractCode":"ES2309",
                    "time":1686603600000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1686344400000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1686258000000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1686171600000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1686085200000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1685998800000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1685739600000
                },
                {
                    "referContractCode":"ES2306",
                    "time":1685653200000
                }
            ]
        }
    ],
    "message":"success",
    "sign":"H/m3GVmsGstQNJxnQrF4nNwkJ3EBJEIBTHMdxzvRKVdM5XtB+PhxlVJBSYclHSRkFn13ckgEr13pzGTrGYjM7cT5zXTTNn0wS0WtVsJoycaUoWqr8KT8P6B6cHq0Sj5LVA5nZlNpno33dplWMWNX3urDf6OiGtQ6J9/ZJcZnvxM=",
    "success":true,
    "timestamp":1696499214141
}

Rate Limit

The base rate limit is 60 requests/min.

Query Trading Hours of Specified Contract

Request class: FutureTradingDateRequest

Parameters

Parameter	Type	Required	Description
contractCode	string	Yes	Futures contract code, e.g., CL1901
tradingDate	`Long` or string	No	Trading date as a millisecond timestamp or `yyyy-MM-dd HH:mm:ss`. The contract-code-only overload uses the current time.
zoneId	`TimeZoneId`	No	Time zone for the string overload; defaults to the `ClientConfig` time zone

Response

FutureTradingDateItem object

FutureTradingDateItem fields:

Name	Type	Description
tradingTimes	`List<TimeSection>`	Trading periods
biddingTimes	`List<TimeSection>`	Bidding periods
timeSection	string	Trading time zone

TimeSection fields:

Name	Type	Description
start	long	Period start, in milliseconds since the Unix epoch
end	long	Period end, in milliseconds since the Unix epoch

Example Request

FutureTradingDateResponse response = client.execute(FutureTradingDateRequest.newRequest("ES2203", System.currentTimeMillis()));
System.out.println(response.getFutureTradingDateItem());

Example Response

FutureTradingDateItem{biddingTimes=[TimeSection{start=1644873300000, end=1644874200000}], tradingTimes=[TimeSection{start=1644793200000, end=1644873300000}, TimeSection{start=1644874200000, end=1644876000000}], timeSection='America/Chicago'}

Rate Limit

The base rate limit is 60 requests/min.

Get Futures Real-time Quotes

Request class: FutureRealTimeQuoteRequest

Description

Get real-time futures quotes. You must purchase market data access for the corresponding market before using this endpoint.

Parameters

Parameter	Type	Required	Description
contractCodes	array	Yes	List of contract codes, supports main contracts, e.g., CL1901/CLmain

Response

List of FutureRealTimeItem objects

FutureRealTimeItem fields:

Name	Type	Description
contractCode	string	Contract code
latestPrice	BigDecimal	Latest trade price
latestSize	Long	Volume of latest price
latestTime	Long	Time of latest price
bidPrice	BigDecimal	Bid price (level 1)
bidSize	Long	Bid quantity (level 1)
askPrice	BigDecimal	Ask price (level 1)
askSize	Long	Ask quantity (level 1)
volume	Long	Daily cumulative traded contracts
openInterest	Long	Open interest
openInterestChange	Long	Change in open interest
open	BigDecimal	Opening price
high	BigDecimal	Highest price
low	BigDecimal	Lowest price
settlement	BigDecimal	Settlement price, returns 0 when not generated
limitUp	BigDecimal	Daily limit up price
limitDown	BigDecimal	Daily limit down price
avgPrice	BigDecimal	Average traded price

Example

List<String> contractCodes = new ArrayList<>();
contractCodes.add("CL1902");

FutureRealTimeQuoteResponse response = client.execute(FutureRealTimeQuoteRequest.newRequest(contractCodes));
System.out.println(response.getFutureRealTimeItems());

Example Response

{
    "code": 0,
    "timestamp": 1545102059229,
    "message": "success",
    "data": [{
        "contractCode": "CN1901",
        "askPrice": 49.4,
        "askSize": 2,
        "bidPrice": 49.39,
        "bidSize": 4,
        "latestSize": 1,
        "latestPrice": 49.39,
        "volume": -18140,
        "openInterest": 72189,
        "openInterestChange": 0,
        "settlement": 49.88,
        "high": 49.59,
        "low": 49.14,
        "latestTime": 1545102035000,
        "open": 49.16,
        "limitUp": 55.88,
        "limitDown": 43.88
    }]
}

Rate Limit

The base rate limit is 120 requests/min.

Get Futures Market Depth

Request class: FutureDepthRequest

Description

Get the futures order book (multi-level bid/ask data).

Parameters

Parameter	Type	Required	Description
contractCodes	`List<String>`	Yes	Contract codes; main contracts such as `CLmain` are supported

Response

List of FutureDepthItem objects

FutureDepthItem fields:

Name	Type	Description
contractCode	string	Contract code
contractId	string	Contract ID
ask	`List<FutureDepthAskBidItem>`	Ask levels
bid	`List<FutureDepthAskBidItem>`	Bid levels

FutureDepthAskBidItem fields:

Name	Type	Description
price	BigDecimal	Order price
volume	Long	Order volume

Example

FutureDepthRequest request = FutureDepthRequest.newRequest(Collections.singletonList("XWmain"));
FutureDepthResponse response = client.execute(request);
System.out.println(response.getFutureDepthItems());

Example Response

{
  "code" : 0,
  "message" : "success",
  "timestamp" : 1754983558519,
  "sign" : "mfa4bnsB6ZNezDuPzqiKt7fIz/pVVfB/xcXoCPZh7q+4TXeXvAu6FgGd1NmsCMf10JQNXibes/+ayMrVxdT3VVsOqVfOAqaeyyB6cDISdIajArHlIVc16eCtv2s2ceoAL+XGFpNTJNof9TH0b9SzL5RYZy7xhVBe4MGGeXXdFfs=",
  "data" : [ {
    "lang" : null,
    "contractId" : "b1846ff7d24744a3a6b16b11ebeb16ee",
    "contractCode" : "XWmain",
    "ask" : [ {
      "price" : 5.12000,
      "volume" : 4
    }, {
      "price" : 5.12125,
      "volume" : 5
    }, {
      "price" : 5.12250,
      "volume" : 4
    }],
    "bid" : [ {
      "price" : 5.11625,
      "volume" : 7
    }, {
      "price" : 5.11500,
      "volume" : 6
    }, {
      "price" : 5.11375,
      "volume" : 4
    }],
    "account" : null
  } ],
  "success" : true
}

Get Futures Trade Ticks

Request class: FutureTickRequest

Description

The index resets to 0 every day at 6:00 AM Beijing time. Tick-by-tick data from the previous day is cleared one minute before the earliest trading session (auction or trading) begins. New tick-by-tick data is recorded after the new trading session starts.
This reset occurs only once per day, meaning multiple trading sessions within the same trading day do not trigger additional resets.

⚠️
Caution
Once the previous day's tick-by-tick data is cleared, the API can no longer access this data. For example: GC2504 tick data can be accessed before 5:59 AM, but will reset to index 0 at 6:00 AM.

Parameters

Parameter	Type	Required	Description
contractCode	string	Yes	Futures contract code, e.g., CL1901
beginIndex	long	No	Start index; defaults to `-1`. A subsequent request can use the last returned index plus 1.
endIndex	long	No	End index; defaults to `-1`. If both indices are `-1`, the latest records are returned. If one is `-1`, the query proceeds from the other index according to `limit`.
limit	int	No	Default 200. The SDK accepts 1 through 1,000; the service uses 200 when omitted or non-positive and caps values above 1,000 at 1,000.

beginIndex and endIndex Parameter Usage

Query Method	beginIndex	endIndex	Description
Query tick records forward	Specific value	-1	Example: beginIndex=10, endIndex=-1, limit=20, returns 20 records from 10 to 29.
Query tick records backward	-1	Specific value	Example: beginIndex=-1, endIndex=29, limit=20, returns 20 records from 10 to 29.
Query latest tick records	-1	-1	Returns limit latest tick records.
Query range index	Specific value	Specific value	Example: beginIndex=10, endIndex=100, returns 91 records from 10 to 100 inclusive. If limit is set to 20, returns 20 records from 10 to 29.

Response

FutureTickBatchItem object

FutureTickBatchItem fields:

Name	Type	Description
contractCode	string	Contract code
items	`List<FutureTickItem>`	Tick records

FutureTickItem fields:

Name	Type	Description
index	long	Daily tick index
price	BigDecimal	Trade price
volume	long	Trade volume
time	long	Trade time in milliseconds since the Unix epoch

Example

List<String> contractCodes = new ArrayList<>();
contractCodes.add("CL1902");

FutureTickResponse response = client.execute(FutureTickRequest.newRequest("CL2209", 10L, 100L,20));
System.out.println(response.getFutureTickItems());

Example Response

{
	"code": 0,
	"data": {
		"contractCode": "CL2209",
		"items": [{
			"index": 10,
			"price": 87.91,
			"time": 1660600802000,
			"volume": 6
		}, {
			"index": 11,
			"price": 87.90,
			"time": 1660600802000,
			"volume": 1
		}, {
			"index": 12,
			"price": 87.93,
			"time": 1660600802000,
			"volume": 1
		}, {
			"index": 13,
			"price": 87.91,
			"time": 1660600803000,
			"volume": 4
		}, {
			"index": 14,
			"price": 87.89,
			"time": 1660600804000,
			"volume": 1
		}, {
			"index": 15,
			"price": 87.90,
			"time": 1660600804000,
			"volume": 1
		}, {
			"index": 16,
			"price": 87.92,
			"time": 1660600804000,
			"volume": 2
		}, {
			"index": 17,
			"price": 87.91,
			"time": 1660600804000,
			"volume": 1
		}, {
			"index": 18,
			"price": 87.93,
			"time": 1660600805000,
			"volume": 8
		}, {
			"index": 19,
			"price": 87.93,
			"time": 1660600805000,
			"volume": 10
		}, {
			"index": 20,
			"price": 87.93,
			"time": 1660600805000,
			"volume": 7
		}, {
			"index": 21,
			"price": 87.93,
			"time": 1660600805000,
			"volume": 8
		}, {
			"index": 22,
			"price": 87.93,
			"time": 1660600805000,
			"volume": 7
		}, {
			"index": 23,
			"price": 87.95,
			"time": 1660600806000,
			"volume": 1
		}, {
			"index": 24,
			"price": 87.94,
			"time": 1660600806000,
			"volume": 1
		}, {
			"index": 25,
			"price": 87.95,
			"time": 1660600807000,
			"volume": 1
		}, {
			"index": 26,
			"price": 87.98,
			"time": 1660600807000,
			"volume": 1
		}, {
			"index": 27,
			"price": 87.99,
			"time": 1660600807000,
			"volume": 1
		}, {
			"index": 28,
			"price": 88.00,
			"time": 1660600807000,
			"volume": 1
		}, {
			"index": 29,
			"price": 87.97,
			"time": 1660600807000,
			"volume": 2
		}]
	},
	"message": "success",
	"sign": "llqaLoA5mQZN+nx1pGq5/mp1Ds5Z77uCvD+wM4TM7jtyvW",
	"success": true,
	"timestamp": 1660620843648
}

Rate Limit

The base rate limit is 120 requests/min.

Get Futures Candlestick Bars

Request class: FutureKlineRequest

Description

Provides daily candlestick bars (K-line data) for popular contracts over the past 10 years, and minute-level data for all contracts from August 2017 to present.

Results are returned in reverse chronological order starting from endTime.

For 1-minute K-line data, a minute with no trades has no bar. The endpoint returns the current minute's bar only after a trade occurs. If the first trade occurs at the 50th second, that minute's bar is unavailable before then.

Parameters

Parameter	Type	Required	Description
contractCodes	array	Yes	List of contract codes, supports main contracts, e.g., CL1901/CLmain
period	`FutureKType`	No	`min1`, `min2`, `min3`, `min5`, `min10`, `min15`, `min30`, `min45`, `min60`, `hour2`, `hour3`, `hour4`, `hour6`, `day`, `week`, or `month`. `null` and the contract-code-only overload default to `day`.
beginTime	`Long` or string	No	Inclusive start. Long values are milliseconds; string overloads accept `yyyy-MM-dd HH:mm:ss`. If omitted, the range starts seven days before the current time.
endTime	`Long` or string	No	Exclusive end. Long values are milliseconds; string overloads accept `yyyy-MM-dd HH:mm:ss`. If omitted, the range ends at the current time.
zoneId	`TimeZoneId`	No	Time zone for string values; defaults to the `ClientConfig` time zone
limit	Integer	No	Records per contract; default 200, maximum 1000. Larger values are capped at 1000.
pageToken	string	No	Pagination token (only supports single contract, queries with specified endTime), when using pageToken pagination, other query conditions cannot change

Response

List of FutureKlineBatchItem objects

FutureKlineBatchItem fields:

Field	Type	Description
contractCode	string	Contract code
nextPageToken	string	Next-page token, available only for one contract with a valid specified `endTime`; `null` means no more data. Keep all query conditions except `pageToken` unchanged while paging.
items	array	K-line array, see field descriptions below

candlestick bars (K-line data) items attributes:

Name	Type	Description
lastTime	long	Time of latest price trade
volume	long	Traded contracts
openInterest	long	Open interest
open	BigDecimal	Opening price
close	BigDecimal	Closing price
time	long	Time
high	BigDecimal	Highest price
low	BigDecimal	Lowest price
settlement	BigDecimal	Settlement price, returns 0 when not generated

Example

// Note: Futures contract codes expire on a quarterly schedule. Use FutureContractByExchCodeRequest
// to get the current active contract list, or use FutureContinuousContractRequest to get the
// continuous (main) contract code to avoid using expired contracts.
// The example below uses a historical contract code with a matching historical time range.
List<String> contractCodes = new ArrayList<>();
contractCodes.add("CL1901");

FutureKlineResponse response = client.execute(
    FutureKlineRequest.newRequest(contractCodes, FutureKType.min15, 1535634249489L,
        1538807049489L, 200));
System.out.println(response.getFutureKlineItems());

Example Response

{
        "code": 0,
        "timestamp": 1545105097358,
        "message": "success",
        "data": [{
                "contractCode": "CL1901",
                "items": [{
                                "lastTime": 1545083998000,
                                "volume": 124206,
                                "high": 51.87,
                                "openInterest": 90329,
                                "low": 4901,
                                "time": 1545084000000,
                                "close": 49.16,
                                "open": 51.25,
                                "settlement": 49.88
                        },
                        {
                                "lastTime": 1544824796000,
                                "volume": 434074,
                                "high": 52.95,
                                "openInterest": 131753,
                                "low": 5084,
                                "time": 1544824800000,
                                "close": 51.23,
                                "open": 52.83,
                                "settlement": 51.2
                        },
                        {
                                "lastTime": 1544738399000,
                                "volume": 593178,
                                "high": 53.27,
                                "openInterest": 186783,
                                "low": 5035,
                                "time": 1544738400000,
                                "close": 52.85,
                                "open": 51.2,
                                "settlement": 52.58
                        }
                ]
        }]
}

PageToken Example

    List<String> contractCodes = new ArrayList<>();
    contractCodes.add("NGmain");
    // pagetoken only for single symbol and specified endTime
    FutureKlineRequest request = FutureKlineRequest.newRequest(contractCodes, FutureKType.day,
        1650920400000L, 1651870900000L, 3);

    int count = 1;
    while (true) {
      FutureKlineResponse response = client.execute(request);
      System.out.println("search time:" + count + ", success:" + response.isSuccess() + ", msg:" + response.getMessage());
      if (!response.isSuccess()) {
        break;
      }
      System.out.println(response.getFutureKlineItems());
      if (response.getFutureKlineItems().size() == 0) {
        break;
      }
      String nextPageToken = response.getFutureKlineItems().get(0).getNextPageToken();
      if (nextPageToken == null) {
        break;
      }
      count++;
      // Conservative example: one request every 6 seconds, about 10/min,
      // below the base limit of 60 requests/min.
      try {
        TimeUnit.SECONDS.sleep(6);
      } catch (InterruptedException e) {
        e.printStackTrace();
      }
      // set nextPageToken and search next page data
      request.withPageToken(nextPageToken);
    }

Rate Limit

The base rate limit is 60 requests/min.