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; USD is an illustrative value
contract.setMarket("US"); // Optional; examples include US, HK, CN, SG, and AU

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

Gets one contract required for trading. See the routing table under “Get Multiple Contract Information” for account-path field differences.

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	Currency, for example USD, HKD, or 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
contractId	123456	Contract ID.
ibCode	CL	Futures contract code.
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.
name	K12 INC	Stock name
localSymbol	1033	Global account specific, used for identifying warrants and CBBCs in Hong Kong stocks
currency	USD	Currency, for example 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; for example, this may be 1 for a US stock or 100 for an A-share.
minTick	0.001	Nullable `Double` minimum tick size. A stock contract may not have one fixed value; 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)
closeOnly	false	Whether the contract is position-closing only. When true, orders may reduce or close an existing position but may not open a position.
continuous	false	Futures specific, whether it's a continuous contract
type	CL	Futures specific, underlying futures type
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; returned only for ETF contracts
discountedDayInitialMargin	0.3	Intraday discounted initial margin ratio; for example, 0.3 means 30%.
discountedDayMaintenanceMargin	0.25	Intraday discounted maintenance margin ratio; for example, 0.25 means 25%.
discountedTimeZoneCode	CDT	Intraday discount time zone.
discountedStartAt	17:30:00	Intraday discount start time.
discountedEndAt	14:30:00	Intraday discount end time.
supportOvernightTrading	true	Whether overnight trading is supported (US stocks only)
supportFractionalShare	true	Whether fractional-share trading is supported.

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
}

Rate Limit

The base rate limit is 60 requests/min.

Get Multiple Contract Information

Request class: ContractsRequest

Description

Get contract information required for trading. Supports STK, FUT, and CC. Routing and field behavior are:

Request	Path and field behavior
`sec_type=FUT`	Every account uses the futures-contract path
Global `STK` / `CC`	Uses the Global contract path; this path does not populate `shortMaintenanceMargin`
Prime/Paper `STK` / `CC`	Uses the Prime/Paper contract path; margin fields, `shortableCount`, `closeOnly`, fractional-share support, and related fields are mapped when supplied downstream

⚠️
NOTE
For Prime and paper accounts, currency and exchange do not narrow batch contract results. Use the returned contract attributes to distinguish contracts that share a symbol.

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	Currency, for example USD, HKD, or CNH
exchange	string	No	Exchange; Prime/Paper does not use it to narrow batch results
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
contractId	123456	Contract ID.
ibCode	CL	Futures contract code.
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.
name	K12 INC	Stock name
localSymbol	1033	Global account only, HK stocks used to identify warrants and bull bear certificates
currency	USD	Currency, for example 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
lotSize	100	Shares per lot.
minTick	0.001	Nullable `Double` minimum tick size. A stock contract may not have one fixed value; 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)
closeOnly	false	Whether the contract is position-closing only. When true, orders may reduce or close an existing position but may not open a position.
continuous	false	Futures only, whether continuous contract
type	CL	Futures only, underlying futures type
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; returned only for ETF contracts
supportOvernightTrading	true	Whether overnight trading is supported (US stocks only)
discountedDayInitialMargin	0.3	Intraday discounted initial margin ratio; for example, 0.3 means 30%.
discountedDayMaintenanceMargin	0.25	Intraday discounted maintenance margin ratio; for example, 0.25 means 25%.
discountedTimeZoneCode	CDT	Intraday discount time zone.
discountedStartAt	17:30:00	Intraday discount start time.
discountedEndAt	14:30:00	Intraday discount end time.
supportFractionalShare	true	Whether fractional-share trading is supported.

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
}

Rate Limit

The base rate limit is 60 requests/min.

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
}

Rate Limit

The base rate limit is 60 requests/min.