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, ) -> 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 the asset it holds (e.g. BTC for the position Alpaca lists as BTCUSD), 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). How an order held as live ended in this window is recovered too (see below); a lifecycle event of any other order, such as new for one placed elsewhere, is not.

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. A fill both paths deliver is sent once: it is recognised by its execution id, which the WS frame and the FILL activity both carry.

A fill lacking that id on either path is recognised instead by "{order_id}:{cum_qty}", taken from the activity’s own cum_qty, so it matches the WS path’s filled_qty by construction. Only where Alpaca omits cum_qty too does that 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.

Every fill’s TradeId is Alpaca’s execution id, whether the stream, recovery, or ExecutionClient::fetch_trades delivers it, so a fill read again by fetch_trades matches the one the stream delivered. A stream fill whose execution_id is missing, null or empty is logged and identified by "{order_id}:{filled_qty}" instead.

The read is made once, with no retry. When it fails, times out, or stops at 5,000 fills, the stream sends one AccountEventKind::FillRecoveryGaveUp covering the stream’s instruments, or every instrument when that list is empty. A truncated read delivers the fills it read first, and the event’s span starts just before the last of them.

Busted and corrected fills

A trade_bust or trade_correct is sent as AccountEventKind::TradeAmended, naming the fill amended by its TradeId; the fill itself was delivered as first reported and is not withdrawn. The Trading API documents neither event, so their frames are read per Alpaca’s Broker API schema, and each is also logged whole at warn!. One sent while the stream was disconnected is not recovered.

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.

Orders that ended while disconnected

A reconnect also reports how each order the client holds as live ended, where it did, as an AccountEventKind::OrderSnapshot of its inactive state: filled (with the average fill price), cancelled or replaced (as cancelled, with what filled before), expired, or rejected. Like fill recovery, it covers only the instruments the stream was opened with, or every instrument when that list is empty. Alpaca’s closed-order list filters on when an order was submitted, so such an order is found by asking about it, not by time.

• Which orders. The client holds an order as live from the response to placing it, from a listing of open orders (account_snapshot, fetch_open_orders), and from its live reports on any of its account streams, until it sees the order end; a cancel Alpaca has only accepted does not end it. A bracket’s take-profit and stop-loss legs carry client order ids Alpaca assigns, so they are held only once a listing or the stream reports them. It holds up to 4,096 orders and forgets the oldest past that, logged at warn. An order placed outside this client and never listed or reported to it is not covered.
• Cost. One GET /v2/orders?status=open request listing every instrument with an order held, then one GET /v2/orders:by_client_order_id for each held order the listing no longer shows, 8 at a time. These share the account’s rate limit with orders, so after an outage in which many held orders ended, the check can hold orders back until the window resets (see Rate limits).
• Fills first. The check starts once fill recovery has finished or given up, so an order’s recovered fills arrive before how it ended. It runs alongside the stream, which is read from the start. A fill that brings an order to its full quantity ends it, and that order is not reported again.
• Keys. Each snapshot carries StrategyId::unknown, since Alpaca records no strategy. The engine matches it to the order it tracks by client order id.
• Failures. Each order’s lookup is settled as it ends. An instrument whose listing or lookup fails, or whose check is still running after 30 s, is retried while connected 1, 2, 4, 8 and 16 minutes later, asking only about the orders still held, then given up, logged at error; its orders are asked about again at the next reconnect. A listing that fails charges every instrument in it. Alpaca lists at most 500 open orders and has no pagination for them, so a listing of 500 may be truncated and fails: an account with 500 or more open orders on the held instruments is not covered. An order Alpaca does not know (404) stops being held, logged at warn; one still live, done_for_day, or in a state this version cannot read stays held.

The same lookup is public as OrderStatusClient::fetch_ended_orders.

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.

Orders done for the day

A done_for_day event is delivered as an AccountEventKind::OrderSnapshot of the order as open, with what it has filled: Alpaca stops working the order until the next trading day but has not ended it.

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>, ) -> 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.

The client keeps holding the order as live until the stream reports how it ended, so if the stream is down when it does, a reconnect still finds out (see account_stream).

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>, ) -> 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.

async fn fetch_trades( &self, start: DateTime<Utc>, end: DateTime<Utc>, instruments: &[InstrumentNameExchange], ) -> Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Cost

One call sends up to 50 requests, reading at most 5,000 FILL activities, and returns resume when it stops there. The limit counts every activity on the account, before the instrument filter, so a call for one instrument can spend all 50 requests and return no trades with resume: Some.

Times

An activity whose transaction_time does not parse is still returned, since Alpaca placed it in the span. Its time_exchange is then the local clock at the read, which can lie outside the span, and a warning names it.

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.

fn validate_config( config: &Self::Config, instruments: &[ClientInstrument<'_>], ) -> Result<(), String>

Checks config against the instruments this client is about to be built to trade, before Self::new is called. Err names what is wrong.

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

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

impl OrderStatusClient for AlpacaClient

async fn fetch_ended_orders( &self, orders: &[UnindexedOrderKey], ) -> Result<Vec<UnindexedInactiveOrder>, UnindexedClientError>

Looks each order up with GET /v2/orders:by_client_order_id, up to 8 at a time.

filled is reported as fully filled with filled_avg_price, canceled and replaced as cancelled (the order replacing one has its own client order id, which the caller must learn from ExecutionClient::fetch_open_orders), expired as expired and rejected as open failed. done_for_day is not ended: Alpaca works the order again the next trading day. A 404, or an order on another symbol than the key’s (ignoring case), is unknown.