Get Contract

Contract Introduction

A contract identifies a tradable instrument, such as a stock, option, or futures contract, according to exchange-defined attributes. For example, Tiger Brokers stock is uniquely identified by the symbol "TIGR" and market=US. Contract information uniquely identifies an instrument when placing orders or requesting market data.

Most contracts (such as stocks, CFDs, indices, or forex) can be uniquely determined by the following four basic attributes:

Symbol: Generally, US stocks, UK stocks and other contract codes are English letters, while Hong Kong stocks, A-shares and other contract codes are numbers. For example, Tiger Brokers' symbol is TIGR.
Security Type: Common contract types include: STK (stock), OPT (option), FUT (futures), CASH (forex). For example, Tiger Brokers' stock contract type is STK.
Currency: Common currencies include USD (US Dollar), HKD (Hong Kong Dollar).
Exchange: STK-type contracts generally don't use the exchange field as orders are automatically routed. Futures contracts all use the exchange field.

Some contracts (such as options and futures) require additional information to be uniquely identified due to their more complex nature.

The following are several common types of contracts and their constituent elements.

Stock

ContractItem contract = new ContractItem();
contract.setSymbol("TIGR");
contract.setSecType("STK");
contract.setCurrency("USD"); //Optional, defaults to USD when placing orders
contract.setMarket("US"); //Optional, contract market including US (US market), HK (Hong Kong market), CN (A-share market), SG (Singapore market), AU (Australia market), etc. Defaults to US when placing orders

Option

Tiger API's option contracts support two methods:

One is the four-element method: symbol (stock symbol), expiry (option expiration date), strike (option strike price), right (option right).
The other is the standard OCC option contract format with a fixed length of 21 characters, containing four parts:
- The code of the related stock or ETF, such as (AAPL), fixed at six characters, with insufficient digits filled with spaces
- Option expiration date, 6 digits, format: yymmdd
- Option type, value is P or C, representing put or call
- Option strike price, value is price x 1000, fixed at 8 digits, with insufficient leading digits filled with 0

ContractItem contract = new ContractItem();
contract.setSymbol("AAPL");
contract.setSecType("OPT");
contract.setCurrency("USD");
contract.setExpiry("20180821");
contract.setStrike(30D);
contract.setRight("CALL");
contract.setMultiplier(100.0D);
contract.setMarket("US"); //Optional

Futures

ContractItem contract = new ContractItem();
contract.setSymbol("CL1901");
contract.setSecType("FUT");
contract.setExchange("SGX");
contract.setCurrency("USD");
contract.setExpiry("20190328");
contract.setMultiplier(1.0D);

Crypto

ContractItem contract = new ContractItem();
contract.setSymbol("BTC.USD");
contract.setSecType("CC");

Fund

ContractItem contract = new ContractItem();
contract.setSymbol("IE00B11XZ988.USD");
contract.setSecType("FUND");

Get Single Contract Information

Request class: ContractRequest

Description

Get contract information required for trading.
Note that global accounts and prime accounts return different numbers of ContractItem field values. It's recommended to use the same account for getting contracts and placing orders.

Input Parameters

com.tigerbrokers.stock.openapi.client.https.request.contract.ContractRequest

Parameter	Type	Required	Description
account	string	Yes	User authorized account, e.g.: 572386
symbol	string	Yes	Stock symbol, e.g.: 00700/AAPL
sec_type	string	Yes	STK/OPT/FUT/CC
currency	string	No	USD/HKD/CNH
expiry	string	No	Expiration date, required for options, format: yyyyMMdd
strike	double	No	Strike price, required for options
right	string	No	CALL/PUT, required for options
exchange	string	No	Exchange (US stocks: SMART, HK stocks: SEHK, Shanghai-HK Connect: SEHKNTL, Shenzhen-HK Connect: SEHKSZSE)
secret_key	string	No	Trader secret key, for institutional users only

Response

com.tigerbrokers.stock.openapi.client.https.response.contract.ContractResponse

The data item fields are as follows:
com.tigerbrokers.stock.openapi.client.https.domain.contract.item.ContractItem

