options

func (*CSVService) Chain ¶

func (s *CSVService) Chain(ctx context.Context, symbol string, opts ...ChainOption) (*response.CSVResponse, error)

Chain fetches the options chain for an underlying stock symbol as CSV. See Service.Chain for parameter and validation details.

func (*CSVService) Expirations ¶

func (s *CSVService) Expirations(ctx context.Context, symbol string, opts ...ExpirationOption) (*response.CSVResponse, error)

Expirations fetches the expiration dates for an underlying stock symbol as CSV. See Service.Expirations for parameter and validation details.

func (*CSVService) Quote ¶

func (s *CSVService) Quote(ctx context.Context, optionSymbol string, opts ...QuoteOption) (*response.CSVResponse, error)

Quote fetches a single option contract's quote as CSV. See Service.Quote for parameter and validation details.

func (*CSVService) Quotes ¶

func (s *CSVService) Quotes(ctx context.Context, optionSymbols []string, opts ...QuoteOption) (map[string]*response.CSVResponse, error)

Quotes fetches quotes for multiple option contracts as CSV, one request per symbol (mirroring Service.Quotes' own per-symbol fan-out), and returns a map keyed by option symbol instead of merging into one result — each contract's CSV text is independent, unlike candle chunks of the same time series. The first error cancels the remaining in-flight requests (ADR-014).

The options apply to every symbol in the batch, so a historical window is expressible for a watchlist and not only for a single contract — the same reason Service.Quotes takes a slice plus options rather than a variadic symbol list.

Unlike Service.Quotes, there is no NoData omission: every requested symbol gets an entry in the map holding whatever the API returned for it (see ADR-018 — the CSV/HTML facets have no NoData concept).

func (Expirations) String ¶

func (e Expirations) String() string

String returns a summary of the expirations list.

func (*OptionQuote) CalcMid ¶

func (c *OptionQuote) CalcMid() float64

CalcMid calculates the bid-ask midpoint locally from the Bid and Ask fields, unlike the Mid field, which is the midpoint reported by the API.

func (*OptionQuote) Spread ¶

func (c *OptionQuote) Spread() float64

Spread returns the bid-ask spread (Ask minus Bid).

func (OptionQuote) String ¶

func (c OptionQuote) String() string

String returns a summary of the option contract.

func (OptionsChain) String ¶

func (oc OptionsChain) String() string

String returns a summary of the options chain.

func (*Service) AsCSV ¶

func (s *Service) AsCSV() *CSVService

AsCSV returns the CSV facet of this service.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	csv, err := client.Options.AsCSV().Chain(context.Background(), "AAPL")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(csv.CSV())
}

Output:

func (*Service) Chain ¶

func (s *Service) Chain(ctx context.Context, symbol string, opts ...ChainOption) (*OptionsChain, *response.Response, error)

Chain fetches the options chain for an underlying stock symbol, returning a real-time or historical OptionsChain with one OptionQuote per contract. The symbol is required; all other parameters are optional and supplied as ChainOption values.

Without an expiry filter the API returns only the front-month (nearest) expiration, not the whole chain. To fetch every listed expiration, pass options.AllExpirations() to WithExpiry — and expect a much larger response, billed accordingly.

The two groups of mutually-exclusive API parameters are each expressed as a single sealed-union option, so the API's silently-conflicting combinations cannot be written: WithStrike selects contracts by strike or delta, and WithExpiry selects expirations by date, dte, month, year, or an expiration range. WithChainDate requests a historical snapshot as of a day and is independent. Free filters such as WithSide, WithStrikeLimit, WithRange, the bid/ask and liquidity filters, and the expiration-type filters combine freely. See the ChainOption constructors in this package for the complete set.

Option values that cannot be encoded in the type system (a strike or delta out of range, a month outside 1..12, a malformed date range) are rejected with a sdkerrors.ValidationError before any request is made.

A symbol the API does not recognize is reported as a [NotFoundError]. A valid request that simply matches no contracts is not an error: Chain returns an empty chain (safe to range), a nil error, and a response whose NoData field is true. See the "Missing Data and Unknown Symbols" section of the marketdata package documentation.

API documentation: https://www.marketdata.app/docs/api/options/chain

Example:

chain, _, err := client.Options.Chain(ctx, "AAPL",
    options.WithExpiry(options.OnExpiration(time.Now().AddDate(0, 1, 0))),
    options.WithStrike(options.StrikeRange(150, 160)),
)

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
	"github.com/MarketDataApp/sdk-go/v2/marketdata/options"
)

