Get Contract

About 7 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
  • 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 Forexs can be identify 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.Symbol ="TIGR";
contract.SecType ="STK";
contract.Currency ="USD"; //Optional, USD by default
contract.Market = "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

    options identifier

ContractItem contract = new ContractItem();
contract.Symbol ="AAPL";
contract.SecType ="OPT";
contract.Currency ="USD";
contract.Expiry="20180821";
contract.Strike = 30;
contract.Right ="CALL";
contract.Multiplier =100.0;
contract.Market = "US"; // Optional

Futures

ContractItem contract = new ContractItem();
contract.Symbol ="CL1901";
contract.SecType ="FUT";
contract.Exchange ="SGX";
contract.Currency ="USD";
contract.Expiry="20190328";
contract.Multiplier=1.0;

Get Contract

Description

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

Argument

ArgumentTypeoptionalDesription
accountstringYesAccount id: 13810712
symbolstringYesTicker symbol of the stock/equity, example: 'AAPL'
sec_typestringYesSecurtiy type, example: STK
currencystringNoUSD/HKD/CNH
expirystringNoOptions expiration date, format: 'yyyyMMdd', example: '20220121'
strikedoubleNoOptions strike price. Required for options
rightstringNoCALL/PUT. Required for options
exchangestringNoExchange code (U.S stocks SMART, Shanghai-Hong Kong Stock Connect-SEHK, A-Shares-SEHKNTL，Shenzhen-Hong Kong Stock Connect SEHKSZSE)
secret_keystringNoecret key for the trader of institutions, please config in client_config, ignore if you are a indiviual user

ResponseTigerOpenAPI.Trade.Response.ContractResponsesourceopen in new window

Structured as follows：

namespace TigerOpenAPI.Trade.Response
{
  public class ContractResponse : TigerResponse
  {
    [JsonProperty(PropertyName = "data")]
    public ContractItem Data { get; set; }
  }
}

Use ContractResponse.Data to access returned data. This method will return a ContractItem object, whereTigerOpenAPI.Trade.Response.ContractItem has the following attributes:

NameExampleDescription
identifierCL2109/AAPLAsset identifier
nameK12 INCname of the asset
contractId1IB contract id
symbolLRNstock ticker symbol
secTypeSTKSTK/OPT/WAR/IOPT, STK by default
expiry20171117Contract expiration date
contractMonth201804Delivery month
strike24.0strike price for options
rightPUTPut/Call for options
typeESfutures type
multiplier0.0multiplier for options, futures, CBBCs
exchangeNYSEExchange code
primaryExchangeNYSEPrimary exchange
marketUSmarket /US/HK/CN
currencyUSDUSD/HKD/CNH
localSymbol1033used in HK market to identify warrant and CBBC
tradingClassLRNTrading class
minTick0.001minimum 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
marginabletrueif able to purchase with financing
longInitialMargin1Long initial margin
longMaintenanceMargin1Long maintenance margin
shortInitialMargin0.35Short intial margin
shortMaintenanceMargin0.3Short maintenance margin（prime account only )
shortabletrueavailable for shorting
shortableCount10000000amount of shares you can short
shortFeeRate0short fee rate
tradeabletrueif available for trading（STK type only）
closeOnlyfalseIs it only possible to close the position
continuousfalseFutures only, if the contract is continuous
lastTradingDate2019-01-01Futures only, last trading date
firstNoticeDate2019-01-01Futures only, first notice date
lastBiddingCloseTime0Futures only, last bidding date
isEtffalseis ETF
etfLeverage3ETF leverage
discountedDayInitialMargin3069.0Futures only, Intraday initial margin discount
discountedDayMaintenanceMargin2790.0Futures only, Intraday maintenance margin discount
discountedTimeZoneCodeCDTFutures only, Intraday margin discount period time zone
discountedStartAt17:30:00Futures only, Intraday margin discount start time
discountedEndAt14:30:00Futures only, Intraday margin discount end time

Example

