@callback asset_classes() :: [asset_class(), ...]

Asset classes this provider supports. Used by Strategy.AccountCapabilities to gate template recommendations and by the Strategy resource to reject configurations where the strategy's declared asset class isn't tradable on its credential's provider.

Providers must return a non-empty list. A provider that supports both crypto and equity (e.g. Webull) returns [:crypto, :equity]; pure crypto exchanges return [:crypto].

@callback cancel_order(String.t(), credentials(), keyword()) ::
  {:ok, order_data()} | {:error, String.t()}

Cancel an existing order.

Parameters

• order_id: Order ID to cancel
• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, order_data()} on success
• {:error, reason} on failure

@callback capabilities() :: capabilities()

Capability declaration for this provider — consumed by orchestration code so it can make routing decisions without case provider do "webull" -> branches. See Exchanges.Core.Capabilities for field semantics.

Build it with Capabilities.new/1, which validates the collection-scope invariants a struct cannot express.

Required: every adapter must answer truthfully. There is no default on the behaviour because silent defaults hide adapter bugs (a new adapter that forgets to override would silently look like a streaming provider and starve its indicator engines).

@callback get_accounts(
  credentials(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Get account information and balances.

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, [account_data()]} on success
• {:error, reason} on failure

@callback get_balances(
  credentials(),
  keyword()
) :: {:ok, [balance_data()]} | {:error, String.t()}

Get account balances for all currencies.

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, [balance_data()]} on success
• {:error, reason} on failure

@callback get_fees(
  credentials(),
  keyword()
) :: {:ok, map()} | {:error, String.t()}

Get fee structure for trading.

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, fee_data()} on success
• {:error, reason} on failure

@callback get_historical_price(symbol(), currency(), DateTime.t(), keyword()) ::
  {:ok, Decimal.t()} | {:error, :not_supported} | {:error, term()}

Get the spot price for symbol quoted in quote_currency at the given UTC timestamp. Historical-price adapters implement this; live exchange adapters generally return {:error, :not_supported}.

Phase 4 of docs/design/2026-06-30_boundary-violation-audit-and-refactor.md.

Parameters

• symbol — the base ticker (e.g. "BTC", "ETH").
• quote_currency — the quote currency (e.g. "USD").
• timestamp — the UTC datetime for the historical price.
• opts — adapter-specific options.

Returns

• {:ok, Decimal.t()} — the historical price.
• {:error, :not_supported} — the adapter doesn't implement historical prices (e.g. spot-only exchanges).
• {:error, term()} — other failures (network, API, unmapped symbol).

@callback get_historical_prices(symbol(), DateTime.t(), DateTime.t(), keyword()) ::
  {:ok, [price_data()]} | {:error, String.t()}

Get historical price data for a specific trading pair/symbol.

Parameters

• symbol: Trading pair symbol (e.g., "BTC-USD", "ETH-USD")
• start_time: Start time for historical data
• end_time: End time for historical data
• opts: Optional parameters (granularity, etc.)

Returns

• {:ok, [price_data()]} on success
• {:error, reason} on failure

@callback get_market_overview(credentials() | nil) ::
  {:ok, [market_overview_entry()]} | {:error, :not_supported | String.t()}

Single bulk-stats call returning a 24h overview for every tradable pair on this provider. Used by the universe analyzer's discovery pass to rank pairs without falling back to per-symbol polling.

Implementations:

• Binance: single /api/v3/ticker/24hr call (~2000 pairs).
• Coinbase: paginated /api/v3/brokerage/products.
• Kraken: comma-chunked /0/public/Ticker calls.
• Gemini: /v1/symbols + per-symbol /v1/pubticker/{s} fan-out.
• Robinhood / Webull: no bulk endpoint exposed; declare {:error, :not_supported}. The analyzer routes those strategies through the sibling-credential pattern (Decision 2) or skips the discovery pass entirely if no sibling is present.

Optional callback — adapters that don't implement it fall through to {:error, :not_supported} in the analyzer's router.

@callback get_order(String.t(), credentials(), keyword()) ::
  {:ok, order_data()} | {:error, String.t()}

Get order status and details.

Parameters

• order_id: Order ID to query
• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, order_data()} on success
• {:error, reason} on failure

@callback get_order_book(
  symbol(),
  keyword()
) :: {:ok, map()} | {:error, String.t()}

Get order book (bids and asks) for a symbol.

Parameters

• symbol: Trading pair symbol
• opts: Optional parameters (depth, etc.)

Returns

• {:ok, order_book_data()} on success
• {:error, reason} on failure

@callback get_orders(
  credentials(),
  keyword()
) :: {:ok, [order_data()]} | {:error, String.t()}

Get list of orders (open, filled, cancelled).

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters (status filter, symbol filter, pagination, etc.)

Returns

• {:ok, [order_data()]} on success
• {:error, reason} on failure

@callback get_price(
  symbol(),
  keyword()
) :: {:ok, price_data()} | {:error, String.t()}

Get current price data for a specific trading pair/symbol.

Parameters

