Meta

Maintainers

Project description

# alpaca-trade-api-python

`alpaca-trade-api-python` is a python library for the Alpaca trade API.It allows rapid trading algo development easily, with support for theboth REST and streaming interfaces. For details of each API behavior,please see the online API document.

## Install

```bash$ pip install alpaca-trade-api-python```

## Example

In order to call Alpaca's trade API, you need to obtain API key pairs.Replace <key_id> and <secret_key> with what you get from theweb console.

The Alpaca API requires API key ID and secret key, which you can obtain from theweb console after you sign in. You can give them to the initializers of`REST` or `StreamConn` as arguments, or set up environment variables asfollows.

- APCA_API_KEY_ID: key ID- APCA_API_SECRET_KEY: secret key

## REST

The `REST` class is the entry point for the API request. The instance of thisclass provides all REST API calls such as account, orders, positions,bars, quotes and fundamentals.

Each returned object is wrapped by a subclass of `Entity` class (or a list of it).This helper class provides property access (the "dot notation") to thejson object, backed by the original object stored in the `_raw` field.It also converts certain types to the appropriate python object.

### REST.list_bars(symbols, timeframe, start_dt=None, end_dt=None, limit=None)Calls `GET /bars` and returns a list of `AssetBars` entities. If `symbols` isnot a string, it is concatenated with commas. `start_dt` and `end_dt` should bein the ISO8601 string format.

### REST.get_bars(symbol, timeframe, start_dt=None, end_dt=None, limit=None)Calls `GET /assets/{symbol}/bars` with parameters and returns an `AssetBars`entity. `start_dt` and `end_dt` should be in the ISO8601 string format.

## StreamConn

The `StreamConn` class provides WebSocket-based event-driveninterfaces. Using the `on` decorator of the instance, you candefine custom event handlers that are called when the patternis matched on the stream name. Once event handlers are set up,call the `run` method which runs forever until a critical exceptionis raised. This module itself does not provide any threadingcapability, so if you need to consume the messages pushed from theserver, you need to run it in a background thread.

The `run` method routine starts from establishing the WebSocketconnection, immediately followed by the authenticationhandshake. The `authenticated` event is called right after authenticationis done, where it is the best time to start subscribing to particularstreams you are interested in, by calling the `subscribe` method.

The `run` method tries to reconnect to the server in the event ofconnection failure. In this case you may want to reset your statewhich is best in the `connect` event. The method still raisesexception in the case any other unknown error happens inside theevent loop.

The `msg` object passed to each handler is wrapped by the entityhelper class if the message is from the server.

You will likely call the `run` method in a thread since it will keep runnigunless an exception is raised.

### StreamConn.subscribe(streams)Request "listen" to the server. `streams` must be a list of string stream names.A "listening" response will be triggered if server responses to this request.

### StreamConn.run()Goes into an infinite loop and awaits for messages from the server. You shouldset up event listeners using the `on` or `register` method before calling `run`.

### StreamConn.on(stream_pat)As in the above example, this is a decorator method to add an event handler function.`stream_pat` is used as a regular expression pattern to filter stream names.

### StreamConn.register(stream_pat, func)Registers a function as an event handler that is triggered by the stream eventsthat match with `stream_path` regular expression. Calling this method with thesame `stream_pat` will overwrite the old handler.