// init trade client
TradeClient tradeClient = new TradeClient(config);

  static async Task<ContractResponse?> GetContractAsync(TradeClient tradeClient)
  {
    // get stock contract
    TigerRequest<ContractResponse> request = new TigerRequest<ContractResponse>()
    {
      ApiMethodName = TradeApiService.CONTRACT,
      ModelValue = new ContractModel()
      {
        Symbol = "AAPL"
      }
    };
    ContractResponse? response = await tradeClient.ExecuteAsync(request);
    ApiLogger.Info("response:" + JsonConvert.SerializeObject(response, TigerClient.JsonSet));

    // get options contract
    request = new TigerRequest<ContractResponse>()
    {
      ApiMethodName = TradeApiService.CONTRACT,
      ModelValue = new ContractModel()
      {
        SecType = SecType.OPT.ToString(),
        Symbol = "AAPL",
        Strike = 150.0,
        Expiry = "20230616",
        Right = Right.CALL.ToString(),
        Currency = Currency.USD.ToString()
      }
    };
    response = await tradeClient.ExecuteAsync(request);
    ApiLogger.Info("options response:" + JsonConvert.SerializeObject(response, TigerClient.JsonSet));

    // get warrant contract
    request = new TigerRequest<ContractResponse>()
    {
      ApiMethodName = TradeApiService.CONTRACT,
      ModelValue = new ContractModel()
      {
        SecType = SecType.WAR.ToString(),
        Symbol = "29263",
        Strike = 351.567,
        Expiry = "20230330",
        Right = Right.CALL.ToString()
      }
    };
    response = await tradeClient.ExecuteAsync(request);
    ApiLogger.Info("warrants response:" + JsonConvert.SerializeObject(response, TigerClient.JsonSet));

    // get futures contract
    request = new TigerRequest<ContractResponse>()
    {
      ApiMethodName = TradeApiService.CONTRACT,
      ModelValue = new ContractModel()
      {
        SecType = SecType.FUT.ToString(),
        Symbol = "JPY2306"
      }
    };
    response = await tradeClient.ExecuteAsync(request);
    ApiLogger.Info("futures response:" + JsonConvert.SerializeObject(response, TigerClient.JsonSet));

    return response;
  }

Response Example

response:{"data":{"identifier":"AAPL","symbol":"AAPL","secType":"STK","multiplier":1.0,"market":"US","currency":"USD","localSymbol":"AAPL","tradingClass":"AAPL","name":"Apple","tradeable":true,"marginable":true,"shortInitialMargin":0.35,"shortMaintenanceMargin":0.3,"longInitialMargin":0.3,"longMaintenanceMargin":0.25,"tickSizes":[{"begin":"0","end":"1","type":"CLOSED","tickSize":0.0001},{"begin":"1","end":"Infinity","type":"OPEN","tickSize":0.01}]},"message":"success","timestamp":1678248447856,"sign":"R6uVWPOfoYR7C+/U4mw8pYgsfLaLHyL8UJ5Bgr4GII6JYBYYvz3OBYYwZDTGmTIjjdEeSm8llgojY6VMiEwIVXPqbr+C3HvLM8JpztbCe4gvnFXlfHSVMDoNMariVIF2IdcET2eNqJANVJXDFAJa0jZWMaNjmBZwcllgnEIvH8k="} 

options response:{"data":{"identifier":"AAPL  230616C00150000","symbol":"AAPL","secType":"OPT","expiry":"20230616","strike":150.0,"right":"CALL","multiplier":1.0,"market":"US","currency":"USD","localSymbol":"AAPL","tradingClass":"AAPL","name":"Apple","tradeable":true,"shortInitialMargin":1.0,"shortMaintenanceMargin":1.0,"longInitialMargin":1.0,"longMaintenanceMargin":1.0,"tickSizes":[{"begin":"0","end":"Infinity","type":"CLOSED_OPEN","tickSize":0.01}]},"message":"success","timestamp":1678248435184,"sign":"KUvm5w4MW0o4x/UhaKUudo+/ToOoGSIUvaS5/O1OpKLpszMMarEqUAPBMpo/q1X5cbkan1yH5jDpaL55jCwM4vM2fvh1vvBme1M+BgWfHNk27TSSB6vTtTp37T6P1FXM0GPKDZmmyq7cRHeLDefyvd5W8ha0lXAHma4tB8u5Vj0="} 

