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

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>

Limitations

No position is reported per instrument: every InstrumentAccountSnapshot::position is None. Crypto holdings from /v2/positions become asset balances. Equity and option positions are left out (#418); they count only toward the USD balance, whose total is account equity and whose free is buying power.

Rate limit note

When both USD and non-USD assets are requested (the common startup case), this method fetches /v2/account and /v2/positions in parallel for ~100-300ms latency savings. Under rate pressure, both requests may hit 429 simultaneously and retry independently. Operators approaching Alpaca rate limits should call with explicit asset filters to serialize requests if needed.

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