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, for the wait Alpaca gives or a minute without one, and is retried. Once the retries are exhausted the request fails with ApiError::RateLimit, carrying that wait, and later requests still wait for it.

Fees, interest and borrow fees

Every Trade this client reports carries zero fees. Equities and options trade without commission. Alpaca’s fill events carry no fee for crypto either: it is taken from the asset the trade credits, so it shows only in that asset’s balance.

Alpaca posts its other charges, such as margin interest and fees, to the account’s cash as account activities. A USD balance’s total is that cash, so it includes a charge once Alpaca has posted it. ExecutionClient::account_stream delivers none of them, nor any balance: Alpaca streams neither. AlpacaClient::fetch_cash_flows reads them on request. PnL computed from fills excludes them.

Cloning is cheap: all inner state is behind Arc.

Implementations

impl AlpacaClient

pub async fn fetch_cash_flows( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<CashFlowsRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Read the cash Alpaca moved into or out of the account other than by a trade, from start to end: interest, fees, and pass-through charges and rebates.

Alpaca streams none of these: trade_updates carries order events only. Nothing is pushed: the caller decides when to read, and must drop the flows it has already applied, by id, before applying a read’s. Alpaca posts each to the account’s cash, so the account’s USD balance already includes a flow read here.

What each activity becomes

Activity	CashFlowKind
INT of sub-type MGN, or with no sub-type and a negative amount	MarginInterest, with no rate or principal: Alpaca reports neither
PTR, a pass-through rebate	Rebate
Any other: FEE, PTC, credit interest	Other, naming the type and, when Alpaca gives one, the sub-type, as FEE.TAF

Alpaca documents no activity type for a stock borrow fee. Should it post one as one of these, it arrives as Other with its own name.

• amount is Alpaca’s net_amount, negative when the account paid.
• asset is its currency, or USD when it names none.
• instrument is its symbol, when it names one.
• time_exchange is when Alpaca created the activity (created_at), which its after and until filter on. A fee is typically created the day after the trade it was charged on.
• id is Alpaca’s activity id.

Status

• An activity Alpaca marks canceled is left out, and logged at INFO. A flow read before it was canceled is not reversed: the caller reconciles against the account’s cash.
• One marked correct is returned like any other. Alpaca does not document whether a correction stands beside the activity it corrects or replaces it, so a caller applying both by id may count the cash twice. Reconcile against the account’s cash.

An activity without an amount or a creation time that parses is left out, and logged at WARN.

Cost and resuming

One call sends up to 50 requests, reading at most 5,000 activities, and returns resume when it stops there: the millisecond of the last activity’s creation time. That resume is exact only if Alpaca serves these activities in order of creation, as it serves fills in order of time; its documentation orders them by “activity datetime” without saying which time, and this ordering has not been observed for them. Read spans short enough to fit one call, as the volume of these activities usually allows, and resume stays None.

Errors

Fails if a request fails, or, with UnindexedClientError::Internal, if more activities share the span’s first millisecond than one call reads, so a read from resume could not advance.

pub async fn fetch_option_events( &self, start: DateTime<Utc>, end: DateTime<Utc>, ) -> Result<TradesRead<AssetNameExchange, InstrumentNameExchange>, UnindexedClientError>

Read the trades Alpaca made when an option contract was exercised, assigned or expired, from start to end.

Alpaca reports these as account activities, not fills: trade_updates carries none of them, and fetch_trades reads fills only. Nothing is pushed: the caller decides when to read, and must drop the trades it has already applied, by id, before applying a read’s. To let these trades move the engine’s positions without the engine also settling the contract at expiry, set the exchange’s expiry handling to Venue (see ExpiryHandling in the rustrade crate).

What each activity becomes

Each becomes one Trade, whose origin says why it happened:

Activity	Instrument	TradeOrigin	Price
OPEXP, expiry	the contract	Expiry	0
OPEXC, exercise	the contract	Exercise	0
OPASN, assignment	the contract	Assignment	0
OPTRD, the shares an exercise or assignment trades	the underlying	that of its exercise or assignment, else External	the strike

• side and quantity come from Alpaca’s signed qty: negative is a sell. An exercised long or an expiring long is sold; an assigned short is bought. Quantities are in contracts on the contract, and in shares on OPTRD.
• The contract leaves at a price of 0. What it was worth at exercise or assignment is in the shares traded at the strike.
• time_exchange is when Alpaca created the activity (created_at), or the start of its date, in UTC, when it gives no creation time. Such a dated activity is in the span when its date is one of the span’s UTC days, so a read up to now still returns one posted today, and successive reads within one day each return it again.
• id and order_id are Alpaca’s activity id, since no order produced the trade. strategy is unknown, and fees are zero.

Pairing the share leg

OPTRD names the underlying, not the contract, so its origin is found by pairing it with an OPEXC or OPASN of the same date whose contract’s root symbol is the OPTRD’s symbol, whose strike is its price, and whose kind implies its side: exercising a call or being assigned on a put buys the shares, and the other two sell them. Each is paired at most once, in the order Alpaca returns them, preferring one of 100 shares a contract, the standard size, so that two exercises at one strike pair with their own shares. An OPTRD with no such partner is returned as External, and logged at WARN. The read covers the whole UTC days of start and end, so that both legs are read together, and returns only the trades in start..=end.

Status

An activity Alpaca marks canceled is left out, and logged at INFO. An activity without a symbol, a non-zero quantity or a time, an OPTRD without a price, or one of another type is left out, and logged at WARN.

Cost and resuming

As fetch_cash_flows: one call sends up to 50 requests, reading at most 5,000 activities, and returns resume when it stops there. A read from resume reads its whole UTC day again, so drop by id what was already applied. So more than 5,000 option activities in one UTC day cannot be read through; see Errors.

A read that stops at the cap can split an exercise or assignment from its share leg, and return the OPTRD as External while the next read, from resume, returns it again with its pair’s origin. A caller dropping trades by id keeps the first. When a read returns resume, hold back its External OPTRDs until the next read.

Errors

Fails if a request fails, or, with UnindexedClientError::Internal, if a read from resume could not advance: one UTC day holds more option activities than one call reads. That includes a day whose activities before start alone fill the call.

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.

impl ShortabilityClient for AlpacaClient

async fn fetch_shortability( &self, instrument: &InstrumentNameExchange, ) -> Result<Shortability, UnindexedClientError>

Reads the asset with GET /v2/assets/{symbol}, one request.

• shortable is the asset’s shortable.
• easy_to_borrow is its borrow_status, which Alpaca reports for US equities only, or failing that its easy_to_borrow flag; neither present leaves it unknown.
• fee_rate is zero for an easy-to-borrow stock, as Alpaca charges no borrow fee on one. That is Alpaca’s charge, not the market’s cost of borrowing. Alpaca publishes no rate for a hard-to-borrow stock, so its fee is unknown.
• available is unknown. Alpaca’s locate quotes report what it can lend of a hard-to-borrow stock, but they are not on paper accounts and are not read here.

Alpaca updates its borrow flags from a daily list, so they may be up to a day old.

Errors

ApiError::InstrumentInvalid for a symbol Alpaca knows no asset under, and for an option, as writing one borrows nothing.