warrants response:{"data":{"identifier":"29263 230330C00351567","symbol":"29263","secType":"WAR","expiry":"20230330","strike":351.567,"right":"CALL","multiplier":10000.0,"market":"HK","currency":"HKD","localSymbol":"29263","tradingClass":"29263","name":"CTTENCT@EC2303D.C","tradeable":true,"shortInitialMargin":1.0,"shortMaintenanceMargin":1.0,"longInitialMargin":1.0,"longMaintenanceMargin":1.0,"tickSizes":[{"begin":"0","end":"0.25","type":"CLOSED","tickSize":0.001},{"begin":"0.25","end":"0.5","type":"OPEN_CLOSED","tickSize":0.005},{"begin":"0.5","end":"10","type":"OPEN_CLOSED","tickSize":0.01},{"begin":"10","end":"20","type":"OPEN_CLOSED","tickSize":0.02},{"begin":"20","end":"100","type":"OPEN_CLOSED","tickSize":0.05},{"begin":"100","end":"200","type":"OPEN_CLOSED","tickSize":0.1},{"begin":"200","end":"500","type":"OPEN_CLOSED","tickSize":0.2},{"begin":"500","end":"1000","type":"OPEN_CLOSED","tickSize":0.5},{"begin":"1000","end":"2000","type":"OPEN_CLOSED","tickSize":1.0},{"begin":"2000","end":"5000","type":"OPEN_CLOSED","tickSize":2.0},{"begin":"5000","end":"Infinity","type":"OPEN","tickSize":5.0}]},"message":"success","timestamp":1678248448209,"sign":"KUvm5w4MW0o4x/UhaKUudo+/ToOoGSIUvaS5/O1OpKLpszMMarEqUAPBMpo/q1X5cbkan1yH5jDpaL55jCwM4vM2fvh1vvBme1M+BgWfHNk27TSSB6vTtTp37T6P1FXM0GPKDZmmyq7cRHeLDefyvd5W8ha0lXAHma4tB8u5Vj0="}
futures response:{"data":{"identifier":"JPY2306","symbol":"JPY2306","secType":"FUT","multiplier":1.0,"market":"US","currency":"USD","localSymbol":"JPY2306","tradingClass":"JPY2306","name":"Japanese Yen - Jun 2023","tradeable":true,"marginable":true,"shortInitialMargin":4092.0,"shortMaintenanceMargin":3720.0,"longInitialMargin":4092.0,"longMaintenanceMargin":3720.0,"tickSizes":[{"begin":"0","end":"Infinity","type":"CLOSED_OPEN","tickSize":5E-07}],"discountedDayInitialMargin":3069.0,"discountedDayMaintenanceMargin":2790.0,"discountedTimeZoneCode":"CDT","discountedStartAt":"17:30:00","discountedEndAt":"14:30:00"},"message":"success","timestamp":1683181339383,"sign":"bORW/gW79+1+woZIiEyAB+SdMBbfdTdBJQ3u2jqm+1IeE73ke2y2/bELBQA17U4H01wKndZLA+3hLB2RtJg6MOmsIDCnwMdMuTX3atuAqk5enG/HlTsz/sqqNRSBua//rocgrpv94+huJixSbfq0PoUA/+m9Txu2sJ05ICzN6Zo="}

Get Multiple Contracts

Description

Get multiple contracts. Use this method with gobal 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

ArgumentTypeoptionalDesription
accountstringYesAccount id: 13810712
symbolsList<string>YesTicker symbol of the stock/equity, example: 'AAPL'. Maximum 50 per request
sec_typestringYesSecurtiy type, example: STK/FUT
currencystringNoUSD/HKD/CNH
secret_keystringNoecret key for the trader of institutions, please config in client_config, ignore if you are a indiviual user

ResponseTigerOpenAPI.Trade.Response.ContractsResponsesourceopen in new window

Structured as follows：

namespace TigerOpenAPI.Trade.Response
{
  public class ContractsResponse : TigerResponse
  {
    [JsonProperty(PropertyName = "data")]
    public Dictionary<string, List<ContractItem>> Data { get; set; }
  }
}

Use ContractsResponse.Data to access returned data. This method will return ContractItem objects, whereTigerOpenAPI.Trade.Response.ContractItem has the following attributes:

NameExampleDescription
identifierCL2109/AAPLAsset identifier
nameK12 INCname of the asset
contractId1IB contract id
symbolLRNstock ticker symbol
secTypeSTKSTK/OPT/WAR/IOPT, STK by default
expiry20171117Contract expiration date
contractMonth201804Delivery month
strike24.0strike price for options
rightPUTPut/Call for options
typeESfutures type
multiplier0.0multiplier for options, futures, CBBCs
exchangeNYSEExchange code
primaryExchangeNYSEPrimary exchange
marketUSmarket /US/HK/CN
currencyUSDUSD/HKD/CNH
localSymbol1033used in HK market to identify warrant and CBBC
tradingClassLRNTrading class
minTick0.001minimum 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
marginabletrueif able to purchase with financing
longInitialMargin1Long initial margin
longMaintenanceMargin1Long maintenance margin
shortInitialMargin0.35Short intial margin
shortMaintenanceMargin0.3Short maintenance margin（prime account only )
shortabletrueavailable for shorting
shortableCount10000000amount of shares you can short
shortFeeRate0short fee rate
tradeabletrueif available for trading（STK type only）
closeOnlyfalseIs it only possible to close the position
continuousfalseFutures only, if the contract is continuous
lastTradingDate2019-01-01Futures only, last trading date
firstNoticeDate2019-01-01Futures only, first notice date
lastBiddingCloseTime0Futures only, last bidding date
isEtffalseis ETF
etfLeverage0ETF leverage

Example

  static async Task<ContractsResponse?> GetContractsAsync(TradeClient tradeClient)
  {
    TigerRequest<ContractsResponse> request = new TigerRequest<ContractsResponse>()
    {
      ApiMethodName = TradeApiService.CONTRACTS,
      ModelValue = new ContractsModel()
      {
        SecType = SecType.STK.ToString(),
        Symbols = new List<string> { "AAPL", "TSLA" },
        Account = "13810712"
      }
    };
    return await tradeClient.ExecuteAsync(request);
  }

Response Example

{
    "data":{
        "items":[
            {
                "contractId":0,
                "identifier":"AAPL",
                "symbol":"AAPL",
                "secType":"STK",
                "expiry":null,
                "contractMonth":null,
                "strike":"NaN",
                "right":null,
                "multiplier":1,
                "exchange":null,
                "market":"US",
                "primaryExchange":null,
                "currency":"USD",
                "localSymbol":"AAPL",
                "tradingClass":"AAPL",
                "name":"Apple Inc",
                "tradeable":true,
                "closeOnly":false,
                "minTick":"NaN",
                "marginable":false,
                "shortInitialMargin":"NaN",
                "shortMaintenanceMargin":"NaN",
                "shortFeeRate":"NaN",
                "shortable":false,
                "shortableCount":0,
                "longInitialMargin":"NaN",
                "longMaintenanceMargin":"NaN",
                "lastTradingDate":null,
                "firstNoticeDate":null,
                "lastBiddingCloseTime":0,
                "continuous":false,
                "type":null,
                "ibCode":null,
                "tickSizes":[
                    {
                        "begin":"0",
                        "end":"1",
                        "type":"CLOSED",
                        "tickSize":0.0001
                    },
                    {
                        "begin":"1",
                        "end":"Infinity",
                        "type":"OPEN",
                        "tickSize":0.01
                    }
                ],
                "discountedDayInitialMargin":"NaN",
                "discountedDayMaintenanceMargin":"NaN",
                "discountedTimeZoneCode":null,
                "discountedStartAt":null,
                "discountedEndAt":null,
                "isEtf":false,
                "etfLeverage":0
            },
            {
                "contractId":0,
                "identifier":"TSLA",
                "symbol":"TSLA",
                "secType":"STK",
                "expiry":null,
                "contractMonth":null,
                "strike":"NaN",
                "right":null,
                "multiplier":1,
                "exchange":null,
                "market":"US",
                "primaryExchange":null,
                "currency":"USD",
                "localSymbol":"TSLA",
                "tradingClass":"TSLA",
                "name":"Tesla Motors",
                "tradeable":true,
                "closeOnly":false,
                "minTick":"NaN",
                "marginable":false,
                "shortInitialMargin":"NaN",
                "shortMaintenanceMargin":"NaN",
                "shortFeeRate":"NaN",
                "shortable":false,
                "shortableCount":0,
                "longInitialMargin":"NaN",
                "longMaintenanceMargin":"NaN",
                "lastTradingDate":null,
                "firstNoticeDate":null,
                "lastBiddingCloseTime":0,
                "continuous":false,
                "type":null,
                "ibCode":null,
                "tickSizes":[
                    {
                        "begin":"0",
                        "end":"1",
                        "type":"CLOSED",
                        "tickSize":0.0001
                    },
                    {
                        "begin":"1",
                        "end":"Infinity",
                        "type":"OPEN",
                        "tickSize":0.01
                    }
                ],
                "discountedDayInitialMargin":"NaN",
                "discountedDayMaintenanceMargin":"NaN",
                "discountedTimeZoneCode":null,
                "discountedStartAt":null,
                "discountedEndAt":null,
                "isEtf":false,
                "etfLeverage":0
            }
        ]
    },
    "code":0,
    "message":"success",
    "timestamp":1684915702228,
    "sign":"DveGmN84KAMpKv7Ud7XqE/ZpNqO82JYxboPeuLfZwHIXdA2Q4OOe8x/kYVhAKIL+tjg/4if71LxPpB7o3dd1I1VZf3LgusRsShTfHrAZOetiv9kW5Y1rpTeiAEaeez4hwPiBUnxxXsK9d/2+9MtwnqhDvrazj3VBstmc7DZ+RBE="
}

