> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trading with Alpaca

> Connect Alpaca paper and live accounts to Scalar Field — OAuth connection, US equities and options order semantics, asynchronous fills, and the research data functions available for equity and options strategies.

<Info>**Execution:** `venue.trade()` in chat code, `strategy.execute()` in strategy agents.</Info>

# Overview

Alpaca connects to Scalar Field via OAuth and provides two accounts: `ALPACA_PAPER` (simulated money) and `ALPACA_LIVE` (real money). Both support US equities, ETFs, and options, with identical call semantics — strategy code validated on paper runs unchanged against live.

| Specification | Value                                                     |
| ------------- | --------------------------------------------------------- |
| Instruments   | US equities, ETFs, and options (OPRA/OSI symbols)         |
| Accounts      | `ALPACA_PAPER`, `ALPACA_LIVE`                             |
| Connection    | OAuth                                                     |
| Fractional    | Yes (equities)                                            |
| Hours         | US market hours; off-hours orders queue for the next open |
| Fill model    | Asynchronous — orders may return `PENDING`                |
| Quotes        | Last, bid, ask, volume (no order-book depth)              |
| Currency      | USD                                                       |

# Order Semantics

* **Equity symbols are plain tickers** (`AAPL`); **options use OPRA/OSI symbols** (`AAPL260919C00250000`). Option positions carry `multiplier: 100`, so `market_value = qty * price * 100`.
* **Fills are asynchronous.** `venue.trade()` may return `"PENDING"` — the order is submitted but not yet filled. Orders use `day` time-in-force; orders placed outside market hours remain `PENDING` until the next open. Pending orders are reconciled automatically (see [Reconciliation](/trading/reconciliation)).
* **Fractional quantities are supported** for equities. Size from a dollar budget with `round(budget / price, 2)`.
* The `slippage_bps` parameter does not apply to Alpaca.

# Connecting

Click "Connect" on the portfolio page and authorize with your Alpaca account. Paper and live accounts link through the same OAuth flow.

# Usage

```python theme={null}
from scalarlib import venue

# Equities on paper
resp = venue.trade("buy", "AAPL", 5, account="ALPACA_PAPER")

# Same call against the live account
resp = venue.trade("buy", "AAPL", 1.5, account="ALPACA_LIVE")

# Options by OPRA symbol
resp = venue.trade("buy", "AAPL260919C00250000", 1, account="ALPACA_PAPER")
```

In strategy agents, use `strategy.execute(symbol, target_qty)` instead — see [Strategies](/trading/strategies).

# Data Functions

Equity and options research uses the cross-asset market-data functions; each links to its full reference:

| Function / dataset                                            | Purpose                                                  |
| ------------------------------------------------------------- | -------------------------------------------------------- |
| [Equity & ETF OHLCV](/market-data/equity-ohlcv)               | Historical price bars for backtesting and signals        |
| [Latest Price Snapshot](/market-data/latest-price)            | Live last/bid/ask quotes for sizing and execution checks |
| [Options Quotes](/market-data/options-quotes)                 | Options chains and quotes                                |
| [Options Greeks & IV](/market-data/options-greeks)            | Greeks and implied volatility                            |
| [Options Screener](/market-data/screen-options)               | Contract screening by moneyness, expiry, volume          |
| [Earnings](/market-data/earnings)                             | Earnings calendar and results                            |
| [Insider Trades](/market-data/insider-trades)                 | SEC Form 4 insider transactions                          |
| [Institutional Holdings](/market-data/institutional-holdings) | 13F institutional positions                              |

# Notes

* Positions and cash update only on terminal order states (filled, cancelled, expired); partial fills on a live order are not reflected until the order is terminal.
* A `PENDING` response outside market hours is normal — the order executes at the next open.
* Avoid trading directly on the Alpaca dashboard while strategies are active on the account — see [Reconciliation](/trading/reconciliation).

# Related

* [Strategies](/trading/strategies) — automated strategy execution
* [Reconciliation](/trading/reconciliation) — pending order tracking and position sync
* [Supported Venues](/trading/supported-brokerages) — venue registry and `venue.*` functions