@callback asset_classes() :: [atom()]

Which asset classes this venue trades, e.g. [:crypto] or [:crypto, :equity].

@callback cancel_order(credentials(), String.t(), keyword()) ::
  result(DpExchange.Core.Types.Order.t())

Cancels an order.

@callback capabilities() :: DpExchange.Core.Capabilities.t()

The activation map: which functions are answerable, and how well each is known.

Static and safe at boot. This is what a consumer branches on instead of venue identity.

@callback child_spec(keyword()) :: Supervisor.child_spec()

Starts the venue's whole tree — connections, limiter, session refresh, whatever it needs.

A venue with no processes returns :ignore. You put this in your supervision tree and choose its restart strategy, shutdown order and name.

@callback coverage(keyword()) :: %{required(symbol()) => route()}

What is observed arriving, by which route — never what was subscribed.

This is the strongest guarantee in the contract, and it exists because intent standing in for evidence is how a venue reported 325 symbols subscribed and confirmed while 174 were delivering. A venue that cannot observe delivery answers :not_covered rather than reporting success it cannot see.

Symbols absent from the map are :not_covered.

@callback get_accounts(
  credentials(),
  keyword()
) :: result([map()])

Accounts visible to the credential.

@callback get_balances(
  credentials(),
  keyword()
) :: result([DpExchange.Core.Types.Balance.t()])

Balances for the credentialed account.

@callback get_fees(
  credentials(),
  keyword()
) :: result(map())

The fee schedule that applies to this credential.

@callback get_historical_prices(symbol(), String.t(), keyword(), keyword()) ::
  result([DpExchange.Core.Types.Quote.t()])

Historical candles for symbol at timeframe.

The venue rejects a timeframe it does not serve rather than substituting the nearest one. A missing granularity silently becoming the closest one mislabels every candle it touches, and every value stays plausible.

@callback get_market_overview(keyword()) :: result(map())

A bulk snapshot across the venue's symbols, where it offers one.

@callback get_order(credentials(), String.t(), keyword()) ::
  result(DpExchange.Core.Types.Order.t())

One order's current state.

@callback get_order_book(
  symbol(),
  keyword()
) :: result(DpExchange.Core.Types.OrderBook.t())

The order book for symbol, best price first on both sides.

@callback get_orders(
  credentials(),
  keyword()
) :: result([DpExchange.Core.Types.Order.t()])

Orders visible to the credential.

@callback get_price(
  symbol(),
  keyword()
) :: result(DpExchange.Core.Types.Quote.t())

The current price for symbol.

@callback get_rate_limit_status(
  credentials() | nil,
  keyword()
) :: result(map())

What the venue's ceiling currently is and how much of it is left.

@callback get_symbols(keyword()) :: result([symbol()])

Every symbol the venue lists.

@callback get_trade_history(
  credentials(),
  keyword()
) :: result([DpExchange.Core.Types.Fill.t()])

Past fills for the credential.

@callback get_transfers(
  credentials(),
  keyword()
) :: result([map()])

Deposit and withdrawal history — needed to compute cost basis for transferred-in assets.

@callback list_instruments(keyword()) :: result([DpExchange.Core.Instrument.t()])

The venue's listings with the fields get_symbols/1 discards — base, quote, instrument type, trading status.

Optional: single-quote venues derive base and quote trivially and have no non-spot instruments, so requiring an implementation there is ceremony.

@callback market_status(keyword()) :: result(market_status())

Whether the venue is trading right now.

Crypto venues answer :open. An equity venue answers honestly, including pre- and post-market.

Not cosmetic. A feed that delivers nothing warns loudly and keeps warning, so without this an equities package alarms every night and every weekend — and a real outage becomes indistinguishable from Saturday. The venue is the only thing that knows its own calendar; the policy — whether to trade in extended hours — stays with the consumer.

@callback place_order(credentials(), map(), keyword()) ::
  result(DpExchange.Core.Types.Order.t())

Places an order. Irreplaceable by definition: this is the act.

@callback provider_name() :: String.t()

The venue's display name.

@callback quantization(symbol()) :: result(map())

Rounds a price and quantity to what the venue will actually accept.

Optional: when a venue does not implement it, a caller skips quantization and falls back to per-asset-class defaults.

@callback runtime_id() :: atom()

The venue's stable identifier, matching its package's namespace segment.

@callback start_link(keyword()) :: {:ok, pid()} | :ignore | {:error, term()}

Starts the venue directly. See child_spec/1 — a venue with no processes returns :ignore.

@callback subscribe(
  [symbol()],
  keyword()
) :: :ok | {:error, term()}

Subscribes the caller to symbols.

The venue decides everything about how. Connections, sharding, pacing, protocol, whether it streams at all or polls and pushes the results — none of it crosses this boundary, and a caller cannot discover it.

Events arrive as messages to the subscribing process, or to a pid given in opts, tagged so a process subscribed to several venues can tell them apart. The payload is a DpExchange.Core.Types.* struct — the same value the pull endpoints return — so one handler serves a price whether the caller asked for it or was sent it.

Back-pressure is a bounded mailbox, and it is declared

A venue pushing faster than its subscriber consumes drops oldest beyond a stated bound and emits a :degraded notice saying so. Growing a mailbox silently until the node dies is the failure this avoids; dropping silently is the failure the notice avoids.

@callback subscribe_notices(keyword()) :: :ok | {:error, term()}

Subscribes the caller to the package's notices — what it is doing and what is going wrong with it.

Distinct from subscribe/2, which carries what the venue says about the market. A monitoring process that never touches market data still needs to know a credential was rejected.

A notice is a prompt to re-read, never the record. Delivery is not guaranteed — see DpExchange.Core.Notice.

@callback test_connection(
  credentials() | nil,
  keyword()
) :: result(map())

Whether the venue is reachable and the credential, if given, is accepted.

@callback unsubscribe(
  [symbol()],
  keyword()
) :: :ok | {:error, term()}

Stops delivery for symbols.

Addressed by the thing itself, never by a handle. Takes the same identifiers subscribe/2 was given: on crypto the pair, on an equity venue the symbol. A caller already knows what it subscribed to, so a subscription reference would be pure overhead wrapping something it already holds — and one more thing to leak.

A dead subscriber stops delivery too. A venue must not accumulate events for a process that no longer exists.

@callback update_symbols(
  [symbol()],
  keyword()
) :: :ok | {:error, term()}

Changes a live subscription's symbol set without tearing the venue's connections down.