Name	Example	Description
identifier	CL2109/AAPL	Unique identifier, stock identifier is the same as symbol, option is a 21-character identifier like 'AAPL 220729C00150000', futures identifier
symbol	LRN	Stock symbol, option contract symbol is the corresponding underlying asset code
secType	STK	STK (stock)/OPT (option)/FUT (futures)/WAR (warrant)/IOPT (CBBC), etc., default STK
name	K12 INC	Stock name
localSymbol	1033	Global account specific, used for identifying warrants and CBBCs in Hong Kong stocks
currency	USD	USD/HKD/CNH
exchange	NYSE	Stock exchange
primaryExchange	NYSE	Stock listing exchange
market	US	Market, e.g.: US/HK/CN
expiry	20171117	Options and futures specific, option or futures expiration date
contractMonth	201804	Futures specific, contract delivery month
right	PUT	Options specific, option right, CALL or PUT
strike	24.0	Options specific, option strike price
multiplier	0.0	Options and futures specific, multiplier, quantity per lot
lotSize	100	Shares per lot: typically 1 for US stocks, 100 for A-shares, and contract-specific for HK stocks. Order quantities normally must be multiples of this value, except fractional-share orders.
minTick	0.001	Minimum tick size. Futures have a fixed value; stock tick sizes vary by price range, so this field may be null. Use `tickSizes` for the complete tiered configuration.
tickSizes	`[{"begin":"0","end":"1", "tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity", "tickSize":0.01,"type":"OPEN"}]`	Tiered minimum tick sizes. Each item contains `begin`, `end` (`Infinity` means no upper bound), interval `type` (`OPEN`, `CLOSED`, `OPEN_CLOSED`, or `CLOSED_OPEN`), and `tickSize`. Order prices must be integer multiples of the applicable `tickSize`.
marginable	true	Whether margin trading is available
shortable	true	Whether borrow inventory is currently available (`shortableCount > 0`). This does not indicate that the account itself has permission to short.
longInitialMargin	1	Long initial margin ratio in the range (0, 1]; for example, 0.3 means 30%
longMaintenanceMargin	1	Long maintenance margin ratio in the range (0, 1], usually below `longInitialMargin`
shortInitialMargin	0.35	Short initial margin ratio
shortMaintenanceMargin	0.3	Short maintenance margin ratio (has value for prime accounts, no value for global account contracts)
shortableCount	10000000	Available short selling quantity
shortFeeRate	0	Annualized stock-borrow fee rate; for example, 0.03 means 3%
tradingClass	LRN	Contract trading class name
tradeable	true	Whether the contract is tradable (STK category only)
continuous	false	Futures specific, whether it's a continuous contract
lastTradingDate	2019-01-01	Futures specific, last trading date
firstNoticeDate	2019-01-01	Futures specific, first notice date. Contracts cannot open long positions after the first notice date. Existing long positions will be forcibly closed before the first notice date (usually three trading days prior).
lastBiddingCloseTime	0	Futures specific, bidding close time
isEtf	false	Whether it's an ETF
etfLeverage	3	ETF leverage multiple, only exists when the contract is an ETF
discountedDayInitialMargin	3069.0	Futures specific, intraday discounted initial margin ratio
discountedDayMaintenanceMargin	2790.0	Futures specific, intraday discounted maintenance margin ratio
discountedTimeZoneCode	CDT	Futures specific, intraday discount time zone
discountedStartAt	17:30:00	Futures specific, intraday discount start time
discountedEndAt	14:30:00	Futures specific, intraday discount end time
supportOvernightTrading	true	Whether overnight trading is supported (US stocks only)
supportFractionalShare	true	Whether fractional-share trading is supported (prime/paper trading accounts only). HK fractional orders have a minimum of one share; US fractional orders have a minimum value of USD 1 and quantity precision of 0.0001.

Example

// Initialize client
TigerHttpClient client = TigerHttpClient.getInstance().clientConfig(ClientConfig.DEFAULT_CONFIG);

// Get stock contract
ContractRequest contractRequest = ContractRequest.newRequest(new ContractModel("AAPL"));
ContractResponse contractResponse = client.execute(contractRequest);
System.out.println("return stock contract:" + JSONObject.toJSONString(contractResponse));

// Get option contract
ContractModel model = new ContractModel("AAPL", SecType.OPT.name(),Currency.USD.name(), "20211126", 150D, Right.CALL.name());
contractRequest = ContractRequest.newRequest(model);
contractResponse = client.execute(contractRequest);
System.out.println("return option contract:" + JSONObject.toJSONString(contractResponse));

// Get warrant contract
ContractModel contractModel = new ContractModel("13745", SecType.WAR.name());
contractModel.setStrike(719.38D);
contractModel.setRight(Right.CALL.name());
contractModel.setExpiry("20211223");
contractRequest = ContractRequest.newRequest(contractModel);
contractResponse = client.execute(contractRequest);
System.out.println("return warrant contract:" + JSONObject.toJSONString(contractResponse));

// Get futures contract
contractRequest = ContractRequest.newRequest(
        new ContractModel("JPY2306", SecType.FUT.name()), "572386");
contractResponse = client.execute(contractRequest);
System.out.println("return future contract:" + JSONObject.toJSONString(contractResponse));

Example Response

