Get Contract

About 6 min

What is a Contract

We refer to what is being traded in an order as a "contract". The specs of a specific contract are set by a exchange, and are used to identify a specific asset in global markets, across the exchanges. This information, and the information required to trade a certain contract, are embedded in the Contract object.

A typical contract object includes the following elements:

Symbol: The ticker symbol of the stock/equity. The symbol of most U.S stocks only contains letters, HK stocks and Chinese A-Shares uses numbers as symbols of stocks. For example, the symbol of Tiger Brokers (NASDAQ) is TIGR
Security type: Common Security types includes STK(Stocks), OPT(Options), FUT(Futures) and CASH(Forex). For example, the Security type of Tiger Brokers (NASDAQ) is TIGR
Currency type: common currencies include USD (US dollar), HKD (Hong Kong dollar).
Exchange: The code of the exchange in which the requested asset is traded. Contracts with Security typ of STK does not require this data field, as the orders will be routed automatically to a designated exchange, However, for futures, this field is necessary

Most stocks, CFDs, indexes or Forex can be identified by those four elements. However, some contracts like Futures and Options has more attributes in their corresponding contract objects

Stocks

ContractItem contract = new ContractItem();
contract.setSymbol("TIGR");
contract.setSecType("STK");
contract.setCurrency("USD"); //Optional，default is USD
contract.setMarket("US"); //Optional, including US(United States) , HK (HongKong), CN(A-Shares), etc. US by default

Options

Tiger Securities's API support 2 option contract format:

One is the four-factor approach, including symbol, expiry, strike, right.
The other is the standard OCC option contract format, fixed length of 21 bits. contains four parts：
- The code of the relevant stock or ETP, e.g. (AAPL), is fixed at six characters, with the missing digits filled by spaces
- Option expiration date, 6 digits, format: yymmdd
- Option type,including P or C, for put or call
- Option exercise price, the value of the price x 1000, fixed 8 digits, the first few digits are filled by 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);

Get Contract

Description

Get contract information. Use this method with global account and prime account, ContractItem will have different data fields. Use the same account to get contract information and to place orders.

Argument

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

Argument	Type	optional	Description
account	string	Yes	Account id: 13810712
symbol	string	Yes	Ticker symbol of the stock/equity, example: 'AAPL'
sec_type	string	Yes	Security type, example: STK
currency	string	No	USD/HKD/CNH
expiry	string	No	Options expiration date, format: 'yyyyMMdd', example: '20220121'
strike	double	No	Options strike price. Required for options
right	string	No	CALL/PUT. Required for options
exchange	string	No	Exchange code (U.S stocks SMART, Shanghai-Hong Kong Stock Connect-SEHK, A-Shares-SEHKNTL，Shenzhen-Hong Kong Stock Connect SEHKSZSE)
secret_key	string	No	secret key for the trader of institutions, please config in client_config, ignore if you are a indiviual user

Response

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

Use ContractResponse.getItem() to access returned data. This method will return a ContractItem object, wherecom.tigerbrokers.stock.openapi.client.https.domain.contract.item.ContractItemhas the following attributes:

Name	Example	Description
identifier	CL2109/AAPL	Asset identifier
name	K12 INC	name of the asset
contractId	1	IB contract id
symbol	LRN	stock ticker symbol
secType	STK	STK/OPT/WAR/IOPT, STK by default
expiry	20171117	Contract expiration date
contractMonth	201804	Delivery month
strike	24.0	strike price for options
right	PUT	Put/Call for options
type	ES	futures type
multiplier	0.0	multiplier for options, futures, CBBCs
exchange	NYSE	Exchange code
primaryExchange	NYSE	Primary exchange
market	US	market /US/HK/CN
currency	USD	USD/HKD/CNH
localSymbol	1033	used in HK market to identify warrant and CBBC
tradingClass	LRN	Trading class
minTick	0.001	minimum ticksize
tickSizes	[ { "begin":"0", "end":"1", "tickSize":0.0001, "type":"CLOSED" }, { "begin":"1", "end":"Infinity", "tickSize":0.01, "type":"OPEN" } ]	only support stocks，type： OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN, tickSize：minTick for different price ranges
marginable	true	if able to purchase with financing
longInitialMargin	1	Long initial margin
longMaintenanceMargin	1	Long maintenance margin
shortInitialMargin	0.35	Short intial margin
shortMaintenanceMargin	0.3	Short maintenance margin（prime account only )
shortable	true	available for shorting
shortableCount	10000000	amount of shares you can short
shortFeeRate	0	short fee rate
tradeable	true	if available for trading（STK type only）
closeOnly	false	Is it only possible to close the position
continuous	false	Futures only, if the contract is continuous
lastTradingDate	2019-01-01	Futures only, last trading date
firstNoticeDate	2019-01-01	Futures only, first notice date
lastBiddingCloseTime	0	Futures only, last bidding date
isEtf	boolean	is ETF
etfLeverage	integer	ETF leverage
discountedDayInitialMargin	3069.0	Exclusive to futures, intraday preferential initial margin ratio
discountedDayMaintenanceMargin	2790.0	Exclusive to futures, intraday preferential maintenance margin ratio
discountedTimeZoneCode	CDT	Exclusive to futures, intraday preferential time and time zone
discountedStartAt	17:30:00	Exclusive to futures, start time of discount within the day
discountedEndAt	14:30:00	Exclusive to futures, the end time of the discount within the day

