🦙 alpacars

An async-first Rust SDK for the Alpaca Markets API — a Rust equivalent of the official alpaca-py Python SDK.

📚 Table of Contents

• About
• ✨ Features
• 📦 Installation
• 🔑 API Keys
• 🚀 Usage
  • Trading API
  • Broker API
  • Market Data — Historical
  • Market Data — Live Streaming
• ▶️ Examples
• 🧪 Running Tests
• 🗂️ Supported Clients
• 📄 License

About

alpacars provides a fully async interface to all Alpaca API products — Trading, Broker, and Market Data (historical + live streaming). Every network call is async and returns a Result<T, AlpacaError>, making it easy to integrate into any tokio-based application.

The design mirrors alpaca-py closely so that anyone familiar with the Python SDK can pick up the Rust SDK immediately, while taking full advantage of Rust's type system, ownership model, and zero-cost abstractions.

✨ Features

📦 Installation

Add to your Cargo.toml:

[dependencies]
alpacars = "0.1"

Minimum Rust version: 1.75

🔑 API Keys

Set your credentials as environment variables:

export APCA_API_KEY_ID="your-api-key"
export APCA_API_SECRET_KEY="your-secret-key"

For Broker API, use your Broker API key and secret. For OAuth, pass the token directly to the client constructor.

Obtain API keys from the Alpaca dashboard. 🖥️

🚀 Usage

Trading API

use alpacars::trading::client::TradingClient;
use alpacars::trading::enums::{OrderSide, TimeInForce};
use alpacars::trading::requests::OrderRequest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TradingClient::new("API_KEY", "SECRET_KEY", true)?; // paper = true

    // 💰 Account info
    let account = client.get_account().await?;
    println!("Buying power: {:?}", account.buying_power);

    // 📬 Submit a market order
    let order = client
        .submit_order(&OrderRequest::market("SPY", OrderSide::Buy, "5"))
        .await?;
    println!("Order ID: {}", order.id);

    // 📋 Submit a limit order
    let limit = client
        .submit_order(&OrderRequest::limit(
            "AAPL", OrderSide::Buy, "10", "175.00", TimeInForce::Day,
        ))
        .await?;
    println!("Limit order status: {:?}", limit.status);

    // 📊 List open positions
    let positions = client.get_all_positions().await?;
    println!("Open positions: {}", positions.len());

    // 🗑️ Cancel all open orders
    client.cancel_orders().await?;

    Ok(())
}

Broker API

use alpacars::broker::client::BrokerClient;
use alpacars::broker::requests::ListAccountsRequest;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 🏦 Broker API uses HTTP Basic auth
    let client = BrokerClient::new("BROKER_KEY", "BROKER_SECRET", true)?; // sandbox = true

    let accounts = client.list_accounts(Some(&ListAccountsRequest::default())).await?;
    println!("Accounts: {}", accounts.len());

    Ok(())
}

Market Data — Historical

use alpacars::data::historical::stock::{StockBarsRequest, StockHistoricalDataClient};
use alpacars::data::historical::crypto::{CryptoBarsRequest, CryptoHistoricalDataClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 📈 Stock bars
    let stock = StockHistoricalDataClient::new(Some("KEY"), Some("SECRET"), false)?;

    let bars = stock
        .get_stock_bars(&StockBarsRequest {
            symbols: vec!["AAPL".to_string(), "TSLA".to_string()],
            ..Default::default()
        })
        .await?;

    for (symbol, sym_bars) in &bars {
        println!("{}: {} bars, latest close = {}",
            symbol, sym_bars.len(),
            sym_bars.last().map(|b| b.close).unwrap_or(0.0));
    }

    // ₿ Crypto bars
    let crypto = CryptoHistoricalDataClient::new(Some("KEY"), Some("SECRET"))?;

    let crypto_bars = crypto
        .get_crypto_bars(&CryptoBarsRequest {
            symbols: vec!["BTC/USD".to_string()],
            ..Default::default()
        })
        .await?;

    println!("BTC/USD bars: {}",
        crypto_bars.get("BTC/USD").map(|b| b.len()).unwrap_or(0));

    Ok(())
}

