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) -> AlpacaClient

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>

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 synthesised by accumulating per-execution qty in that order. If Alpaca returns activities out of chronological order (e.g. at pagination boundaries), dedup keys will diverge and fills may be dropped or duplicated for that order.

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 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

type Config = AlpacaConfig

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

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

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