Example

// init trade 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 options 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 future 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));

Response 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 Contracts

Description

Get multiple contracts. Use this method with global account and prime account, ContractItem will have different data fields. Use the same account to get contract information and to place orders.

CAUTION

There is no field related to margin in the contract returned by the prime account

Argument

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

Argument	Type	optional	Description
account	string	Yes	Account id: 13810712
symbols	`List<string>`	Yes	Ticker symbol of the stock/equity, example: 'AAPL'. Maximum 50 per request
sec_type	string	Yes	Security type, example: STK/FUT
currency	string	No	USD/HKD/CNH
secret_key	string	No	secret key for the trader of institutions, please config in client_config, ignore if you are a indiviual user

Response

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

Use ContractsResponse.getItems() to access returned data. This method will return ContractItem objects, wherecom.tigerbrokers.stock.openapi.client.https.domain.contract.item.ContractItem has the following attributes:

Name	Example	Description
identifier	CL2109/AAPL	Asset identifier
name	K12 INC	name of the asset
contractId	1	IB contract id
symbol	LRN	stock ticker symbol
secType	STK	STK/OPT/WAR/IOPT, STK by default
expiry	20171117	Contract expiration date
contractMonth	201804	Delivery month
strike	24.0	strike price for options
right	PUT	Put/Call for options
type	ES	futures type
multiplier	0.0	multiplier for options, futures, CBBCs
exchange	NYSE	Exchange code
primaryExchange	NYSE	Primary exchange
market	US	market /US/HK/CN
currency	USD	USD/HKD/CNH
localSymbol	1033	used in HK market to identify warrant and CBBC
tradingClass	LRN	Trading class
minTick	0.001	minimum ticksize
tickSizes	[ { "begin":"0", "end":"1", "tickSize":0.0001, "type":"CLOSED" }, { "begin":"1", "end":"Infinity", "tickSize":0.01, "type":"OPEN" } ]	only support stocks，type： OPEN/OPEN_CLOSED/CLOSED/CLOSED_OPEN, tickSize：minTick for different price ranges
marginable	true	if able to purchase with financing
longInitialMargin	1	Long initial margin
longMaintenanceMargin	1	Long maintenance margin
shortInitialMargin	0.35	Short initial margin
shortMaintenanceMargin	0.3	Short maintenance margin（prime account only )
shortable	true	available for shorting
shortableCount	10000000	amount of shares you can short
shortFeeRate	0	short fee rate
tradeable	true	if available for trading（STK type only）
closeOnly	false	Is it only possible to close the position
continuous	false	Futures only, if the contract is continuous
lastTradingDate	2019-01-01	Futures only, last trading date
firstNoticeDate	2019-01-01	Futures only, first notice date
lastBiddingCloseTime	0	Futures only, last bidding date
isEtf	false	is ETF
etfLeverage	0	ETF leverage

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

Response 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 Contract for Options and Warrants

Description

Get stock‘s Warrant and CBBC contracts

Argument

Argument	Type	Required	Description
symbols	string	Yes	symbol of the underlying asset
sec_type	string	Yes	Security types, possible values are: OPT-options/ WAR-warrants/ IOPT-CBBCs)
expiry	String	No	Expiration date(yyyyMMdd), must have a value for OPT type
lang	string	No	Language: zh_CN,zh_TW,en_US, en_US by default

Response：com.tigerbrokers.stock.openapi.client.https.response.quote.QuoteContractResponse

Use QuoteContractResponse.getContractItems() to access returned data. This method will return a list of QuoteContractItem object, wherecom.tigerbrokers.stock.openapi.client.https.domain.quote.item.QuoteContractItem has the following attributes:

Name	Type	Description
symbol	string	Stock ticker symbol
name	string	Contract name
exchange	string	Exchange where the contract is traded
market	string	Market where the contract is traded
secType	string	Security type
currency	string	Currency
expiry	string	Expiration date for options, warrants, CBBC, futures, e.g. 20171117
right	string	PUT/CALL for options, warrants, futures and CBBCs
strike	string	Strike price
multiplier	double	Multiplier for options, warrants, futures and CBBCs

Response 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": "MSTENCT@EC2112B.C",
			"right": "CALL",
			"secType": "WAR",
			"strike": "719.38",
			"symbol": "13745"
		}, {
			"currency": "HKD",
			"exchange": "SEHK",
			"expiry": "20211223",
			"market": "HK",
			"multiplier": 5000.0,
			"name": "JPTENCT@EC2112A.C",
			"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
}

Get Contract

# What is a Contract

# Get Contract

# Get Multiple Contracts

# Get Contract for Options and Warrants

What is a Contract

Get Contract

Get Multiple Contracts

Get Contract for Options and Warrants