@type catalog_access() :: :enumerable | :query_only

How the venue's catalogue can be reached.

:enumerable — get_symbols/1 returns the whole list. :query_only — there is no list-everything call and get_symbols/1 requires a search term.

@type catalog_size() :: :small | :large | :vast | :unknown

Roughly how many instruments the venue lists.

A class rather than a count, because the count changes daily and the decision it informs does not. It exists so a consumer can tell that re-pulling one venue's catalogue on a timer is fine and another's is not — the difference between a thousand instruments and millions is a different strategy, not a different number.

@type ceiling() ::
  %{
    :limit => non_neg_integer(),
    :per_ms => pos_integer(),
    optional(:burst) => pos_integer(),
    optional(:scope) => ceiling_scope()
  }
  | nil

Requests per interval, as the venue publishes it.

There are two of these on a venue with a better authenticated path, and which applies depends on what the caller supplied. Carrying one number means a package holding credentials meters itself against the public limit and leaves most of its budget unused.

:burst is optional because most venues do not publish one

A GCRA limiter takes three parameters — rate, interval, and how far a caller may run ahead of the rate before being made to wait. This type carried only the first two, so a venue that publishes its burst depth had nowhere to declare it and the package had to hardcode the number beside the declaration, which is precisely the drift this struct exists to prevent.

Gemini publishes one: "we offer a burst rate of five additional requests that are queued". It is the first venue in the family to do so, and it found this gap.

Optional, not required, because a venue that does not publish a burst depth must not be made to invent one — and nil here means "not published", which a consumer can tell apart from a declared burst of zero.

max_leverage: :per_account, for venues that margin without a single ceiling

max_leverage began as Decimal.t() | nil, on the reasonable-looking assumption that a venue which margins has a leverage. Schwab does not, and the assumption cost more than it looked: nil with supports_margin: true raises, so the only ways to ship were to declare supports_margin: false, which is false, or to invent a multiplier — the substitution this whole family exists to refuse.

A Schwab MarginAccount carries five different buying powers — overall, non-marginable, day-trading, option and stock — which are not multiples of one another, so no one of them is "the" leverage. A CashAccount at the same venue carries none of them, so any number reported for one would be invented. The Reg-T fields, regTCall and sma, are call and credit amounts rather than ratios. Equities margin is not crypto margin, and Kraken's 5x does not carry over.

So :per_account is a positive statement: the venue margins, and the ceiling belongs to the account rather than to the venue — read it from the balance response. nil still raises when supports_margin: true, because nil means "nobody said", and the error names :per_account so a venue author discovers the option instead of inventing a number.

@type ceiling_scope() :: :credential | :account | :application

What a ceiling is counted against.

:credential is the default and was the only case while every venue was crypto: one key, one budget. The others exist because Schwab's is neither.

• :credential — per API key. One key, one bucket.
• :account — per account, so a host running several accounts through one registration shares nothing between them and cannot infer one budget from another.
• :application — per registered application, shared across every credential and account it issues. A ceiling a host cannot raise by adding keys.

This changes what a caller must do, which is why it is declared rather than left implicit: a limiter keyed by credential silently over-permits a venue that counts by account.

@type credential_benefit() :: :no_difference | :higher_ceiling | :required

What credentials buy on this venue.

A boolean could not say this. The old field answered "does this venue reject public calls without credentials", which has two states, while the real question has three — and the middle one is the common case:

• :no_difference — public data is served, and credentials change nothing about it.
• :higher_ceiling — public data is served, but the authenticated path has a materially higher rate limit. A package holding credentials should be using it.
• :required — public data is not served at all without credentials.

@type data_kind() ::
  :quotes
  | :top_of_book
  | :order_book
  | :trades
  | :candles
  | :orders
  | :fills
  | :balances
  | :positions

A kind of data a subscription can deliver — normalised, so a consumer never learns a venue's channel vocabulary.

A list-valued capability is a UNION across asset classes, not an intersection

streamable, authenticated_streamable and historical_timeframes are flat lists with no asset-class dimension, and until 2026-09-10 nothing said what that flatness means for a venue serving more than one class. Two readings are available and they are opposites: "every path serves this" or "some path serves this". A venue author had to guess.

The rule is the union: a value belongs in the list if the venue serves it on any path this package reaches. Both multi-asset venues in the family had already chosen that reading independently, which is how the ambiguity stayed invisible — dp_exchange_webull's Rest.wide_timeframes/0 says so in its own doc, and dp_exchange_schwab's Rest.timeframes/0 calls its list "canonical candle widths this venue serves".

What makes a union honest rather than an overstatement is the second half of the rule: the per-call path must FAIL CLOSED for a combination it does not serve. dp_exchange_webull is the worked example — historical_timeframes includes 1w and 1M because the equity, option and futures bars serve them, and get_historical_prices/5 answers {:error, {:unsupported_timeframe, _}} for a crypto category rather than degrading to the nearest width it does serve. Declare the union and substitute at the call, and you have built exactly the failure this family exists to stop.

The limitation this leaves, stated rather than implied

A consumer cannot ask "which widths for crypto specifically" or "is the order book streamable for options". They get the venue-wide answer and discover the per-class truth from an honest refusal. That is a real gap with two confirmed instances:

• dp_exchange_webull cannot say that 1w/1M/1y are equity, option and futures only.
• dp_exchange_schwab cannot declare :order_book for options alone, which is one of two reasons OPTIONS_BOOK stays unwired — see that package's docs/design/ideas/schwab-depth-and-account-activity-streaming.md.

Closing it means an asset-class dimension on these fields, which is a breaking change to a published type for a gap no consumer has yet reported hitting. It is recorded here so the next person weighing it starts from the two instances rather than from zero — and so that a venue author reading this file today knows which reading to write against.

:top_of_book is not :order_book

Venues stream these on separate channels because they are separate things: a best-bid/ask feed carries one level and a depth feed carries many, and the first is deliberately cheaper. They are kept apart here for the same reason Types.TopOfBook is not Types.OrderBook — a consumer subscribing to depth and receiving a single level would be told it has a book when it has a quote.

What these were measured against

Gemini's AsyncAPI document and Schwab's Streamer service list, read 2026-08-31:

bookTicker                          -> :top_of_book
depth, depth5/10/20 (+Fast)         -> :order_book
trade                               -> :trades
ordersAccount, ordersSession        -> :orders
balancesAccount (+Snapshot)         -> :balances
positionsAccount (+Snapshot)        -> :positions
LEVELONE_*                          -> :quotes
NYSE_BOOK, NASDAQ_BOOK, OPTIONS_BOOK -> :order_book
CHART_EQUITY, CHART_FUTURES         -> :candles
ACCT_ACTIVITY                       -> :orders and :fills

Three streamed channels have no kind here yet, deliberately: Gemini's settlementsAccount and contractStatus are prediction-market lifecycle events, and its requestForQuote* family is an RFQ surface. None has a facade home, and inventing a kind before the shape is decided would put a name on the contract that nothing can deliver.

@type maturity() :: :proven | :experimental | :unsupported

How well one endpoint is known.

:experimental is the default and the only honest starting state. :proven is earned per endpoint by production use.

@type session() :: :pre_market | :regular | :post_market | :extended

Which trading session an order names, on a venue whose market closes.