Alpaca Broker Integration

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/llms.txt and https://docs.alpaca.markets/llms-full.txt
• 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

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

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

Auth differs by API family — this trips people up constantly.

Broker API → HTTP Basic

Authorization: Basic base64("<API_KEY_ID>:<API_SECRET_KEY>")

The same Basic credential authenticates Broker REST, Broker SSE event streams, and trading-on-behalf-of-accounts. Build the base64 token once at startup; don't recompute per request.

Market Data API → key/secret headers (or Basic in broker context)

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

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>"}

Broker API partners can usually authenticate market-data calls with their Broker Basic credentials too. Pick one scheme per data client and be consistent; mixing them is a frequent source of 401s.

Trading API → key/secret headers

Same APCA-API-* headers as market data.

Authentication API → OAuth 2.0 Bearer

For OAuth integrations, exchange the code for a token and send Authorization: Bearer <token>.

4. Three consumption styles

Alpaca gives you three transports. Use the right one for the job — and know that they have different auth and different reliability characteristics.

Key distinction: Broker events come over SSE (simple HTTP, Basic auth, replayable with since/since_id). Market data comes over WebSocket (subscribe model, auth message, ping/pong). They are different endpoints with different auth — don't conflate them.

5. Wire conventions (true across the platform)

These apply everywhere and are the source of most subtle bugs:

• Numbers are strings. Prices, quantities, notional, and money amounts come back as JSON strings ("100.50", "1.5"). Parse into a decimal type, never a binary float. See alpaca-broker-money-precision.
• IDs: account_id, order_id, journal_id, transfer_id are UUIDs. Activity IDs and newer event IDs are ULIDs — lexicographically sortable, which matters for event ordering and replay cursors.
• Idempotency: pass your own client_order_id on orders so retries don't double-fill. Records you create from events should be keyed on the Alpaca ID with upsert/skip-duplicate semantics. See alpaca-broker-reconciliation-idempotency.
• Pagination: list endpoints page forward with a token. Market-data bars return next_page_token in the body; activities return a page token via the X-Next-Page-Token response header. Loop until the token is empty.
• Rate limits: responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix seconds). On HTTP 429, wait until reset before retrying. See alpaca-broker-rate-limits-resilience.
• Timestamps: RFC3339 (e.g. 2026-01-02T15:04:05Z). SSE since/until accept RFC3339, but + in a timezone offset must be URL-encoded as %2B.
• Status ≠ done. Almost every write (account, journal, transfer, order) is asynchronous and moves through a state machine. A 200 means "accepted," not "settled." Always reconcile on the terminal status, which arrives later via event or poll.