• symbol: Trading pair symbol (e.g., "BTC-USD", "ETH-USD")
• opts: Optional parameters for the request

Returns

• {:ok, price_data()} on success
• {:error, reason} on failure

@callback get_rate_limit_status(
  credentials(),
  keyword()
) :: {:ok, rate_limit_info()} | {:error, String.t()}

Get current rate limit status for the API.

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, rate_limit_info()} on success
• {:error, reason} on failure

@callback get_symbols(keyword()) :: {:ok, [symbol()]} | {:error, String.t()}

Get available trading pairs/symbols supported by the provider.

Parameters

• opts: Optional parameters for the request

Returns

• {:ok, [symbol()]} on success
• {:error, reason} on failure

@callback get_trade_history(
  credentials(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Get trade history for the account.

Parameters

• credentials: API credentials for authentication
• opts: Optional parameters (symbol filter, pagination, etc.)

Returns

• {:ok, [trade_data()]} on success
• {:error, reason} on failure

@callback get_transfers(
  credentials(),
  keyword()
) :: {:ok, [map()]} | {:error, :not_supported} | {:error, term()}

Get the credentialed account's deposit / withdrawal history.

Needed to compute cost basis for assets TRANSFERRED INTO the venue rather than bought on it — without it, transfer-in positions get current price as their "cost basis" and stop-loss / trailing-stop rules fire at meaningless levels.

Parameters

• credentials: API credentials for authentication
• opts: Optional filters (:currency, :since, :limit)

Returns

• {:ok, [transfer_data()]} where each entry has at minimum:
  • :currency — uppercase asset code (e.g. "BTC", "BAT")
  • :type — :deposit or :withdrawal
  • :amount — Decimal or string-parseable number
  • :timestamp — DateTime.t() Adapters MAY include exchange-specific fields (:tx_hash, :address) in the map; consumers must not require them.
• {:error, reason} on failure
• {:error, :not_supported} when the exchange has no transfer API or the adapter hasn't implemented one yet. Adapters MUST return this rather than raise, so callers can decide how to fall back.

@callback list_instruments(keyword()) ::
  {:ok, [DpExchange.Core.Instrument.t()]} | {:error, term()}

The venue's full listing, with base, quote, instrument type and status — everything get_symbols/1 discards.

get_symbols/1 returns [String.t()], so each adapter fetches the venue's rich payload and drops all but the name. The pair catalog needs precisely those dropped fields, and recovering them by parsing the symbol back apart is what this design rejects: an earlier draft regex-matched a PERP suffix and got Gemini's quote distribution measurably wrong. Gemini is the sharp case — its symbols carry no separator, so BTCUSDCPERP cannot be split at all without the venue's own fields.

Optional. Venues publishing a single-quote -USD catalog with no non-spot instruments (Webull, Robinhood) can omit it; a consumer's catalogue derives from get_symbols/1 for those and marks anything unresolvable :unknown.

Phase 2 of docs/design/2026-08-05_exchange-quote-currencies-and-decoupled-data-collection.md.

@callback place_order(order_request(), credentials(), keyword()) ::
  {:ok, order_data()} | {:error, String.t()}

Place a new trading order.

Parameters

• order_request: Order details including symbol, side, type, quantity, etc.
• credentials: API credentials for authentication
• opts: Optional parameters for the request

Returns

• {:ok, order_data()} on success
• {:error, reason} on failure

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

Get the provider name/identifier.

Returns

• Provider name as string (e.g., "coinbase", "gemini")

@callback quantization(symbol()) ::
  {:ok, quantization()} | {:error, :not_supported | String.t()}

Quantization constraints for symbol on this provider. Used by the sizer (small-capital fractional sizing) and the order-build step to snap the requested quantity + limit price to a broker-acceptable shape before submission. Otherwise the broker rejects the order at submission time with a confusing "invalid quantity" error.

Optional callback — adapters that don't implement it fall through to a permissive default (min_qty: nil, qty_step: nil) and the caller skips quantization. Implementations should return constraints derived from the broker's published symbol metadata, falling back to sensible per-asset-class defaults when the metadata is unavailable.

@callback runtime_id() :: atom()

Runtime atom identifier for the provider — used by GenServer state trackers (DataCollectionManager, ProcessManager) that key by atom rather than string. Each adapter declares its own identifier so there is no central name→atom whitelist.

Most adapters return provider_name() |> String.downcase() |> String.to_atom() shape. The mock provider returns :mock_provider for historical reasons (older code paths assumed the literal atom).

@callback supported_features() :: %{
  websocket: boolean(),
  historical_data: boolean(),
  real_time_balances: boolean(),
  order_management: boolean()
}

Get supported features for this provider.

Returns

• Map of feature flags indicating what functionality is supported

@callback test_connection(
  credentials() | nil,
  keyword()
) :: {:ok, :connected} | {:error, String.t()}

Test API connectivity and authentication.

Parameters

• credentials: API credentials for authentication (optional for public endpoints)
• opts: Optional parameters for the request

Returns

• {:ok, :connected} on successful connection
• {:error, reason} on failure