{
    "code":0,
    "data":{
        "closeOnly":false,
        "currency":"USD",
        "etf":false,
        "identifier":"AAPL",
        "localSymbol":"AAPL",
        "longInitialMargin":0.3,
        "longMaintenanceMargin":0.25,
        "marginable":true,
        "market":"US",
        "multiplier":1,
        "name":"Apple",
        "secType":"STK",
        "shortInitialMargin":0.35,
        "shortMaintenanceMargin":0.3,
        "symbol":"AAPL",
        "tickSizes":[
            {
                "begin":"0",
                "end":"1",
                "tickSize":0.0001,
                "type":"CLOSED"
            },
            {
                "begin":"1",
                "end":"Infinity",
                "tickSize":0.01,
                "type":"OPEN"
            }
        ],
        "tradeable":true,
        "tradingClass":"AAPL"
    },
    "message":"success",
    "sign":"cWxRpcxoN7fICIBBK9WAq18TVtG7ez7dGJaCWOjSLHR8sQINPImZmAly9ctwCseA004K1f/7MgiHz4P9u48YdG9Vm07mUYdiNGaNJ4o79hPMi6Vq5IGMGOYFw3MQ/bZr6ikndgDZS7qQwDpBfeqTTDvzfxWFOh080wHw0SzE+co=",
    "success":true,
    "timestamp":1680838347544
}

Get Multiple Contract Information

Request class: ContractsRequest

Description

Get contract information required for trading, only supports STK and FUT.
Note that Global accounts and Prime accounts return different ContractItem fields. It's recommended to use the same account for getting contracts and placing orders.

⚠️
NOTE
The batch contracts returned by prime accounts do not include short quantity available and margin fields

Input Parameters

com.tigerbrokers.stock.openapi.client.https.request.contract.ContractsRequest

Parameter	Type	Required	Description
account	string	Yes	User authorized account e.g.: 572386
symbols	`List<String>`	Yes	Stock symbol list e.g.: 00700 / AAPL, max 50 per request
sec_type	string	Yes	STK/FUT/CC
currency	string	No	USD/HKD/CNH
secret_key	string	No	Trader secret key, for institutional users only

Response

com.tigerbrokers.stock.openapi.client.https.response.contract.ContractsResponse

Data item fields:
com.tigerbrokers.stock.openapi.client.https.domain.contract.item.ContractItem

Name	Example	Description
identifier	CL2109/AAPL	Unique identifier, stock identifier same as symbol, options use 21-character identifier like 'AAPL 220729C00150000', futures identifier
symbol	LRN	Stock symbol, for options contracts the symbol is the underlying asset symbol
secType	STK	STK stock/OPT option/FUT futures/WAR warrant/IOPT bull bear certificate etc., default STK
name	K12 INC	Stock name
localSymbol	1033	Global account only, HK stocks used to identify warrants and bull bear certificates
currency	USD	USD/HKD/CNH
exchange	NYSE	Stock exchange
primaryExchange	NYSE	Primary listing exchange
market	US	Market /US/HK/CN
expiry	20171117	Options and futures only, expiration date for options or futures
contractMonth	201804	Futures only, contract delivery month
right	PUT	Options only, option right, CALL or PUT
strike	24.0	Options only, option strike price
multiplier	0.0	Options and futures only, multiplier, quantity per contract
minTick	0.001	Minimum tick size. Futures have a fixed value; stock tick sizes vary by price range, so this field may be null. Use `tickSizes` for the complete tiered configuration.
tickSizes	`[{"begin":"0","end":"1", "tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity", "tickSize":0.01,"type":"OPEN"}]`	Stocks only. Tiered minimum tick sizes with `begin`, `end`, interval `type`, and `tickSize`. Order prices must be integer multiples of the applicable `tickSize`.
marginable	true	Whether margin trading is available
shortable	true	Whether borrow inventory is currently available (`shortableCount > 0`); account short-selling permission is separate
longInitialMargin	1	Long initial margin ratio in the range (0, 1]
longMaintenanceMargin	1	Long maintenance margin ratio in the range (0, 1], usually below `longInitialMargin`
shortInitialMargin	0.35	Short initial margin ratio
shortMaintenanceMargin	0.3	Short maintenance margin ratio (has value for prime accounts, no value for global account contracts)
shortableCount	10000000	Available short quantity
shortFeeRate	0	Annualized stock-borrow fee rate
tradingClass	LRN	Contract trading class name
tradeable	true	Whether the contract is tradable (STK only)
continuous	false	Futures only, whether continuous contract
lastTradingDate	2019-01-01	Futures only, last trading date
firstNoticeDate	2019-01-01	Futures only, first notice date. Long positions cannot be opened after first notice date. Existing long positions will be forcibly closed before first notice date (usually three trading days prior).
lastBiddingCloseTime	0	Futures only, bidding close time
isEtf	false	Whether it's an ETF
etfLeverage	0	ETF leverage ratio, only exists when contract is an ETF
supportOvernightTrading	true	Whether overnight trading is supported (US stocks only)