func main() {
	client, err := marketdata.NewClient() // token from MARKETDATA_TOKEN
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	expiration := time.Now().AddDate(0, 1, 0)
	chain, _, err := client.Options.Chain(context.Background(), "AAPL",
		options.WithExpiry(options.OnExpiration(expiration)),
		options.WithStrike(options.StrikeRange(150, 200)),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(chain)
}

Output:

func (*Service) Expirations ¶

func (s *Service) Expirations(ctx context.Context, symbol string, opts ...ExpirationOption) (*Expirations, *response.Response, error)

Expirations fetches the expiration dates with listed option contracts for an underlying stock symbol. The returned Expirations carries the dates in Eastern time plus the server's response-level update time, mirroring the API response. The symbol is required. The optional ExpirationOption values WithExpirationStrike (limit to expirations offering a given strike) and WithExpirationDate (list the expirations that were available on a past date) refine the request.

A request with no listed expirations is not an error: Expirations returns an empty result (Dates is safe to range), a nil error, and a response whose NoData field is true. Note that options/expirations answers an unknown symbol with an unmarked 404 too, so an unrecognized symbol is reported the same way rather than as a [NotFoundError] — the API sends nothing that tells the two apart.

API documentation: https://www.marketdata.app/docs/api/options/expirations

Example:

exps, _, err := client.Options.Expirations(ctx, "AAPL")
if err != nil {
    log.Fatal(err)
}
if exps != nil {
    for _, d := range exps.Dates { ... }
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	expirations, _, err := client.Options.Expirations(context.Background(), "AAPL")
	if err != nil {
		log.Fatal(err)
	}
	if expirations != nil {
		for _, exp := range expirations.Dates {
			fmt.Println(exp.Format("2006-01-02"))
		}
	}
}

Output:

func (*Service) GetChain ¶

func (s *Service) GetChain(symbol string, opts ...ChainOption) (*OptionsChain, error)

GetChain is a convenience wrapper for Service.Chain that uses context.Background() and discards the response metadata. It accepts the same required symbol and optional ChainOption filters, and shares Chain's no-data behavior: when the API returns 404, GetChain returns a nil chain and a nil error.

package main

import (
	"fmt"
	"log"
	"time"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
	"github.com/MarketDataApp/sdk-go/v2/marketdata/options"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	chain, err := client.Options.GetChain("AAPL",
		options.WithExpiry(options.OnExpiration(time.Now().AddDate(0, 1, 0))),
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(chain)
}

Output:

func (*Service) GetExpirations ¶

func (s *Service) GetExpirations(symbol string, opts ...ExpirationOption) (*Expirations, error)

GetExpirations is a convenience wrapper for Service.Expirations that uses context.Background() and discards the response metadata. When the API returns 404, GetExpirations returns nil and a nil error.

func (*Service) GetLookup ¶

func (s *Service) GetLookup(underlying string, expiration time.Time, strike float64, optionType OptionType) (string, error)

GetLookup is a convenience wrapper for Service.Lookup that uses context.Background() and discards the response metadata. When the API cannot resolve the contract (404), GetLookup returns an empty string and a nil error.

func (*Service) GetLookupQuery ¶

func (s *Service) GetLookupQuery(query string) (string, error)

GetLookupQuery is a convenience wrapper for Service.LookupQuery that uses context.Background() and discards the response metadata. When the API cannot resolve the contract (404), GetLookupQuery returns an empty string and a nil error.

func (*Service) GetQuote ¶

func (s *Service) GetQuote(optionSymbol string, opts ...QuoteOption) (*OptionQuote, error)

GetQuote is a convenience wrapper for Service.Quote that uses context.Background() and discards the response metadata. When the API returns 404, GetQuote returns a nil quote and a nil error.

func (*Service) GetQuoteHistory ¶

func (s *Service) GetQuoteHistory(optionSymbol string, opts ...QuoteOption) ([]OptionQuote, error)

GetQuoteHistory is a convenience wrapper for Service.QuoteHistory that uses context.Background() and discards the response metadata. When the API returns 404, GetQuoteHistory returns a nil slice and a nil error.

func (*Service) GetQuotes ¶

func (s *Service) GetQuotes(optionSymbols []string, opts ...QuoteOption) ([]OptionQuote, error)

GetQuotes is a convenience wrapper for Service.Quotes that uses context.Background() and discards the response metadata. Like Quotes, it fetches the symbols concurrently and omits symbols with no data from the result.

func (*Service) GetQuotesBySymbol ¶

func (s *Service) GetQuotesBySymbol(optionSymbols []string, opts ...QuoteOption) (map[string]*OptionQuote, error)

GetQuotesBySymbol is a convenience wrapper for Service.QuotesBySymbol that uses context.Background() and discards the response metadata. Like QuotesBySymbol, it returns one entry per requested symbol, with a nil value where the API had no data.

func (*Service) Lookup ¶

func (s *Service) Lookup(ctx context.Context, underlying string, expiration time.Time, strike float64, optionType OptionType) (string, *response.Response, error)

Lookup resolves an option contract to its OCC option symbol. It takes the underlying stock symbol, the expiration date, the strike price, and an OptionType (Call or Put), all of which are required, and returns the OCC symbol string (for example "AAPL250117C00150000") suitable for use with Service.Quote and Service.Quotes.

All four arguments are validated before any request is made: a missing underlying, a zero expiration, a strike at or below zero, or an option type other than Call or Put is rejected with a sdkerrors.ValidationError. Without those checks an unset argument would be interpolated into the query verbatim, and the resulting 404 would be reported as no-data — making a malformed call indistinguishable from a contract that does not exist.

If the API cannot resolve the contract (HTTP 404), Lookup returns an empty string, a response whose NoData field is true, and a nil error.

API documentation: https://www.marketdata.app/docs/api/options/lookup

Example:

symbol, _, err := client.Options.Lookup(ctx, "AAPL", expDate, 150.0, options.Call)

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
	"github.com/MarketDataApp/sdk-go/v2/marketdata/options"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	expiration := time.Now().AddDate(0, 1, 0)
	symbol, _, err := client.Options.Lookup(context.Background(), "AAPL", expiration, 150, options.Call)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(symbol)
}

Output:

func (*Service) LookupQuery ¶

func (s *Service) LookupQuery(ctx context.Context, query string) (string, *response.Response, error)

LookupQuery resolves an option contract to its OCC option symbol from a free-form, human-readable description, exactly as the endpoint accepts it — for example "AAPL 7/26/23 $200 Call". The query is required and is sent as a single URL path segment; the endpoint does its own parsing, so the accepted phrasings are the API's, not the SDK's.

Service.Lookup is the typed alternative for the common case where the underlying, expiration, strike, and type are already known separately; it validates those four and assembles the query. Use LookupQuery when the description arrives as text — from a user, a spreadsheet cell, or a broker export — and cannot be decomposed first.

If the API cannot resolve the contract (HTTP 404), LookupQuery returns an empty string, a response whose NoData field is true, and a nil error.

API documentation: https://www.marketdata.app/docs/api/options/lookup

Example:

symbol, _, err := client.Options.LookupQuery(ctx, "AAPL 7/26/23 $200 Call")

func (*Service) Quote ¶

func (s *Service) Quote(ctx context.Context, optionSymbol string, opts ...QuoteOption) (*OptionQuote, *response.Response, error)

Quote fetches a real-time or historical OptionQuote for a single option contract, identified by its OCC option symbol (for example "AAPL250117C00150000"). The option symbol is required; if it is not known, Service.Lookup can resolve one from the underlying, expiration, strike, and type. The optional WithOptionQuoteWindow carries a single OptionQuoteWindow value — options.QuoteOnDate(t), options.QuoteRange(from, to), options.QuoteLastN(n), or options.QuoteLastNUntil(n, to) — to request a historical quote; because it is one value, the API's mutually-exclusive date, from/to, and countback parameters cannot be combined (the API returns HTTP 400 when both a date and a from/to are sent).

A malformed quote window (a zero date, a from after its to, or a countback at or below zero) is rejected with a sdkerrors.ValidationError before any request is made.

Quote returns exactly one quote, as its name says. A window that selects several days — a range, or a countback greater than one — makes the API return one row per day, of which Quote keeps only the first; use Service.QuoteHistory to receive all of them.

An OCC symbol matching no contract is reported as a [NotFoundError]. If the contract exists but the API has no data for the requested window, Quote returns a nil quote, a response whose NoData field is true, and a nil error — an OptionQuote has no meaningful empty value, so callers must check for nil. See the "Missing Data and Unknown Symbols" section of the marketdata package documentation.

API documentation: https://www.marketdata.app/docs/api/options/quotes

Example:

quote, _, err := client.Options.Quote(ctx, "AAPL230120C00150000")

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	quote, _, err := client.Options.Quote(context.Background(), "AAPL250117C00150000")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(quote)
}

