InstrumentDefinitionRequest

Note

For a more in depth documentation, you should check the comments from the protobuf file.

Purpose

Warning

Before sending an InstrumentDefinitionRequest, the client should send a ProductInfoRequest and wait for its response.

Note

The server limits the number of instruments that it can send in one response. If the client asks for more instruments than the maximum limit of 10,000, the server will generate an error.

This is used to get contract details of an instrument or multiple instruments.

The client can also subscribe to async definitions, this is usefull when the client wants to be aware of newly added contracts or when the current contracts get updated. The client can subscribe to the asynchronous definitions by setting the subscribe_to_async_def bool, to true.

When subscribe_to_async_def is set to true, the server saves the criteria from the InstrumentDefinitionRequest and when a new contract is added or updated, that matches the criteria from one of the InstrumentDefinitionRequest sent by the client, the server will send the definition as an asynchronous message.

To unsubscribe from these async definitions, the client must disconnect.

Request example

const payload = {
  request_id: 7,
  instrument_definition:
  {
    instrument_ids: [
      1,
      2
    ],
    product_ids: [
      3,
      4
    ],
    product_type_ids: [
      5,
      6
    ],
    product_family_ids: [
      7,
      8
    ],
    exchange_ids: [
      9,
      10
    ]
  }
};

Responses

Valid

Note

The most important field from an InstrumentDefinition is the instrument_id, which should be used to get quotes for that specific intrument.

The server will respond with a InstrumentDefinitionResponse that will contain one or more InstrumentDefinitionResponseRecords. The InstrumentDefinitionResponseRecord can contain one of the following fields:

InstrumentDefinition - containing a valid instrument definition;

InstrumentDefinitionError - containing an error regarding an invalid instrument id/product id, etc.

Error

The server will respond with an ErrorMessageResponse with the following error message:

ProductInfoRequest required before asking for instrument definitions. - If the client didn’t send a ProductInfoRequest before.

You do not have the necessary rights to get any products. - If the client doesn’t have the necessary rights to get any products.

Insufficient information to identify an instrument. - If the client sent a request that is empty or contains empty repeated fields.

The maximum number of instrument definitions that can be sent simultaneously is X and you asked for Y. - If the client asked for Y instruments, but the max number of instrument definitions the server allows at once, is X.

You asked for more instrument definitions than the maximum number of definitions that can be sent simultaneously (X). Please provide more filters to minimize the number of definitions generated. - If the client provided filters that generated more instrument definitions than the server allows to be sent at once.