Market Data — Live Streaming

use alpacars::data::live::stock::StockDataStream;
use alpacars::data::enums::DataFeed;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 📡 Connect to live stock stream
    let mut stream = StockDataStream::new("API_KEY", "SECRET_KEY", DataFeed::Iex);

    stream.subscribe_trades(["AAPL", "TSLA"], |trade| {
        println!("🔔 Trade: {} @ ${} x {}", trade.symbol, trade.price, trade.size);
    });

    stream.subscribe_quotes(["AAPL"], |quote| {
        println!("💬 Quote: {} bid={} ask={}", quote.symbol, quote.bid_price, quote.ask_price);
    });

    stream.run().await?; // blocks until stream ends or error

    Ok(())
}

Real-time trade updates (fills, order status changes):

use alpacars::trading::stream::TradingStream;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut stream = TradingStream::new("API_KEY", "SECRET_KEY", true); // paper

    stream.subscribe_trade_updates(|update| {
        println!("⚡ Event: {:?}", update.event);
    });

    stream.run().await?;

    Ok(())
}

▶️ Examples

Four runnable examples are in examples/. Set your credentials, then:

# 📈 Stock trading — orders, positions, historical data
APCA_API_KEY_ID=<key> APCA_API_SECRET_KEY=<secret> cargo run --example stocks_trading_basic

# ₿ Crypto trading — BTC/USD orders, positions, crypto data
APCA_API_KEY_ID=<key> APCA_API_SECRET_KEY=<secret> cargo run --example crypto_trading_basic

# 🎯 Options trading — contract discovery, orders, exercise, snapshots
APCA_API_KEY_ID=<key> APCA_API_SECRET_KEY=<secret> cargo run --example options_trading_basic

# 🦋 Multi-leg options — straddle and iron condor
APCA_API_KEY_ID=<key> APCA_API_SECRET_KEY=<secret> cargo run --example options_trading_mleg

🧪 Running Tests

Tests use wiremock to mock HTTP responses — no real API credentials needed.

cargo test

Expected output:

test result: ok. 30 passed; 0 failed; 0 ignored

🗂️ Supported Clients

⚠️ Disclaimer

PLEASE READ CAREFULLY BEFORE USE.

alpacars is an independent, unofficial, community-maintained Rust SDK. It is not affiliated with, endorsed by, sponsored by, or in any way officially connected to Alpaca Markets or any of its subsidiaries. All trademarks, service marks, and brand names are the property of their respective owners.

No Financial Advice

Nothing in this software, its documentation, or its source code constitutes financial, investment, legal, or tax advice. This library is provided for educational and informational purposes only. Any trading strategies or examples shown are purely illustrative and do not represent a recommendation to trade any particular instrument or strategy.

Risk Warning

Trading financial instruments — including equities, options, cryptocurrencies, and other derivatives — involves substantial risk of loss and is not appropriate for all investors. Automated trading systems can malfunction, execute unintended orders, or behave unexpectedly under real market conditions.

You may lose some or all of your invested capital. Past performance is not indicative of future results.

No Warranty or Liability

This software is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement. In no event shall the authors or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including but not limited to loss of profits, loss of data, missed trades, or financial loss) arising out of or in connection with the use of this software, even if advised of the possibility of such damages.

Your Responsibility

By using this software you acknowledge that:

• You are solely responsible for all trading decisions and their outcomes.
• You have read and agree to Alpaca's Terms of Service and all applicable regulations in your jurisdiction.
• You will paper-trade thoroughly and validate all behaviour before deploying with real capital.
• Automated trading may be subject to regulatory requirements in your country — it is your responsibility to ensure compliance.

📄 License

MIT — see LICENSE.