Output:

func (*Service) QuoteHistory ¶

func (s *Service) QuoteHistory(ctx context.Context, optionSymbol string, opts ...QuoteOption) ([]OptionQuote, *response.Response, error)

QuoteHistory fetches every quote the API returns for a single option contract, as a slice in the order the API sent them. It takes the same arguments and options as Service.Quote.

It exists because a historical window can select more than one quote: a QuoteRange spanning several days, or a QuoteLastN/QuoteLastNUntil countback, returns one row per day. Quote returns only the first of those rows, since its contract is a single quote; QuoteHistory returns all of them. For a current quote, or a window that selects a single day, the two are equivalent and QuoteHistory returns a one-element slice.

An OCC symbol matching no contract is reported as a [NotFoundError]. If the contract exists but the window selects nothing, QuoteHistory returns a nil slice (safe to range), a response whose NoData field is true, and a nil error.

API documentation: https://www.marketdata.app/docs/api/options/quotes

Example:

quotes, _, err := client.Options.QuoteHistory(ctx, "AAPL260821C00300000",
    options.WithOptionQuoteWindow(options.QuoteLastN(5)))

func (*Service) Quotes ¶

func (s *Service) Quotes(ctx context.Context, optionSymbols []string, opts ...QuoteOption) ([]OptionQuote, *response.Response, error)

