Get Contract

Contract Introduction

A contract refers to the trading object or underlying asset (such as a stock or an option), which is uniformly formulated by the exchange. For example, when purchasing Tiger Brokers' stock, it can be uniquely identified through the symbol "TIGR" and market information (market=US, US market). Through contract information, we can uniquely determine an underlying asset when placing orders or obtaining market data. Common contracts include stock contracts, option contracts, futures contracts, etc.

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 (China 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 code), expiry (option expiration date), strike (option strike price), right (option direction).
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);

Fund

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

Get Single Contract Information

Corresponding Request Class: ContractRequest

Description

Get contract information required for trading. Note that global accounts and integrated 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 code, e.g.: 00700/AAPL
sec_type	string	Yes	STK/OPT/FUT
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 code, 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 direction, CALL or PUT
strike	24.0	Options specific, option strike price
multiplier	0.0	Options and futures specific, multiplier, quantity per lot
lotSize	100	Stock quantity per lot
minTick	0.001	Minimum tick size
tickSizes	`[{"begin":"0","end":"1", "tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity", "tickSize":0.01,"type":"OPEN"}]`	Minimum tick size price ranges, when order price is within the begin and end range, it must meet tickSize requirements. begin: left price range, end: right price range, type: range type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN (open interval/left open right closed/closed interval/left closed right open), tickSize: minimum price unit
marginable	true	Whether margin trading is available
shortable	true	Whether short selling is allowed
longInitialMargin	1	Long initial margin
longMaintenanceMargin	1	Long maintenance margin
shortInitialMargin	0.35	Short initial margin ratio
shortMaintenanceMargin	0.3	Short maintenance margin ratio (has value for integrated accounts, no value for global account contracts)
shortableCount	10000000	Available short selling quantity
shortFeeRate	0	Short selling fee rate
tradingClass	LRN	Contract trading class name
tradeable	true	Whether tradeable (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 (integrated/demo accounts only)

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 = ContractRequest.newRequest(contractModel);
ContractResponse contractResponse = client.execute(contractRequest);
System.out.println("return warrant contract:" + JSONObject.toJSONString(contractResponse));

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

Return Example

{
    "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

Corresponding Request Class: ContractsRequest

Description

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

⚠️
CAUTION The batch contracts returned by Integrated 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
currency	string	No	USD/HKD/CNH
secret_key	string	No	Trader secret key, for institutional users only

Return

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 direction, 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
tickSizes	`[{"begin":"0","end":"1", "tickSize":1.0E-4,"type":"CLOSED"},{"begin":"1","end":"Infinity", "tickSize":0.01,"type":"OPEN"}]`	Stocks only, minimum tick size price ranges, when order price is within begin and end range, must satisfy tickSize requirement. begin: left price range, end: right price range, type: range type OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN (open interval/left open right closed/closed interval/left closed right open), tickSize: minimum price unit
marginable	true	Whether margin trading is available
shortable	true	Whether short selling is available
longInitialMargin	1	Long initial margin
longMaintenanceMargin	1	Long maintenance margin
shortInitialMargin	0.35	Short initial margin ratio
shortMaintenanceMargin	0.3	Short maintenance margin ratio (has value for integrated accounts, no value for global account contracts)
shortableCount	10000000	Available short quantity
shortFeeRate	0	Short selling fee rate
tradingClass	LRN	Contract trading class name
tradeable	true	Whether tradeable (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 supports overnight trading (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));

Return Example

{
    "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

Corresponding 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

Return Result:

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 direction (options, warrants, bull bear certificates), PUT/CALL
strike	string	Strike price
multiplier	double	Multiplier, quantity per contract (options, warrants, bull bear certificates, futures)

Request Example:

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());
}

Response Example:

{
	"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
}