Struct AlpacaClient 

pub struct AlpacaClient { /* private fields */ }

Alpaca execution client supporting options, equities, and crypto via the single unified Alpaca trading API.

All three asset classes share the same REST and WebSocket endpoints. The key behavioral differences handled transparently:

• Options: position_intent field is required (detected by OCC symbol format)
• Crypto: position_intent is omitted (not a valid field for crypto orders); fractional quantities are supported natively via Decimal::to_string()
• Equities: position_intent is valid but optional for long-only strategies

Rate limits

Once a response reports no requests left in the current window (X-Ratelimit-Remaining: 0), every request, orders included, waits until the window resets (X-Ratelimit-Reset, at most a minute away), so it is not refused. A 429 waits the same way and is retried.

Cloning is cheap: all inner state is behind Arc.

Implementations

impl AlpacaClient

pub async fn open_order_with_intent( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, intent: AlpacaPositionIntent, ) -> Option<Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>>

Place an order with an explicit position_intent override.

Use this instead of ExecutionClient::open_order when you need to specify exact position intent (e.g. SellToOpen for writing a short option, or BuyToClose for closing a short position by buying).

intent is only sent for non-crypto symbols. For crypto symbols (those containing /) the field is always omitted regardless of intent.

Caller obligations

The caller is responsible for passing the semantically correct intent. No validation is performed against the order side or existing position.

pub async fn open_bracket_order( &self, request: AlpacaBracketOrderRequest, ) -> AlpacaBracketOrderResult

Place a bracket order (entry + take-profit + stop-loss) in a single request.

A bracket order consists of three linked orders:

1. Entry: Limit order to enter the position
2. Take Profit: Limit order to exit at profit target
3. Stop Loss: Stop (or stop-limit) order to exit at loss limit

When the entry order fills, Alpaca activates both exit legs. When either exit leg fills, Alpaca automatically cancels the other.

Constraints

• time_in_force must be Day or GoodUntilCancelled (Alpaca rejects others)
• No extended hours trading with bracket orders
• Entry is always a limit order

Example

let request = AlpacaBracketOrderRequest::new(
    "AAPL".into(),
    StrategyId::new("momentum"),
    ClientOrderId::new("bracket-001"),
    Side::Buy,
    dec!(10),
    dec!(150.00),  // entry
    dec!(160.00),  // take profit
    dec!(145.00),  // stop loss
    TimeInForce::GoodUntilCancelled { post_only: false },
);
let result = client.open_bracket_order(request).await;

Trait Implementations

impl BracketOrderClient for AlpacaClient

async fn open_bracket_order( &self, request: UnifiedBracketOrderRequest<ExchangeId, &InstrumentNameExchange>, ) -> UnifiedBracketOrderResult

Place a bracket order (entry + take-profit + stop-loss).

impl Clone for AlpacaClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AlpacaClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl ExecutionClient for AlpacaClient

fn new(config: Self::Config) -> Self

Panics

Panics if the API key or secret key contains characters invalid in an HTTP header value.