Get Contract for Options and Warrants

Description

Get stock‘s Warrant and CBBC contracts

Argument

ArgumentTypeRequiredDescription
symbolsstringYessymbol of the underlying asset
sec_typestringYesSecurity types, possible values are: OPT-options/ WAR-warrants/ IOPT-CBBCs)
expiryStringNoExpiration date(yyyyMMdd), must have a value for OPT type
langstringNoLanguage: zh_CN,zh_TW,en_US, en_US by default

Response：TigerOpenAPI.Quote.Response.QuoteContractResponsesourceopen in new window

Structured as follows：

namespace TigerOpenAPI.Quote.Response
{
  public class QuoteContractResponse : TigerResponse
  {
    [JsonProperty(PropertyName = "data")]
    public QuoteContractItem Data { get; set; }
  }
}

Use QuoteContractResponse.Data to access returned data. This method will return a QuoteContractItem object, whereTigerOpenAPI.Quote.Response.QuoteContract has the following attributes:

NameTypeDescription
symbolstringStock ticker symbol
namestringContract name
exchangestringExchange where the contract is traded
marketstringMarket where the contract is traded
secTypestringSecurity type
currencystringCurrency
expirystringExpiration date for options, warrants, CBBC, futures, e.g. 20171117
rightstringPUT/CALL for options, warrants, futures and CBBCs
strikestringStrike price
multiplierdoubleMultiplier for options, warrants, futures and CBBCs

Response Example:

  static async Task<QuoteContractResponse?> GetQuoteContractAsync(QuoteClient quoteClient)
  {
    TigerRequest<QuoteContractResponse> request = new TigerRequest<QuoteContractResponse>()
    {
      ApiMethodName = QuoteApiService.QUOTE_CONTRACT,
      ModelValue = new QuoteContractsModel()
      {
        Symbol = "00700",
        SecType = SecType.WAR,
        Expiry = "20211223"
      }
    };
    return await quoteClient.ExecuteAsync(request);
  }

Response Example：

{
	"code": 0,
	"data": [{
		"symbol": "00700",
		"secType": "WAR",
		"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"
		}]
	}],
	"message": "success",
	"sign": "bxQhZiWMsT9aSVTNtt2SXVeeh5w8Ypug/6UY3nL9N7LFKB1YxBVpQoKDJ4JloFojyb/CPCGT0fCXTxboDBTZvnA4stjbh1YqbNlz2lNqmHhpxYUKMdE+w2hFKVvoYMlMPCmsY5NqSQ3S/fsSzZrJyxBRPzZ+d+0qb7VSYw9yhho=",
	"success": true,
	"timestamp": 1637686550209
}
Last update: