/integration

name: alpaca-broker-integration
description: Entry point for integrating with the Alpaca Broker API (plus Market Data and Trading APIs) in any programming language. Use when a developer wants to build on Alpaca — open brokerage accounts, run KYC, fund accounts, move money via journals, place orders, consume real-time event streams, or pull market data — and need to know base URLs, auth, conventions, or which focused sub-skill to use.

Alpaca Integration Assistant

You are an expert on the **Alpaca** APIs. Help developers integrate with Alpaca in **any programming language**. Generate working code, explain protocols, and debug integration issues.

This is the **router / overview** skill. It covers the things that are true across *all* of Alpaca's APIs — the API families, base URLs, auth, consumption styles, and wire conventions — and points you to a focused sub-skill for each domain. Read this first, then jump to the specific skill for the task.

> Most of the hard-won value in these skills is in the **lessons-learned** sub-skills (reconciliation, rate limits, money precision, SSE reliability). Alpaca's reference docs tell you *what* the endpoints are; these skills tell you *what breaks in production and why*.

---

Reference Documentation

• Docs home: `https://docs.alpaca.markets/`
• API reference: `https://docs.alpaca.markets/reference/`
• Machine-readable index: `https://docs.alpaca.markets/us/llms.txt` (the root `llms.txt` is the India/GIFT City index; `llms-full.txt` redirects to the docs home)
• OpenAPI specs (4): **Authentication API**, **Broker API**, **Market Data API**, **Trading API**

**Live schema lookups:** if the `alpaca-docs` MCP server is connected, prefer it over guessing — `list-specs`, `list-endpoints`, `get-endpoint` (exact request/response schemas + servers), and `search` / `fetch` (guide pages). Always confirm an exact payload against the spec before generating code that posts money or orders.

---

1. The four API families

| Family | What it's for | Who uses it | |--------|---------------|-------------| | **Broker API** | Open & manage brokerage accounts on behalf of *your* end users (KYC, funding, journals, trading-for-accounts, documents, events). You are the broker-of-record's tech partner; you custody many sub-accounts under your firm. | Apps that onboard their own users and hold their assets (neobrokers, fintechs). | | **Trading API** | Trade a *single* account that belongs to the API-key holder. | Individual algo traders, bots. | | **Market Data API** | Real-time + historical prices, bars, quotes, trades, news, corporate actions, screener. REST and WebSocket. | Everyone. | | **Authentication API** | Issues access tokens: `client_credentials` for your own machine-to-machine calls, plus OAuth 2.0 flows for letting third parties act on an Alpaca account. | Every Broker partner; OAuth integrations. |

**Decide first which family you're on — it changes the base URL, the auth, and the URL shape of every call.** The most common confusion: Broker API places orders at `/v1/trading/accounts/{account_id}/orders` (the account is in the path because you act *for* a user), whereas the standalone Trading API places orders at `/v2/orders` (implicitly *your own* account).

These skills focus primarily on the **Broker API**, because that's where the lifecycle is hardest: onboarding, funding rails, journals, and event reconciliation.

---

2. Base URLs

| Family | Production | Sandbox / Paper | |--------|-----------|-----------------| | **Broker API** | `https://broker-api.alpaca.markets` | `https://broker-api.sandbox.alpaca.markets` | | **Trading API** | `https://api.alpaca.markets` | `https://paper-api.alpaca.markets` (paper) | | **Market Data (REST)** | `https://data.alpaca.markets` | `https://data.sandbox.alpaca.markets` | | **Market Data (WebSocket)** | `wss://stream.data.alpaca.markets` | `wss://stream.data.sandbox.alpaca.markets` |

**Always start in sandbox.** Switch by environment variable, never by code path — a single `ENV` flag that selects the base URL is the pattern that survives. Sandbox accounts can be funded with fake money and auto-approved, so you can exercise the full lifecycle without real KYC or cash.

---

3. Authentication

Client credentials → Bearer token (Broker API, and Broker partners calling Market Data)

POST https://authx.alpaca.markets/v1/oauth2/token
     (sandbox: https://authx.sandbox.alpaca.markets/v1/oauth2/token)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

The secret goes in the **body** (`client_secret_post`), not in an `Authorization` header. The response is `{"access_token": "…", "expires_in": 899, "token_type": "Bearer"}` — tokens are valid **15 minutes**. Send it as `Authorization: Bearer <token>`.

Documented for the Broker API, and for Broker partners calling Market Data over both REST and WebSocket. On the WebSocket the auth message uses the literal key `access_token`:

{"action": "auth", "key": "access_token", "secret": "<ACCESS_TOKEN>"}

Not yet available for the Trading API.

**Cache the token per process and refresh before expiry** — around 12 of the 15 minutes. Hold it behind one accessor that can refresh, not a startup constant. Treat a `401` on a long-lived call as *refresh and retry once* before treating it as bad credentials; whether an already-open SSE stream survives token expiry is not documented.

Legacy key/secret → still supported, and the only path for Trading API

APCA-API-KEY-ID: <API_KEY_ID>
APCA-API-SECRET-KEY: <API_SECRET_KEY>

Broker also accepts `Authorization: Basic base64("<API_KEY_ID>:<API_SECRET_KEY>")` on REST and SSE. The Trading API uses the `APCA-API-*` headers only. For the WebSocket data stream you don't use headers — you send an auth message *after* connecting:

{"action": "auth", "key": "<API_KEY_ID>", "secret": "<API_SECRET_KEY>"}

> Pick one