Quotes fetches quotes for multiple option contracts identified by their OCC option symbols. At least one symbol is required. The optional QuoteOption values are the same ones Service.Quote accepts and apply to every symbol in the batch, so WithOptionQuoteWindow requests the same historical window across the whole set. The method fans out one concurrent Service.Quote request per symbol; the goroutines draw slots from the client's shared concurrency pool (at most 50 in-flight requests per client across all services), so passing many symbols will not exceed that limit. The results are merged into a single slice in the order the symbols were given.

Symbols the API has no data for, and symbols naming a contract it does not recognize, are both omitted from the result rather than producing an error, so the returned slice may be shorter than the input and gives no indication of which symbols were dropped; use Service.QuotesBySymbol when that distinction matters. This is where the batch methods differ from Service.Quote, which reports an unknown contract as a [NotFoundError]: in a batch a bad symbol is information about that symbol, not a failure of the whole request. If any request fails with a real error, Quotes returns that error and no quotes. The returned response corresponds to one of the individual requests, not an aggregate.

API documentation: https://www.marketdata.app/docs/api/options/quotes

Example:

quotes, _, err := client.Options.Quotes(ctx, []string{"AAPL230120C00150000", "AAPL230120P00150000"})

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/MarketDataApp/sdk-go/v2/marketdata"
)

func main() {
	client, err := marketdata.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = client.Close() }()

	quotes, _, err := client.Options.Quotes(context.Background(), []string{
		"AAPL250117C00150000",
		"AAPL250117P00150000",
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, q := range quotes {
		fmt.Println(q)
	}
}

Output:

func (*Service) QuotesBySymbol ¶

func (s *Service) QuotesBySymbol(ctx context.Context, optionSymbols []string, opts ...QuoteOption) (map[string]*OptionQuote, *response.Response, error)

QuotesBySymbol fetches quotes for multiple option contracts and returns them keyed by the OCC option symbol that was requested. At least one symbol is required. It fetches exactly like Service.Quotes — one concurrent request per symbol, drawn from the client's shared 50-slot pool, with the first hard error cancelling its siblings.

It accepts the same QuoteOption values as Service.Quote, applied to every symbol.

The difference is what happens to contracts the API has no data for, or does not recognize at all. Quotes omits them, so the returned slice is simply shorter than the input and the caller cannot tell which symbols were dropped. QuotesBySymbol returns one map entry for every requested symbol, with a nil value for those, so a missing contract is distinguishable from one that was never asked for. Repeated symbols collapse into a single entry. Neither method reports an unknown contract as an error the way Service.Quote does — see Quotes for why.

If any request fails with a real error, QuotesBySymbol returns that error and no quotes. The returned response corresponds to one of the individual requests, not an aggregate.

API documentation: https://www.marketdata.app/docs/api/options/quotes

Example:

quotes, _, err := client.Options.QuotesBySymbol(ctx, []string{"AAPL230120C00150000", "AAPL230120P00150000"})
for symbol, q := range quotes {
    if q == nil {
        log.Printf("%s: no data", symbol)
        continue
    }
    ...
}