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 XYZ Holding's stock, it can be uniquely identified through the symbol "XYZX" 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, etc.

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

Symbol: Generally, US stocks, UK stocks and other contract codes are English letters
Security Type: Common contract types include: STK (stock), OPT (option)
Currency: Common currencies include USD (US Dollar)
Exchange: STK type contracts generally don't use the exchange field as orders are automatically routed

Some contracts (such as options) 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("XYZX");
contract.setSecType("STK");
contract.setCurrency("USD"); //Optional, defaults to USD when placing orders
contract.setMarket("US"); //Optional, Defaults to US when placing orders

Option

TradeUP 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 "XYZX", 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("XYZX");
contract.setSecType("OPT");
contract.setCurrency("USD");
contract.setExpiry("20180821");
contract.setStrike(30D);
contract.setRight("CALL");
contract.setMultiplier(100.0D);
contract.setMarket("US"); //Optional

Get Single Contract Information

Corresponding Request Class: ContractRequest

Description

Get contract information required for trading. Note that live 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.: XYZX
sec_type	string	Yes	STK/OPT
currency	string	No	USD
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)
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/XYZX	Unique identifier, stock identifier is the same as symbol, option is a 21-character identifier
symbol	LRN	Stock code, option contract symbol is the corresponding underlying asset code
secType	STK	STK (stock)/OPT (option), default STK
name	K12 INC	Stock name
currency	USD	USD
exchange	NYSE	Stock exchange
primaryExchange	NYSE	Stock listing exchange
market	US	Market, e.g.: US
expiry	20171117	Options specific, option expiration date
right	PUT	Options specific, option direction, CALL or PUT
strike	24.0	Options specific, option strike price
multiplier	0.0	Options 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 live accounts)
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)
isEtf	false	Whether it's an ETF
etfLeverage	3	ETF leverage multiple, only exists when the contract is an ETF
supportOvernightTrading	true	Whether overnight trading is supported (US stocks only)
supportFractionalShare	true	Whether fractional share trading is supported (prime/paper trading accounts only)

Example

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

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

// Get option contract
ContractModel model = new ContractModel("XYZX", 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));

Return Example

{
    "code":0,
    "data":{
        "closeOnly":false,
        "currency":"USD",
        "etf":false,
        "identifier":"XYZX",
        "localSymbol":"XYZX",
        "longInitialMargin":0.3,
        "longMaintenanceMargin":0.25,
        "marginable":true,
        "market":"US",
        "multiplier":1,
        "name":"XYZ Holding",
        "secType":"STK",
        "shortInitialMargin":0.35,
        "shortMaintenanceMargin":0.3,
        "symbol":"XYZX",
        "tickSizes":[
            {
                "begin":"0",
                "end":"1",
                "tickSize":0.0001,
                "type":"CLOSED"
            },
            {
                "begin":"1",
                "end":"Infinity",
                "tickSize":0.01,
                "type":"OPEN"
            }
        ],
        "tradeable":true,
        "tradingClass":"XYZX"
    },
    "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. Note that live 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 live 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.: XYZX, max 50 per request
sec_type	string	Yes	STK
currency	string	No	USD
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	XYZX	Unique identifier, stock identifier same as symbol, options use 21-character identifier
symbol	XYZX	Stock symbol, for options contracts the symbol is the underlying asset symbol
secType	STK	STK stock/OPT option, default STK
name	XYZ Holding	Stock name
currency	USD	USD
exchange	NYSE	Stock exchange
primaryExchange	NYSE	Primary listing exchange
market	US	Market, US
expiry	20171117	Options only, expiration date for options
right	PUT	Options only, option direction, CALL or PUT
strike	24.0	Options only, option strike price
multiplier	0.0	Options 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 live accounts)
shortableCount	10000000	Available short quantity
shortFeeRate	0	Short selling fee rate
tradingClass	LRN	Contract trading class name
tradeable	true	Whether tradeable (STK only)
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("XYZX");
symbols.add("YZX");
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":"XYZX",
            "localSymbol":"XYZX",
            "market":"US",
            "multiplier":1,
            "name":"XYZ Holding",
            "secType":"STK",
            "symbol":"XYZX",
            "tickSizes":[
                {
                    "begin":"0",
                    "end":"1",
                    "tickSize":0.0001,
                    "type":"CLOSED"
                },
                {
                    "begin":"1",
                    "end":"Infinity",
                    "tickSize":0.01,
                    "type":"OPEN"
                }
            ],
            "tradeable":true,
            "tradingClass":"XYZX"
        },
        {
            "currency":"USD",
            "etf":false,
            "identifier":"YZX",
            "localSymbol":"YZX",
            "market":"US",
            "multiplier":1,
            "name":"YZX Inc",
            "secType":"STK",
            "symbol":"YZX",
            "tickSizes":[
                {
                    "begin":"0",
                    "end":"1",
                    "tickSize":0.0001,
                    "type":"CLOSED"
                },
                {
                    "begin":"1",
                    "end":"Infinity",
                    "tickSize":0.01,
                    "type":"OPEN"
                }
            ],
            "tradeable":true,
            "tradingClass":"YZX"
        }
    ],
    "message":"success",
    "sign":"Bv8H6BBfKOrMOhdJAanE0hwJiJAoKOk55/cTkJIVSmw9ENd2nmbeBI3cesqRgPq8bJ2dUBrYr+cqLVG65meXwbaFYyEenWlNyigl02IuJVoETgChuSoX1SZBTnafoVivCIj3neWG8BFdhaTNNXfBMbeSYf01+BqI6xYEc6KQxKc=",
    "success":true,
    "timestamp":1684912317872
}

Get Options 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)
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), 20171117
right	string	Option direction (options), PUT/CALL
strike	string	Strike price
multiplier	double	Multiplier, quantity per contract (options)

Request Example:

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

Response Example:

{
	"code": 0,
	"data": [{
		"items": [{
			"currency": "USD",
			"exchange": "NYSE",
			"expiry": "20211223",
			"market": "US",
			"multiplier": 100.0,
			"name": "XYZX  211223P00180000",
			"right": "CALL",
			"secType": "OPT",
			"strike": "180.0",
			"symbol": "XYZX"
		}, {
			"currency": "USD",
			"exchange": "NYSE",
			"expiry": "20211223",
			"market": "US",
			"multiplier": 100.0,
			"name": "XYZX  211223P00190000",
			"right": "CALL",
			"secType": "OPT",
			"strike": "190.0",
			"symbol": "XYZX"
		}],
		"secType": "OPT",
		"symbol": "XYZX"
	}],
	"message": "success",
	"sign": "bxQhZiWMsT9aSVTNtt2SXVeeh5w8Ypug/6UY3nL9N7LFKB1YxBVpQoKDJ4JloFojyb/CPCGT0fCXTxboDBTZvnA4stjbh1YqbNlz2lNqmHhpxYUKMdE+w2hFKVvoYMlMPCmsY5NqSQ3S/fsSzZrJyxBRPzZ+d+0qb7VSYw9yhho=",
	"success": true,
	"timestamp": 1637686550209
}