# alpaca-py replaces kwargs with a request model per endpoint

> alpaca-py is the current Python SDK for Alpaca's brokerage, market data and streaming APIs, built on pydantic request objects using a request-object design. Good for typed trading code, heavy for anyone whose workload fits a handful of REST calls.

**alpacahq/alpaca-py** — The Official Python SDK for Alpaca API

- Repository: https://github.com/alpacahq/alpaca-py
- Website: https://alpaca.markets/sdks/python/getting_started.html
- Stars: 1,558 · Forks: 417
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/alpacahq-alpaca-py

## One request model per method

The design change that matters when you move from the older SDK is structural. alpaca-py uses a more object-oriented request design than the previous SDK; you will generally need to create a request object containing the desired request data. The README states that generally there is a unique request model for each method and names two examples: `GetOrdersRequest` for `TradingClient.get_orders()`, and `CryptoLatestOrderbookRequest` for `CryptoHistoricalDataClient.get_crypto_latest_orderbook()`.

Underneath that is pydantic 2, declared in pyproject.toml alongside `requests`, `pandas`, `msgpack`, `websockets` and `sseclient-py`. Requests are validated before they leave your process, and responses are parsed into typed models rather than dicts you have to guess at. The package ships a `py.typed` marker and includes it in the distribution, so a type checker reads the models as typed.

The dependency list is worth noting for what it implies. `websockets` and `sseclient-py` mean the streaming clients are first-class rather than bolted on, and `pandas` is a hard dependency because bar data comes back as dataframes.

## Installing it and getting keys in place

The SDK requires Python 3.10 or newer, and installation is a single pip command:

```shell
pip install alpaca-py
```

To move an existing environment to the newest release, the README gives the upgrade form:

```shell
pip install alpaca-py --upgrade
```

Authentication is key pair based and environment driven. The `.env.example` file at the repository root lists exactly which variables exist, split by product:

```yaml
APCA_API_KEY_ID=
APCA_API_SECRET_KEY=
ALPACA_BROKER_API_KEY=
ALPACA_BROKER_API_SECRET=
```

The comments in that file are the part to read. It recommends paper keys for trading and market data and sandbox keys for Broker, and it documents the environment overrides `ALPACA_TRADING_PAPER=true` and `ALPACA_BROKER_SANDBOX=true` that switch modes, with paper trading on and sandbox on by default. Getting this wrong is the difference between a paper account and a live one, so check which mode your key pair belongs to before you submit an order.

The first call in the README needs no keys at all, because crypto data is public:

```python
from alpaca.data.historical import CryptoHistoricalDataClient
from alpaca.data.requests import CryptoBarsRequest
from alpaca.data.timeframe import TimeFrame

# no keys required for crypto data
client = CryptoHistoricalDataClient()
```

From there you build a `CryptoBarsRequest` with `symbol_or_symbols`, `timeframe` and `start`, which is the shape every data call follows.

## Three product surfaces in one package

The README's What is New section names three things that were not all present before: the Broker API, the object-oriented request design, and data validation, alongside support for many clients.

The README highlights Broker API support for building investment apps. Key handling differs, which is why `.env.example` keeps `ALPACA_BROKER_API_KEY` separate from `APCA_API_KEY_ID`.

Market data and trading are the other two surfaces, for equities, options and crypto, with streaming over WebSocket and server-sent events on top of the REST endpoints. The repository's `examples/` directory shows the shape of real usage: `stocks-trading-basic.ipynb`, `crypto-trading-basic.ipynb`, `options-trading-basic.ipynb` and `options-trading-mleg.ipynb`, plus plain directories for `crypto/`, `options/` and `stocks/`.

Two environment variables are for the test suite rather than the SDK, and they tell you how the project checks itself: `ALPACA_RUN_LIVE=1` as an alternative gate to the pytest live run, and `ALPACA_LIVE_STREAM_TIMEOUT` with `ALPACA_LIVE_OPTION_SYMBOL` as streaming probe settings.

## There is an API breakage check in the build

The Makefile contains a target that most SDK repositories do not:

```bash
make check-api-breakage
```

It runs `tools/scripts/compare_api_breakage.py` with `--fail-on-breaking`, optionally against a published release with `AGAINST=version`. In practice that means the maintainers compare the public API of the working tree with a shipped version and fail the build when something that existed before has disappeared or changed incompatibly.

That is a design decision about how this SDK evolves, and it is relevant to you because it tells you what to expect. Interface changes are treated as a tracked, checkable event rather than something that happens quietly between minor versions. The tagged releases reflect that pace: v0.44.0 on 2026-08-11, v0.43.5 on 2026-07-02, v0.43.4 on 2026-04-29. The project sits below 1.0, so minor bumps are where the movement happens.

The version in pyproject.toml is a placeholder, `0.0.0`, and the real version is substituted at build time by poetry-dynamic-versioning with substitution into the `alpaca` folder. That is a reminder that the version you see in the repository is not the version you install.

## The costs of a typed, heavyweight SDK

There are places where this SDK is the wrong tool, and they are structural rather than fixable.

The dependency weight is real. pandas comes along whether or not you touch a dataframe, and the websocket and SSE clients load regardless. For a cron job that fetches one price, pulling in a trading stack to make a single authenticated GET is more surface than the job needs.

The object model is the second cost. Every endpoint needs a request class, so a script that would be three lines with `requests` becomes an import, a construction and a client call. That is the right trade for a codebase with several people and typed models, and the wrong one for a notebook or a glue script.

Where the SDK stops is also worth stating. It talks to Alpaca's API and nothing else, and it will not talk to your broker. Market data is Alpaca's, orders go to Alpaca's brokerage, and the accounts are Alpaca accounts. Anyone wanting the same shape against a different venue has to write the request models themselves.

Maintenance and licensing: the last push was on 2026-10-16 and the repository is not archived, with the default branch `master`. The license is Apache-2.0, which carries an explicit patent grant and requires preserving notices if you redistribute the SDK, though that is a statement about the license text rather than advice about your deployment. The docs site is built with Sphinx in a Dockerfile that ends on `nginx:alpine`, and `make generate` rebuilds it through `tools/scripts/generate-docs.sh`.

## Conclusion

Adopt alpaca-py for new work against Alpaca's APIs, especially if you want streaming and the Broker API in one typed package, and pin the version since the tags move often. Do not port an existing alpaca-trade-api codebase just for style, because the request-object rewrite touches every call site, and do not add it to a project that only needs a scheduled REST query. Verify first that your Python is 3.10 or newer, that the paper environment is what you think it is by checking the APCA_API_KEY_ID pair in .env.example, and that the release you pin still has the endpoint you call.

## FAQ

### How do I install alpaca-py?

Run `pip install alpaca-py`, or `pip install alpaca-py --upgrade` to move an existing installation to the latest version. The SDK requires Python 3.10 or newer.

### How do I authenticate with alpaca-py?

The .env.example file shows the variables: APCA_API_KEY_ID and APCA_API_SECRET_KEY for trading and market data, ALPACA_BROKER_API_KEY and ALPACA_BROKER_API_SECRET for Broker. Crypto historical data needs no keys at all.

### What is the difference between alpaca-py and alpaca-trade-api?

alpaca-py uses a more object-oriented request design than alpaca-trade-api, generally with a unique request model for each method, such as GetOrdersRequest for TradingClient.get_orders(). It also adds Broker API support.

### Does alpaca-py support streaming market data?

Yes. The package depends on websockets and sseclient-py, and the README describes Alpaca's products as REST, WebSocket and SSE endpoints covering streaming market data through to building investment apps.

## Sources

- [alpacahq/alpaca-py on GitHub](https://github.com/alpacahq/alpaca-py)
- [License: Apache-2.0](https://github.com/alpacahq/alpaca-py/blob/master/LICENSE)
- [Project website](https://alpaca.markets/sdks/python/getting_started.html)
- [README](https://github.com/alpacahq/alpaca-py/blob/master/README.md)
- [Releases](https://github.com/alpacahq/alpaca-py/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alpacahq-alpaca-py