MLink TickerBasket

The TickerBasket feature allows clients to group multiple tickers into named baskets for more efficient querying through the MLink REST and MLink WebSockets APIs.

Overview

MLink TickerBasket enables clients to:

• Group multiple tickers into named baskets
• Query data for all tickers in a basket using a single parameter
• Achieve faster query performance compared to WHERE clause filtering
• Scale efficiently from small (10 tickers) to large (200+ tickers) baskets

To use TickerBasket, clients must:

1. Secure an MLink API Key
2. Connect to an MLink/WebSocket or REST server
3. Define baskets using TickerItemDef messages
4. Query using the basket number parameter

TickerBasket Workflow

Key Messages

Message	Source	Description
TickerItemDef	Client	Define tickers in a basket

Workflow

1. Client Sends TickerItemDef Objects:

   • Send multiple TickerItemDef objects to the MLink server
   • Each object represents a ticker with key details (ticker symbol, asset type, ticker source)
   • Include a basketNumber field to group tickers into a single basket
   • Include a userName field to identify the basket owner

2. Post Basket Definitions:

   • Post using: POST /rest/proto?cmd=postmsgs&postaction=I
   • Each TickerItemDef adds one ticker to the specified basket
   • Baskets can contain varying numbers of tickers (10-200+), each being its own object.
   • Baskets are user-specific: the same basket number can exist for different users

3. Query Using TickerBasket Parameter:

   • Use the tickerbasket parameter with the basket number
   • Example: GET /rest/proto?cmd=getmsgs&msgtype=OptionNbboQuote&tickerbasket=0000-0000-0000-0001
   • Server processes the query for all tickers in the basket

API Reference

TickerItemDef Message

The TickerItemDef message is used to define individual tickers within a basket.

Primary Key Fields:

• ticker (TickerKey): The ticker symbol, asset type, and ticker source
• basketNumber (HexLong): The basket identifier (can be formatted with or without dashes, e.g., 1 or 0000-0000-0000-0001)
• userName: The username that owns this basket - your username

Body Fields:

• clientFirm (ClientFirm): The client firm associated withyour userName - not mandatory
• timestamp (Timestamp): Timestamp - not mandatory

Example TickerItemDef POST with Objects as Body:

POST /rest/json?cmd=postmsgs&postaction=I
{
  "header": {
    "mTyp": "TickerItemDef"
  },
  "message": {
    "pkey": {
      "ticker": {
        "at": "EQT",
        "ts": "NMS",
        "tk": "AAPL"
      },
      "basketNumber": "0000-1111-2222-3333",
      "userName": "YOUR_USERNAME"
    },
    "clientFirm": "YOUR_CLIENT_FIRM",
    "timestamp": "2025-01-01 12:00:00.000000"
  }
}

Query Parameter

Parameter Name: tickerbasket

Format: HexLong (supports both 1 and 0000-0000-0000-0001 formats)

Usage: Add to any getmsgs or getcount query

Examples:

GET /rest/json?cmd=getmsgs&msgtype=StockBookQuote&tickerbasket=1

GET /rest/json?cmd=getmsgs&msgtype=OptionNbboQuote&tickerbasket=1&l=5000

GET /rest/json?cmd=getcount&msgtype=LiveImpliedQuote&tickerbasket=0000-0000-0000-0001

Supported Message Types

TickerBasket filtering works with message types that have one of the following key types in their schema (primary key OR body fields):

• TickerKey in Primary Key: Messages like StockBookQuote, StockPrint
• OptionKey in Primary Key: Messages like OptionNbboQuote, LiveImpliedQuote
• ExpiryKey in Primary Key: Messages like LiveSurfaceCurve

Features

• Performance Optimization: Faster query performance compared to WHERE clause filtering, especially for queries involving multiple tickers
• Scalability: Support for baskets ranging from 10 to 200+ tickers
• Flexible Querying: Use basket number as a single parameter instead of complex WHERE clauses
• Named Baskets: Organize tickers into logical groups with unique basket numbers
• Combined Filtering: Can be combined with other query parameters like where, limit, etc.

Error Handling

The server returns specific error messages for common issues:

• Basket Not Found: TickerBasket: basket {basketNumber} not found for user {userName}
• Empty Basket: TickerBasket: basket {basketNumber} is empty
• Unsupported Message Type: TickerBasket: message type {messageType} does not support ticker basket filtering
• Invalid Format: invld param: tickerbasket ({value})

Best Practices

1. Basket Size: Keep baskets to a reasonable size (10-200 tickers) for optimal performance
2. Combining Filters: TickerBasket works well with other filters, but complex WHERE clauses may negate performance benefits

Example Use Cases

Example 1: Equity Quote Basket

# Define basket with 3 equity tickers
POST /rest/json?cmd=postmsgs&postaction=I
[Multiple TickerItemDef messages with basketNumber=1]

# Query all quotes for basket
GET /rest/json?cmd=getmsgs&msgtype=StockBookQuote&tickerbasket=1

Example 2: Option Quote Basket

# Define basket with option underliers (Ticker)
POST /rest/json?cmd=postmsgs&postaction=I
[Multiple TickerItemDef messages with basketNumber=2]

# Query all option quotes for basket
GET /rest/json?cmd=getmsgs&msgtype=OptionNbboQuote&tickerbasket=2&l=5000

Example 3: Combined with WHERE Clause

# Query options in basket with additional filtering
GET /rest/json?cmd=getmsgs&msgtype=OptionNbboQuote&tickerbasket=1&where=okey.tk:eq:2025-01-17