async fn account_snapshot( &self, assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<UnindexedAccountSnapshot, UnindexedClientError>

Balances and positions

• USD: total is the account’s cash, and free the lesser of cash and its non_marginable_buying_power: cash that can be spent without borrowing. Alpaca’s buying power figures include the loan value of held stock, so none of them alone is free cash. A short sale’s proceeds are credited to cash but do not raise buying power, so free stays below total while a short is open. Cash is negative while the account borrows on margin, and then free is negative too. Account equity is not reported: it is cash plus the value of the positions below, so it can be derived.
• Equities and options: each holding becomes the InstrumentAccountSnapshot::position of its instrument, PositionReport::Open with a signed Position (negative for a short), the average entry price and the unrealised PnL in USD. An equity or option without a holding is PositionReport::Flat, since Alpaca lists every open position. An option’s entry price is the premium per share of the underlying, as quoted and as orders are priced, not per contract. Margin, liquidation price and leverage are None, and time_exchange is the time of the call, since Alpaca does not timestamp positions.
• Crypto: each holding is an asset balance of its base asset (e.g. btc for BTC/USD), in base units. Alpaca crypto is spot-only and cannot be sold short, so there is no position to report: its instruments are PositionReport::Unreported.

Limitations

A position is reported only under the instrument name Alpaca uses for it, ignoring case: the ticker for an equity and the OCC symbol for an option. A requested equity or option named otherwise is reported PositionReport::Flat even while Alpaca holds it. A crypto pair is recognised by the / in its name (e.g. BTC/USD, the form its orders use); one named without it is taken for an equity and reported flat too. With instruments empty, every instrument that has an open order or a position gets a snapshot; otherwise only the requested ones do.

Errors

ClientError::Internal when a response does not decode, or when any non-zero equity or option position, requested or not, has a missing or unrecognised side: its direction cannot be known, and leaving it out would read as flat. Other request failures are Connectivity or Api, as for every Alpaca REST call.

Rate limit note

/v2/positions is fetched on every call, since it holds both the crypto balances and the equity and option positions. When USD is requested too (the common startup case), /v2/account is fetched in parallel with it for ~100-300ms latency savings. Under rate pressure, both requests may hit 429 simultaneously and retry independently. Operators approaching Alpaca rate limits can request only non-USD assets to skip /v2/account.

async fn account_stream( &self, _assets: &[AssetNameExchange], instruments: &[InstrumentNameExchange], ) -> Result<Self::AccountStream, UnindexedClientError>

Returns a live stream of account events (fills, order updates).

Startup race window

Fills arriving between account_snapshot and this method being called by the caller are not recovered automatically — the WebSocket connection does not exist yet during that window. Fills that arrive after the connection is established but before the first poll are buffered in the tungstenite internal buffer and delivered normally. Callers requiring fill completeness at startup must call ExecutionClient::fetch_trades with a ~1 s lookback after calling this method.

This gap also applies on every reconnect: during the auth+subscribe handshake (connect_and_subscribe), any trade_updates messages that arrive are consumed by the handshake loop and not forwarded. Fill events in this window are recovered via the REST activities endpoint (anchored to disconnect_time). Lifecycle events (new, canceled, rejected) consumed during the handshake are not recovered — callers must call fetch_open_orders after each reconnect to reconcile order state.

Fill recovery ordering

After a reconnect, missed fills are recovered from the REST activities endpoint using direction=asc to match the chronological order in which the WS stream advanced filled_qty. The dedup key "{order_id}:{cum_qty}" is taken from the activity’s own cum_qty, so it matches the WS path by construction and does not depend on the order in which activities arrive.

Only where Alpaca omits cum_qty does the key fall back to accumulating per-execution qty within the batch. That fallback counts from zero per order, so it is correct only for an order whose fills lie wholly inside the recovery window, and it is sensitive to activities arriving out of chronological order (e.g. at pagination boundaries).

A recovered fill also carries the order’s cumulative filled quantity, so it advances the order’s filled_quantity without waiting for a fetch_open_orders reconciliation.

Lifecycle event deduplication

Order lifecycle events (new, canceled, expired) are not deduplicated across reconnects — only fill events carry a dedup key. After a reconnect, Alpaca re-delivers lifecycle events for orders that were active at disconnect time. Specifically, Alpaca re-delivers a new event for every order open at disconnect time, not only orders that changed during the gap. Callers must make AccountEventKind::OrderSnapshot and AccountEventKind::OrderCancelled processing idempotent, or call ExecutionClient::fetch_open_orders after each reconnect to reconcile state.

Rejected orders

Alpaca rejected events are delivered as AccountEventKind::OrderCancelled with state: Err(OrderRejected(...)). Match on response.state.is_err() to distinguish rejections from true cancels — do not call .unwrap() on OrderCancelled.state.

Stream drop behaviour

Dropping the returned BoxStream initiates a graceful shutdown of the background connection_manager task: the channel close causes the task to send a WebSocket close frame and exit within the current heartbeat window (≤60 s). Any AccountEvent items already queued but not yet polled are discarded. Callers who drop and re-subscribe must call ExecutionClient::fetch_trades with a short lookback to recover the gap.

async fn cancel_order( &self, request: OrderRequestCancel<ExchangeId, &InstrumentNameExchange>, ) -> Option<UnindexedOrderResponseCancel>

Cancel an order.

Async cancel semantics

Returns Ok(Cancelled) once Alpaca has accepted the cancel, not once the order is cancelled: DELETE /v2/orders/{id} answers 204 when the cancel request is accepted and the order will be cancelled. Until it is, the order can be pending_cancel, still live, and can still fill. The account stream reports how it ended, and any fill.

The 204 has no body, so filled_quantity is zero whatever the order filled, and time_exchange is the local time the answer arrived.

Needs the venue order id. A request without one is refused, since Alpaca cancels by that id only; resolve it through ExecutionClient::fetch_open_orders.

async fn open_order( &self, request: OrderRequestOpen<ExchangeId, &InstrumentNameExchange>, ) -> Option<Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>>

Position intent derivation

Alpaca options/equities require explicit position_intent. This impl derives intent from RequestOpen::reduce_only and side:

reduce_only	side	intent	use case
false	Buy	BuyToOpen	open long / add to long position
false	Sell	SellToOpen	open short / write option
true	Buy	BuyToClose	close short position
true	Sell	SellToClose	close long position

For explicit control, use AlpacaClient::open_order_with_intent.

Market order price

The returned Order.price echoes the request price. For market orders this is typically Decimal::ZERO (a placeholder). The actual fill price arrives via the WebSocket trade_updates stream as a Trade event. Do not rely on Order.price from this REST ack for market order fill prices.

async fn fetch_balances( &self, assets: &[AssetNameExchange], ) -> Result<Vec<AssetBalance<AssetNameExchange>>, UnindexedClientError>

Fetches balances sequentially (unlike account_snapshot which parallelizes).

Sequential fetch is intentional for live operation: under rate pressure, parallel requests may both hit 429 simultaneously and retry independently, doubling the backoff delay. The startup latency savings from account_snapshot’s parallel fetch are worth the tradeoff there; for periodic balance refreshes during live trading, sequential is safer.

const EXCHANGE: ExchangeId = ExchangeId::AlpacaBroker

const SUPPORTED_KINDS: &'static [InstrumentKindDiscriminant]

The InstrumentKindDiscriminants this client can trade.

type Config = AlpacaConfig

type AccountStream = Pin<Box<dyn Stream<Item = AccountEvent<ExchangeId, AssetNameExchange, InstrumentNameExchange>> + Send>>

async fn fetch_open_orders( &self, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Order<ExchangeId, InstrumentNameExchange, Open>>, UnindexedClientError>

Fetch currently open orders, optionally filtered by instrument.

async fn fetch_trades( &self, time_since: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> Result<Vec<Trade<AssetNameExchange, InstrumentNameExchange>>, UnindexedClientError>

Fetch trades (fills) since time_since, optionally filtered by instrument.

fn cancel_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestCancel<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Option<UnindexedOrderResponseCancel>> + Send

fn open_orders<'a>( &self, requests: impl IntoIterator<Item = OrderRequestOpen<ExchangeId, &'a InstrumentNameExchange>>, ) -> impl Stream<Item = Option<Order<ExchangeId, InstrumentNameExchange, UnindexedOrderState>>> + Send