Example

List<String> symbols = new ArrayList<>();
symbols.add("AAPL");
symbols.add("TSLA");
ContractsModel models = new ContractsModel(symbols, SecType.STK.name());
ContractsRequest contractsRequest = ContractsRequest.newRequest(models, "13810712");
ContractsResponse contractsResponse = client.execute(contractsRequest);
System.out.println("return contracts:" + JSONObject.toJSONString(contractsResponse));

Example Response

{
    "code":0,
    "data":[
        {
            "currency":"USD",
            "etf":false,
            "identifier":"AAPL",
            "localSymbol":"AAPL",
            "market":"US",
            "multiplier":1,
            "name":"Apple Inc",
            "secType":"STK",
            "symbol":"AAPL",
            "tickSizes":[
                {
                    "begin":"0",
                    "end":"1",
                    "tickSize":0.0001,
                    "type":"CLOSED"
                },
                {
                    "begin":"1",
                    "end":"Infinity",
                    "tickSize":0.01,
                    "type":"OPEN"
                }
            ],
            "tradeable":true,
            "tradingClass":"AAPL"
        },
        {
            "currency":"USD",
            "etf":false,
            "identifier":"TSLA",
            "localSymbol":"TSLA",
            "market":"US",
            "multiplier":1,
            "name":"Tesla Motors",
            "secType":"STK",
            "symbol":"TSLA",
            "tickSizes":[
                {
                    "begin":"0",
                    "end":"1",
                    "tickSize":0.0001,
                    "type":"CLOSED"
                },
                {
                    "begin":"1",
                    "end":"Infinity",
                    "tickSize":0.01,
                    "type":"OPEN"
                }
            ],
            "tradeable":true,
            "tradingClass":"TSLA"
        }
    ],
    "message":"success",
    "sign":"Bv8H6BBfKOrMOhdJAanE0hwJiJAoKOk55/cTkJIVSmw9ENd2nmbeBI3cesqRgPq8bJ2dUBrYr+cqLVG65meXwbaFYyEenWlNyigl02IuJVoETgChuSoX1SZBTnafoVivCIj3neWG8BFdhaTNNXfBMbeSYf01+BqI6xYEc6KQxKc=",
    "success":true,
    "timestamp":1684912317872
}

Get Options/Warrants/Bull Bear Certificate Contract List

Request class: QuoteContractRequest

Input Parameters:

Parameter	Type	Required	Description
symbol	string	Yes	Stock symbol
sec_type	string	Yes	Contract type (OPT: options, WAR: HK warrants, IOPT HK bull bear certificates)
expiry	String	No	Expiration date, format: yyyyMMdd, required if OPT
lang	string	No	Language support: en_US, zh_CN, zh_TW, default: en_US

Response Fields

Name	Type	Description
symbol	string	Stock symbol
name	string	Contract name
exchange	string	Exchange
market	string	Market
secType	string	Contract type
currency	string	Currency
expiry	string	Expiration date (options, warrants, bull bear certificates, futures), 20171117
right	string	Option right (options, warrants, bull bear certificates), PUT/CALL
strike	string	Strike price
multiplier	double	Multiplier, quantity per contract (options, warrants, bull bear certificates, futures)

Example Request

QuoteContractResponse response = client.execute(QuoteContractRequest.newRequest("00700", SecType.WAR, "20211223"));
if (response.isSuccess()) {
  System.out.println(response.getContractItems());
} else {
  System.out.println("response error:" + response.getMessage());
}

Example Response

{
	"code": 0,
	"data": [{
		"items": [{
			"currency": "HKD",
			"exchange": "SEHK",
			"expiry": "20211223",
			"market": "HK",
			"multiplier": 50000.0,
			"name": "[email protected]",
			"right": "CALL",
			"secType": "WAR",
			"strike": "719.38",
			"symbol": "13745"
		}, {
			"currency": "HKD",
			"exchange": "SEHK",
			"expiry": "20211223",
			"market": "HK",
			"multiplier": 5000.0,
			"name": "[email protected]",
			"right": "CALL",
			"secType": "WAR",
			"strike": "900.5",
			"symbol": "13680"
		}],
		"secType": "WAR",
		"symbol": "00700"
	}],
	"message": "success",
	"sign": "bxQhZiWMsT9aSVTNtt2SXVeeh5w8Ypug/6UY3nL9N7LFKB1YxBVpQoKDJ4JloFojyb/CPCGT0fCXTxboDBTZvnA4stjbh1YqbNlz2lNqmHhpxYUKMdE+w2hFKVvoYMlMPCmsY5NqSQ3S/fsSzZrJyxBRPzZ+d+0qb7VSYw9yhho=",
	"success": true,
	"timestamp": 1637686550209
}