Find option-capable underlyings, open a chain view, walk its expiries and fetch the call/put contracts you care about. Includes the OCC symbol helper for venues that use that format.

Searching underlyings

When you already know the symbol ("SPY", "AAPL"), go straight to opening a chain. For a picker UI or a scan, SearchUnderlyingsAsync queries every connected options-capable venue and merges the matches:

Searchusing SabrTrader.Pipeline.Options;

IReadOnlyList<OptionUnderlying> hits = await options.SearchUnderlyingsAsync("apple");
foreach (OptionUnderlying u in hits)
    Log($"{u.Symbol}  {u.Description}");        // e.g. "AAPL  Apple Inc."

Each hit is a small record: Symbol, Description and an UnderlyingId (the serving venue's id for it). Pass Symbol to OpenChainAsync. An empty list means nothing matched or no venue is available; the reader answers "no data" with an empty result.

Opening a chain

OpenChainAsync resolves the underlying symbol across the connected venues and returns an IOptionChainView, or null when no venue serves options for that symbol. The view is your handle for everything else in this chapter: contract listings, quote subscriptions and snapshots all go through it.

OpenIOptionChainView? view = await options.OpenChainAsync("SPY");
if (view is null) return;                        // no connected venue serves SPY options

// The listing fetched at open time:
OptionChain chain = view.Chain;
Log($"{chain.UnderlyingSymbol}: {chain.Expiries.Count} expiries, " +
    $"{chain.Contracts.Count} contracts pre-loaded");

What the listing contains

A chain can span thousands of contracts, so the listing has two speeds: Expiries is always the complete, ascending expiry list, while Contracts holds only the expiries fetched so far (at open time, the venue's default nearest expiries). You page in more per expiry as needed.

Fetching more expiries

GetContractsAsync fetches the contracts of exactly the expiries you pass (the result again carries the full expiry list). Fetch what your computation needs rather than the whole board:

Per-expiry fetch// The first two expiries at least 30 days out:
var today = DateOnly.FromDateTime(DateTime.UtcNow);
var wanted = view.Chain.Expiries
    .Where(e => e.DayNumber - today.DayNumber >= 30)
    .Take(2)
    .ToList();

OptionChain chain = await view.GetContractsAsync(wanted);

// Call/put per strike for one expiry:
var board = chain.Contracts
    .Where(c => c.Expiry == wanted[0])
    .OrderBy(c => c.Strike)
    .ThenBy(c => c.Right);         // Call before Put per strike

Anatomy of a contract

View lifecycle

A view holds venue-side state, so dispose it when you are done. Disposing tears down every quote subscription created through it. A view lives only as long as its venue: when the serving venue disconnects, subsequent calls on the view fail. The recovery pattern is the availability loop from the chapter overview: watch AvailabilityChanged, dispose the dead view, reopen.

Lifecycleprivate IOptionChainView? _view;

private async Task OpenAsync()
{
    _view?.Dispose();                            // release the previous view first
    _view = await _options!.OpenChainAsync("SPY");
}

public override void OnDispose()
{
    _view?.Dispose();
    _view = null;
}

The OCC symbol helper

OccOptionSymbol handles the OCC/OSI concatenated symbol form used by US retail broker APIs: {root}{yyMMdd}{C|P}{strike×1000, 8 digits}, e.g. AAPL240119C00190000 = AAPL 2024-01-19 190 Call. It formats and parses:

OccOptionSymbolusing SabrTrader.Pipeline.Options;

// Format:
var occ = new OccOptionSymbol("AAPL", new DateOnly(2026, 12, 18), IsCall: true, Strike: 150m);
string wire = occ.ToSymbol();                    // "AAPL261218C00150000"

// Strict parse: a plain equity ticker is never accepted.
if (OccOptionSymbol.TryParse(candidate, out var parsed))
    Log($"{parsed.Root} {parsed.Expiry:dd MMM yy} {parsed.Strike} {(parsed.IsCall ? "C" : "P")}");

// Just the class, from EITHER wire form: concatenated OCC or the 21-char space-padded OSI form.
string? cls = OccOptionSymbol.RootOf("AAPL  240119C00190000");   // "AAPL"; null when neither form