# Coinbase Advanced API Python SDK
[](https://badge.fury.io/py/coinbase-advanced-py)
[](https://opensource.org/license/apache-2-0/)
[](https://black.readthedocs.io/en/stable/)
Welcome to the official Coinbase Advanced API Python SDK. This python project was created to allow coders to easily plug into the [Coinbase Advanced API](https://docs.cdp.coinbase.com/advanced-trade/docs/welcome).
This SDK also supports easy connection to the [Coinbase Advanced Trade WebSocket API](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview).
Coinbase Advanced Trade offers a comprehensive API for traders, providing access to real-time market data, order management, and execution. Elevate your trading strategies and develop sophisticated solutions using our powerful tools and features.
For thorough documentation of all available functions, refer to the following link: https://coinbase.github.io/coinbase-advanced-py
___
## Installation
```bash
pip3 install coinbase-advanced-py
```
___
## Coinbase Developer Platform (CDP) API Keys
This SDK uses Cloud Developer Platform (CDP) API keys. To use this SDK, you will need to create a CDP API key and secret by following the instructions [here](https://docs.cdp.coinbase.com/advanced-trade/docs/getting-started).
Make sure to save your API key and secret in a safe place. You will not be able to retrieve your secret again.
WARNING: We do not recommend that you save your API secrets directly in your code outside of testing purposes. Best practice is to use a secrets manager and access your secrets that way. You should be careful about exposing your secrets publicly if posting code that leverages this library.
Optional: Set your API key and secret in your environment (make sure to put these in quotation marks). For example:
```bash
export COINBASE_API_KEY="organizations/{org_id}/apiKeys/{key_id}"
export COINBASE_API_SECRET="-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
```
___
## REST API Client
In your code, import the RESTClient class and instantiate it:
```python
from coinbase.rest import RESTClient
client = RESTClient() # Uses environment variables for API key and secret
```
If you did not set your API key and secret in your environment, you can pass them in as arguments:
```python
from coinbase.rest import RESTClient
api_key = "organizations/{org_id}/apiKeys/{key_id}"
api_secret = "-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
client = RESTClient(api_key=api_key, api_secret=api_secret)
```
After creating your API key, a json file will be downloaded to your computer. It's possible to pass in the path to this file as an argument:
```python
client = RESTClient(key_file="path/to/cdp_api_key.json")
```
We also support passing a file-like object as the `key_file` argument:
```python
from io import StringIO
client = RESTClient(key_file=StringIO('{"name": "key-name", "privateKey": "private-key"}'))
```
You can also set a timeout in seconds for your REST requests like so:
```python
client = RESTClient(api_key=api_key, api_secret=api_secret, timeout=5)
```
### Using the REST Client
You are able to use any of the API hooks to make calls to the Coinbase API. For example:
```python
from json import dumps
accounts = client.get_accounts()
print(dumps(accounts.to_dict(), indent=2))
order = client.market_order_buy(client_order_id="clientOrderId", product_id="BTC-USD", quote_size="1")
print(dumps(order.to_dict(), indent=2))
```
This code calls the `get_accounts` and `market_order_buy` endpoints.
TIP: Setting `client_order_id` to the empty string will auto generate a unique client_order_id per call.
However, this will remove the intended safeguard of accidentally placing duplicate orders.
Refer to the [Advanced API Reference](https://docs.cdp.coinbase.com/advanced-trade/reference) for detailed information on each exposed endpoint.
Look in the `coinbase.rest` module to see the API hooks that are exposed.
### Custom Response Objects
Endpoints will return corresponding, custom class objects. This allows you to retrieve response object fields using dot-notation. Here is an example of how you can access a product's price via the Get Product endpoint:
```python
product = client.get_product("BTC-USD")
print(product.price)
```
Dot-notation is only available for fields that are defined. Although all higher-level fields have been defined, not every nested field has. Fields that are not defined are still accessible using standard bracket notation.
For example, we make a call to List Accounts. We take the first account from the defined `accounts` field and access the defined `available_balance` field. Despite its nested fields not being explicitly defined and inaccessible via dot-notation, we can still access them manually using bracket notation, like:
```python
accounts = client.get_accounts()
print(accounts.accounts[0].available_balance['value'])
```
### Passing in additional parameters
Use `kwargs` to pass in any additional parameters. For example:
```python
kwargs = {
"param1": 10,
"param2": "mock_param"
}
product = client.get_product(product_id="BTC-USD", **kwargs)
```
### Generic REST Calls
You can make generic REST calls using the `get`, `post`, `put`, and `delete` methods. For example:
```python
market_trades = client.get("/api/v3/brokerage/products/BTC-USD/ticker", params={"limit": 5})
portfolio = client.post("/api/v3/brokerage/portfolios", data={"name": "TestPortfolio"})
```
Here we are calling the [GetMarketTrades](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getmarkettrades) and [CreatePortfolio](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_createportfolio) endpoints through the generic REST functions.
Once again, the built-in way to query these through the SDK would be:
```python
market_trades = client.get_market_trades(product_id="BTC-USD", limit=5)
portfolio = client.create_portfolio(name="TestPortfolio")
```
### Rate Limit Response Headers
The Advanced API returns useful rate limit information in the response headers as detailed in our [documentation](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-rate-limits#private-endpoints). By initializing the RESTClient with the `rate_limit_headers` field set to True, as shown below, these headers will be appended as fields to the API response body:
```python
client = RESTClient(api_key=api_key, api_secret=api_secret, rate_limit_headers=True)
```
___
## WebSocket API Client
We offer a WebSocket API client that allows you to connect to the [Coinbase Advanced Trade WebSocket API](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview).
Refer to the [Advanced Trade WebSocket Channels](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels) page for detailed information on each offered channel.
In your code, import the WSClient class and instantiate it. The WSClient requires an API key and secret to be passed in as arguments. You can also use a key file or environment variables as described in the RESTClient instructions above.
You must specify an `on_message` function that will be called when a message is received from the WebSocket API. This function must take in a single argument, which will be the raw message received from the WebSocket API. For example:
```python
from coinbase.websocket import WSClient
api_key = "organizations/{org_id}/apiKeys/{key_id}"
api_secret = "-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
def on_message(msg):
print(msg)
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message)
```
In this example, the `on_message` function simply prints the message received from the WebSocket API.
You can also set a `timeout` in seconds for your WebSocket connection, as well as a `max_size` in bytes for the messages received from the WebSocket API.
```python
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, timeout=5, max_size=65536) # 64 KB max_size
```
Other configurable fields are the `on_open` and `on_close` functions. If provided, these are called when the WebSocket connection is opened or closed, respectively. For example:
```python
def on_open():
print("Connection opened!")
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, on_open=on_open)
```
### WebSocket User API Client
We offer a WebSocket User API client that allows you to connect to the Coinbase Advanced Trade WebSocket [user channel](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#user-channel) and [futures_balance_summary channel](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#futures-balance-summary-channel).
In your code, import the WSUserClient class instead of WSClient.
```python
from coinbase.websocket import WSUserClient
api_key = "organizations/{org_id}/apiKeys/{key_id}"
api_secret = "-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
def on_message(msg):
print(msg)
client = WSUserClient(api_key=api_key, api_secret=api_secret, on_message=on_message)
```
### Using the WebSocket Client
Once you have instantiated the client, you can connect to the WebSocket API by calling the `open` method, and disconnect by calling the `close` method.
The `subscribe` method allows you to subscribe to specific channels, for specific products. Similarly, the `unsubscribe` method allows you to unsubscribe from specific channels, for specific products. For example:
```python
# open the connection and subscribe to the ticker and heartbeat channels for BTC-USD and ETH-USD
client.open()
client.subscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker", "heartbeats"])
# wait 10 seconds
time.sleep(10)
# unsubscribe from the ticker channel and heartbeat channels for BTC-USD and ETH-USD, and close the connection
client.unsubscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker", "heartbeats"])
client.close()
```
We also provide channel specific methods for subscribing and unsubscribing. For example, the below code is equivalent to the example from above:
```python
client.open()
client.ticker(product_ids=["BTC-USD", "ETH-USD"])
client.heartbeats(product_ids=["BTC-USD", "ETH-USD"])
# wait 10 seconds
time.sleep(10)
client.ticker_unsubscribe(product_ids=["BTC-USD", "ETH-USD"])
client.heartbeats_unsubscribe(product_ids=["BTC-USD", "ETH-USD"])
client.close()
```
### Automatic Reconnection to the WebSocket API
The WebSocket client will automatically attempt to reconnect the WebSocket API if the connection is lost, and will resubscribe to any channels that were previously subscribed to.
The client uses an exponential backoff algorithm to determine how long to wait before attempting to reconnect, with a maximum number of retries of 5.
If you do not want to automatically reconnect, you can set the `retry` argument to `False` when instantiating the client.
```python
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, retry=False)
```
### Catching WebSocket Exceptions
The WebSocket API client will raise exceptions if it encounters an error. On forced disconnects it will raise a `WSClientConnectionClosedException`, otherwise it will raise a `WSClientException`.
NOTE: Errors on forced disconnects, or within logic in the message handler, will not be automatically raised since this will be running on its own thread.
We provide the `sleep_with_exception_check` and `run_forever_with_exception_check` methods to allow you to catch these exceptions. `sleep_with_exception_check` will sleep for the specified number of seconds, and will check for any exception raised during that time. `run_forever_with_exception_check` will run forever, checking for exceptions every second. For example:
```python
from coinbase.websocket import (WSClient, WSClientConnectionClosedException,
WSClientException)
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message)
try:
client.open()
client.subscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker", "heartbeats"])
client.run_forever_with_exception_check()
except WSClientConnectionClosedException as e:
print("Connection closed! Retry attempts exhausted.")
except WSClientException as e:
print("Error encountered!")
```
This code will open the connection, subscribe to the ticker and heartbeat channels for BTC-USD and ETH-USD, and will sleep forever, checking for exceptions every second. If an exception is raised, it will be caught and handled appropriately.
If you only want to run for 5 seconds, you can use `sleep_with_exception_check`:
```python
client.sleep_with_exception_check(sleep=5)
```
Note that if the automatic reconnection fails after the retry limit is reached, a `WSClientConnectionClosedException` will be raised.
If you wish to implement your own reconnection logic, you can catch the `WSClientConnectionClosedException` and handle it appropriately. For example:
```python
client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, retry=False)
def connect_and_subscribe():
try:
client.open()
client.subscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker", "heartbeats"])
client.run_forever_with_exception_check()
except WSClientConnectionClosedException as e:
print("Connection closed! Sleeping for 20 seconds before reconnecting...")
time.sleep(20)
connect_and_subscribe()
```
### Async WebSocket Client
The functions described above handle the asynchronous nature of WebSocket connections for you. However, if you wish to handle this yourself, you can use the `async_open`, `async_subscribe`, `async_unsubscribe`, and `async_close` methods.
We similarly provide async channel specific methods for subscribing and unsubscribing such as `ticker_async`, `ticker_unsubscribe_async`, etc.
### WebSocket Response Types
For your convenience, we have provided a custom, built-in WebSocket response type object to help interact with our WebSocket feeds more easily.
Simply import it from the same module as you do the `WSClient`:
```python
from coinbase.websocket import WSClient, WebsocketResponse
```
Assume we simply want the price feed for BTC-USD and ETH-USD.
Like we did in previous steps, we subscribe to the `ticker` channel and include 'BTC-USD' and 'ETH-USD' in the `product_ids` list.
As the data comes through, it is passed into the `on_message` function. From there, we use it to build the `WebsocketResponse` object.
Using said object, we can now extract only the desired parts. In our case, we retrieve and print only the `product_id` and `price` fields, resulting in a cleaner feed.
```python
from coinbase.websocket import WSClient, WebsocketResponse
def on_message(msg):
ws_object = WebsocketResponse(json.loads(msg))
if ws_object.channel == "ticker" :
for event in ws_object.events:
for ticker in event.tickers:
print(ticker.product_id + ": " + ticker.price)
client.open()
client.subscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker"])
time.sleep(10)
client.unsubscribe(product_ids=["BTC-USD", "ETH-USD"], channels=["ticker"])
client.close()
```
#### Avoiding errors
In the example, note how we first checked `if ws_object.channel == "ticker"`.
Since each channel's event field has a unique structure and set of fields, it's important to ensure that the fields we access are actually present in the object.
For example, if we were to subscribe to the `user` channel and try to access a field that does not exist in it, such as the `tickers` field, we would be met with an error.
Therefore, we urge users to reference our [documentation](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels), which outlines the JSON object that each channel will return.
___
## Debugging the Clients
You can enable debug logging for the REST and WebSocket clients by setting the `verbose` variable to `True` when initializing the clients. This will log useful information throughout the lifecycle of the REST request or WebSocket connection, and is highly recommended for debugging purposes.
```python
rest_client = RESTClient(api_key=api_key, api_secret=api_secret, verbose=True)
ws_client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, verbose=True)
```
___
## Authentication
Authentication of CDP API Keys is handled automatically by the SDK when making a REST request or sending a WebSocket message.
However, if you wish to handle this yourself, you must create a JWT token and attach it to your request as detailed in the API docs [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-auth#making-requests). Use the built in `jwt_generator` to create your JWT token. For example:
```python
from coinbase import jwt_generator
api_key = "organizations/{org_id}/apiKeys/{key_id}"
api_secret = "-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
uri = "/api/v3/brokerage/orders"
jwt_uri = jwt_generator.format_jwt_uri("POST", uri)
jwt = jwt_generator.build_rest_jwt(jwt_uri, api_key, api_secret)
```
This will create a JWT token for the POST `/api/v3/brokerage/orders` endpoint. Pass this JWT token in the `Authorization` header of your request as:
`
"Authorization": "Bearer " + jwt
`
You can also generate JWTs to use with the Websocket API. These do not require passing a specific URI. For example:
```python
from coinbase import jwt_generator
api_key = "organizations/{org_id}/apiKeys/{key_id}"
api_secret = "-----BEGIN EC PRIVATE KEY-----\nYOUR PRIVATE KEY\n-----END EC PRIVATE KEY-----\n"
jwt = jwt_generator.build_ws_jwt(api_key, api_secret)
```
Use this JWT to connect to the Websocket API by setting it in the "jwt" field of your subscription requests. See the docs [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview#sending-messages-with-cdp-keys) for more details.
___
## Accessing public endpoints without authentication
Both clients contain public endpoints which can be accessed without authentication.
To do so, simply initialize the clients without providing any API keys as arguments.
**_Notes:_**
- Making calls to private endpoints or channels while unauthenticated will return an error
- Unauthenticated requests are rate-limited more aggressively. Because of this we recommend that you authenticate your requests
### REST Client
In the REST client, here is an example calling [Get Public Products](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getpublicproducts).
It does _not_ require authentication and is the public counterpart to
[Get Products](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getproducts), which _does_ require authentication.
Both endpoints return the same data.
```
from coinbase.rest import RESTClient
client = RESTClient()
public_products = client.get_public_products()
print(json.dumps(public_products.to_dict(), indent=2))
```
_Full list of all public REST endpoints [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-overview#public-endpoints)_
_Rate limit details for REST endpoints [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-rate-limits)_
### Websocket Client
In the Websocket client, here is an example subscribing to the [ticker](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#ticker-channel) channel.
Unlike the REST client, Websocket channels handle both authenticated and unauthenticated requests.
At the moment, most channels in the Websocket client are public and can be used without keys.
```
import time
from coinbase.websocket import WSClient
def on_message(msg):
print(msg)
client = WSClient(on_message=on_message)
client.open()
client.ticker(product_ids=["BTC-USD"])
time.sleep(10)
client.ticker_unsubscribe(product_ids=["BTC-USD"])
client.close()
```
_Full list of all public Websocket channels [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels)_
_Rate limit details for Websocket channels [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-rate-limits)_
___
## Changelog
For a detailed list of changes, see the [Changelog](https://github.com/coinbase/coinbase-advanced-py/blob/master/CHANGELOG.md).
___
## Contributing
If you've found a bug within this project, open an issue on this repo and add the "bug" label to it.
If you would like to request a new feature, open an issue on this repo and add the "enhancement" label to it.
Direct concerns or questions on the API to the [Advanced API Discord](https://discord.com/channels/1220414409550336183/1220464268743278613) (use this [invite link](https://discord.com/invite/cdp) if it's your first time accessing the Discord).
Raw data
{
"_id": null,
"home_page": "https://github.com/coinbase/coinbase-advanced-py",
"name": "coinbase-advanced-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Coinbase, Advanced Trade, API, Advanced API",
"author": "Coinbase",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2b/ee/c5b00a351f7f33f6691cddcb313770f360dafddc1b72ca83e13b74064085/coinbase-advanced-py-1.8.1.tar.gz",
"platform": null,
"description": "# Coinbase Advanced API Python SDK\n[](https://badge.fury.io/py/coinbase-advanced-py)\n[](https://opensource.org/license/apache-2-0/)\n[](https://black.readthedocs.io/en/stable/)\n\nWelcome to the official Coinbase Advanced API Python SDK. This python project was created to allow coders to easily plug into the [Coinbase Advanced API](https://docs.cdp.coinbase.com/advanced-trade/docs/welcome).\nThis SDK also supports easy connection to the [Coinbase Advanced Trade WebSocket API](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview).\n\nCoinbase Advanced Trade offers a comprehensive API for traders, providing access to real-time market data, order management, and execution. Elevate your trading strategies and develop sophisticated solutions using our powerful tools and features.\n\nFor thorough documentation of all available functions, refer to the following link: https://coinbase.github.io/coinbase-advanced-py\n\n___\n## Installation\n\n```bash\npip3 install coinbase-advanced-py\n```\n\n___\n## Coinbase Developer Platform (CDP) API Keys\n\nThis SDK uses Cloud Developer Platform (CDP) API keys. To use this SDK, you will need to create a CDP API key and secret by following the instructions [here](https://docs.cdp.coinbase.com/advanced-trade/docs/getting-started).\nMake sure to save your API key and secret in a safe place. You will not be able to retrieve your secret again.\n\nWARNING: We do not recommend that you save your API secrets directly in your code outside of testing purposes. Best practice is to use a secrets manager and access your secrets that way. You should be careful about exposing your secrets publicly if posting code that leverages this library.\n\nOptional: Set your API key and secret in your environment (make sure to put these in quotation marks). For example:\n```bash\nexport COINBASE_API_KEY=\"organizations/{org_id}/apiKeys/{key_id}\"\nexport COINBASE_API_SECRET=\"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n```\n\n___\n## REST API Client\nIn your code, import the RESTClient class and instantiate it:\n```python\nfrom coinbase.rest import RESTClient\n\nclient = RESTClient() # Uses environment variables for API key and secret\n```\nIf you did not set your API key and secret in your environment, you can pass them in as arguments:\n```python\nfrom coinbase.rest import RESTClient\n\napi_key = \"organizations/{org_id}/apiKeys/{key_id}\"\napi_secret = \"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n\nclient = RESTClient(api_key=api_key, api_secret=api_secret)\n```\nAfter creating your API key, a json file will be downloaded to your computer. It's possible to pass in the path to this file as an argument:\n```python\nclient = RESTClient(key_file=\"path/to/cdp_api_key.json\")\n```\nWe also support passing a file-like object as the `key_file` argument:\n```python\nfrom io import StringIO\nclient = RESTClient(key_file=StringIO('{\"name\": \"key-name\", \"privateKey\": \"private-key\"}'))\n```\nYou can also set a timeout in seconds for your REST requests like so:\n```python\nclient = RESTClient(api_key=api_key, api_secret=api_secret, timeout=5)\n```\n\n### Using the REST Client\n\nYou are able to use any of the API hooks to make calls to the Coinbase API. For example:\n```python\nfrom json import dumps\n\naccounts = client.get_accounts()\nprint(dumps(accounts.to_dict(), indent=2))\n\norder = client.market_order_buy(client_order_id=\"clientOrderId\", product_id=\"BTC-USD\", quote_size=\"1\")\nprint(dumps(order.to_dict(), indent=2))\n```\nThis code calls the `get_accounts` and `market_order_buy` endpoints.\n\nTIP: Setting `client_order_id` to the empty string will auto generate a unique client_order_id per call.\nHowever, this will remove the intended safeguard of accidentally placing duplicate orders.\n\nRefer to the [Advanced API Reference](https://docs.cdp.coinbase.com/advanced-trade/reference) for detailed information on each exposed endpoint.\nLook in the `coinbase.rest` module to see the API hooks that are exposed.\n\n### Custom Response Objects\nEndpoints will return corresponding, custom class objects. This allows you to retrieve response object fields using dot-notation. Here is an example of how you can access a product's price via the Get Product endpoint:\n```python\nproduct = client.get_product(\"BTC-USD\")\nprint(product.price)\n```\nDot-notation is only available for fields that are defined. Although all higher-level fields have been defined, not every nested field has. Fields that are not defined are still accessible using standard bracket notation. \n\nFor example, we make a call to List Accounts. We take the first account from the defined `accounts` field and access the defined `available_balance` field. Despite its nested fields not being explicitly defined and inaccessible via dot-notation, we can still access them manually using bracket notation, like:\n```python\naccounts = client.get_accounts()\nprint(accounts.accounts[0].available_balance['value'])\n```\n\n### Passing in additional parameters\nUse `kwargs` to pass in any additional parameters. For example:\n```python\nkwargs = {\n \"param1\": 10,\n \"param2\": \"mock_param\"\n}\nproduct = client.get_product(product_id=\"BTC-USD\", **kwargs)\n```\n\n### Generic REST Calls\nYou can make generic REST calls using the `get`, `post`, `put`, and `delete` methods. For example:\n```python\nmarket_trades = client.get(\"/api/v3/brokerage/products/BTC-USD/ticker\", params={\"limit\": 5})\n\nportfolio = client.post(\"/api/v3/brokerage/portfolios\", data={\"name\": \"TestPortfolio\"})\n```\nHere we are calling the [GetMarketTrades](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getmarkettrades) and [CreatePortfolio](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_createportfolio) endpoints through the generic REST functions.\nOnce again, the built-in way to query these through the SDK would be:\n```python\nmarket_trades = client.get_market_trades(product_id=\"BTC-USD\", limit=5)\n\nportfolio = client.create_portfolio(name=\"TestPortfolio\")\n```\n\n### Rate Limit Response Headers\nThe Advanced API returns useful rate limit information in the response headers as detailed in our [documentation](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-rate-limits#private-endpoints). By initializing the RESTClient with the `rate_limit_headers` field set to True, as shown below, these headers will be appended as fields to the API response body:\n```python\nclient = RESTClient(api_key=api_key, api_secret=api_secret, rate_limit_headers=True)\n```\n\n___\n## WebSocket API Client\nWe offer a WebSocket API client that allows you to connect to the [Coinbase Advanced Trade WebSocket API](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview).\nRefer to the [Advanced Trade WebSocket Channels](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels) page for detailed information on each offered channel.\n\nIn your code, import the WSClient class and instantiate it. The WSClient requires an API key and secret to be passed in as arguments. You can also use a key file or environment variables as described in the RESTClient instructions above.\n\nYou must specify an `on_message` function that will be called when a message is received from the WebSocket API. This function must take in a single argument, which will be the raw message received from the WebSocket API. For example:\n```python\nfrom coinbase.websocket import WSClient\n\napi_key = \"organizations/{org_id}/apiKeys/{key_id}\"\napi_secret = \"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n\ndef on_message(msg):\n print(msg)\n\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message)\n```\nIn this example, the `on_message` function simply prints the message received from the WebSocket API.\n\nYou can also set a `timeout` in seconds for your WebSocket connection, as well as a `max_size` in bytes for the messages received from the WebSocket API.\n```python\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, timeout=5, max_size=65536) # 64 KB max_size\n```\nOther configurable fields are the `on_open` and `on_close` functions. If provided, these are called when the WebSocket connection is opened or closed, respectively. For example:\n```python\ndef on_open():\n print(\"Connection opened!\")\n\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, on_open=on_open)\n```\n### WebSocket User API Client\nWe offer a WebSocket User API client that allows you to connect to the Coinbase Advanced Trade WebSocket [user channel](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#user-channel) and [futures_balance_summary channel](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#futures-balance-summary-channel).\n\nIn your code, import the WSUserClient class instead of WSClient.\n\n```python\nfrom coinbase.websocket import WSUserClient\n\napi_key = \"organizations/{org_id}/apiKeys/{key_id}\"\napi_secret = \"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n\ndef on_message(msg):\n print(msg)\n\nclient = WSUserClient(api_key=api_key, api_secret=api_secret, on_message=on_message)\n```\n\n### Using the WebSocket Client\nOnce you have instantiated the client, you can connect to the WebSocket API by calling the `open` method, and disconnect by calling the `close` method.\nThe `subscribe` method allows you to subscribe to specific channels, for specific products. Similarly, the `unsubscribe` method allows you to unsubscribe from specific channels, for specific products. For example:\n\n```python\n# open the connection and subscribe to the ticker and heartbeat channels for BTC-USD and ETH-USD\nclient.open()\nclient.subscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\", \"heartbeats\"])\n\n# wait 10 seconds\ntime.sleep(10)\n\n# unsubscribe from the ticker channel and heartbeat channels for BTC-USD and ETH-USD, and close the connection\nclient.unsubscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\", \"heartbeats\"])\nclient.close()\n```\n\nWe also provide channel specific methods for subscribing and unsubscribing. For example, the below code is equivalent to the example from above:\n```python\nclient.open()\nclient.ticker(product_ids=[\"BTC-USD\", \"ETH-USD\"])\nclient.heartbeats(product_ids=[\"BTC-USD\", \"ETH-USD\"])\n\n# wait 10 seconds\ntime.sleep(10)\n\nclient.ticker_unsubscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"])\nclient.heartbeats_unsubscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"])\nclient.close()\n```\n\n### Automatic Reconnection to the WebSocket API\nThe WebSocket client will automatically attempt to reconnect the WebSocket API if the connection is lost, and will resubscribe to any channels that were previously subscribed to.\n\nThe client uses an exponential backoff algorithm to determine how long to wait before attempting to reconnect, with a maximum number of retries of 5.\n\nIf you do not want to automatically reconnect, you can set the `retry` argument to `False` when instantiating the client.\n```python\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, retry=False)\n```\n\n### Catching WebSocket Exceptions\nThe WebSocket API client will raise exceptions if it encounters an error. On forced disconnects it will raise a `WSClientConnectionClosedException`, otherwise it will raise a `WSClientException`.\n\nNOTE: Errors on forced disconnects, or within logic in the message handler, will not be automatically raised since this will be running on its own thread.\n\nWe provide the `sleep_with_exception_check` and `run_forever_with_exception_check` methods to allow you to catch these exceptions. `sleep_with_exception_check` will sleep for the specified number of seconds, and will check for any exception raised during that time. `run_forever_with_exception_check` will run forever, checking for exceptions every second. For example:\n\n```python\nfrom coinbase.websocket import (WSClient, WSClientConnectionClosedException,\n WSClientException)\n\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message)\n\ntry:\n client.open()\n client.subscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\", \"heartbeats\"])\n client.run_forever_with_exception_check()\nexcept WSClientConnectionClosedException as e:\n print(\"Connection closed! Retry attempts exhausted.\")\nexcept WSClientException as e:\n print(\"Error encountered!\")\n```\n\nThis code will open the connection, subscribe to the ticker and heartbeat channels for BTC-USD and ETH-USD, and will sleep forever, checking for exceptions every second. If an exception is raised, it will be caught and handled appropriately.\n\nIf you only want to run for 5 seconds, you can use `sleep_with_exception_check`:\n```python\nclient.sleep_with_exception_check(sleep=5)\n```\n\nNote that if the automatic reconnection fails after the retry limit is reached, a `WSClientConnectionClosedException` will be raised.\n\nIf you wish to implement your own reconnection logic, you can catch the `WSClientConnectionClosedException` and handle it appropriately. For example:\n```python\nclient = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, retry=False)\n\ndef connect_and_subscribe():\n try:\n client.open()\n client.subscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\", \"heartbeats\"])\n client.run_forever_with_exception_check()\n except WSClientConnectionClosedException as e:\n print(\"Connection closed! Sleeping for 20 seconds before reconnecting...\")\n time.sleep(20)\n connect_and_subscribe()\n```\n\n### Async WebSocket Client\nThe functions described above handle the asynchronous nature of WebSocket connections for you. However, if you wish to handle this yourself, you can use the `async_open`, `async_subscribe`, `async_unsubscribe`, and `async_close` methods.\n\nWe similarly provide async channel specific methods for subscribing and unsubscribing such as `ticker_async`, `ticker_unsubscribe_async`, etc.\n\n### WebSocket Response Types\nFor your convenience, we have provided a custom, built-in WebSocket response type object to help interact with our WebSocket feeds more easily. \nSimply import it from the same module as you do the `WSClient`:\n\n```python\nfrom coinbase.websocket import WSClient, WebsocketResponse\n```\n\nAssume we simply want the price feed for BTC-USD and ETH-USD. \nLike we did in previous steps, we subscribe to the `ticker` channel and include 'BTC-USD' and 'ETH-USD' in the `product_ids` list. \nAs the data comes through, it is passed into the `on_message` function. From there, we use it to build the `WebsocketResponse` object.\n\nUsing said object, we can now extract only the desired parts. In our case, we retrieve and print only the `product_id` and `price` fields, resulting in a cleaner feed.\n```python\nfrom coinbase.websocket import WSClient, WebsocketResponse\n\ndef on_message(msg):\n ws_object = WebsocketResponse(json.loads(msg))\n if ws_object.channel == \"ticker\" :\n for event in ws_object.events:\n for ticker in event.tickers:\n print(ticker.product_id + \": \" + ticker.price)\n\nclient.open()\nclient.subscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\"])\ntime.sleep(10)\nclient.unsubscribe(product_ids=[\"BTC-USD\", \"ETH-USD\"], channels=[\"ticker\"])\nclient.close()\n```\n#### Avoiding errors\nIn the example, note how we first checked `if ws_object.channel == \"ticker\"`. \nSince each channel's event field has a unique structure and set of fields, it's important to ensure that the fields we access are actually present in the object.\nFor example, if we were to subscribe to the `user` channel and try to access a field that does not exist in it, such as the `tickers` field, we would be met with an error.\n\nTherefore, we urge users to reference our [documentation](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels), which outlines the JSON object that each channel will return.\n\n___\n## Debugging the Clients\nYou can enable debug logging for the REST and WebSocket clients by setting the `verbose` variable to `True` when initializing the clients. This will log useful information throughout the lifecycle of the REST request or WebSocket connection, and is highly recommended for debugging purposes.\n```python\nrest_client = RESTClient(api_key=api_key, api_secret=api_secret, verbose=True)\n\nws_client = WSClient(api_key=api_key, api_secret=api_secret, on_message=on_message, verbose=True)\n```\n\n___\n## Authentication\nAuthentication of CDP API Keys is handled automatically by the SDK when making a REST request or sending a WebSocket message.\n\nHowever, if you wish to handle this yourself, you must create a JWT token and attach it to your request as detailed in the API docs [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-auth#making-requests). Use the built in `jwt_generator` to create your JWT token. For example:\n```python\nfrom coinbase import jwt_generator\n\napi_key = \"organizations/{org_id}/apiKeys/{key_id}\"\napi_secret = \"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n\nuri = \"/api/v3/brokerage/orders\"\n\njwt_uri = jwt_generator.format_jwt_uri(\"POST\", uri)\njwt = jwt_generator.build_rest_jwt(jwt_uri, api_key, api_secret)\n```\nThis will create a JWT token for the POST `/api/v3/brokerage/orders` endpoint. Pass this JWT token in the `Authorization` header of your request as:\n`\n\"Authorization\": \"Bearer \" + jwt\n`\n\nYou can also generate JWTs to use with the Websocket API. These do not require passing a specific URI. For example:\n```python\nfrom coinbase import jwt_generator\n\napi_key = \"organizations/{org_id}/apiKeys/{key_id}\"\napi_secret = \"-----BEGIN EC PRIVATE KEY-----\\nYOUR PRIVATE KEY\\n-----END EC PRIVATE KEY-----\\n\"\n\njwt = jwt_generator.build_ws_jwt(api_key, api_secret)\n```\nUse this JWT to connect to the Websocket API by setting it in the \"jwt\" field of your subscription requests. See the docs [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-overview#sending-messages-with-cdp-keys) for more details.\n\n___\n## Accessing public endpoints without authentication\n\nBoth clients contain public endpoints which can be accessed without authentication. \n\nTo do so, simply initialize the clients without providing any API keys as arguments. \n\n**_Notes:_**\n\n- Making calls to private endpoints or channels while unauthenticated will return an error\n- Unauthenticated requests are rate-limited more aggressively. Because of this we recommend that you authenticate your requests\n\n### REST Client\n\nIn the REST client, here is an example calling [Get Public Products](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getpublicproducts). \nIt does _not_ require authentication and is the public counterpart to \n[Get Products](https://docs.cdp.coinbase.com/advanced-trade/reference/retailbrokerageapi_getproducts), which _does_ require authentication.\n\nBoth endpoints return the same data.\n\n\n```\nfrom coinbase.rest import RESTClient\n\nclient = RESTClient()\n\npublic_products = client.get_public_products()\nprint(json.dumps(public_products.to_dict(), indent=2))\n```\n_Full list of all public REST endpoints [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-overview#public-endpoints)_\n\n_Rate limit details for REST endpoints [here](https://docs.cdp.coinbase.com/advanced-trade/docs/rest-api-rate-limits)_\n\n### Websocket Client\n\nIn the Websocket client, here is an example subscribing to the [ticker](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels#ticker-channel) channel. \nUnlike the REST client, Websocket channels handle both authenticated and unauthenticated requests. \nAt the moment, most channels in the Websocket client are public and can be used without keys.\n\n```\nimport time\nfrom coinbase.websocket import WSClient\n\ndef on_message(msg):\n print(msg)\n\nclient = WSClient(on_message=on_message)\n\nclient.open()\nclient.ticker(product_ids=[\"BTC-USD\"])\n\ntime.sleep(10)\n\nclient.ticker_unsubscribe(product_ids=[\"BTC-USD\"])\nclient.close()\n```\n\n_Full list of all public Websocket channels [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-channels)_\n\n_Rate limit details for Websocket channels [here](https://docs.cdp.coinbase.com/advanced-trade/docs/ws-rate-limits)_\n\n\n___\n## Changelog\nFor a detailed list of changes, see the [Changelog](https://github.com/coinbase/coinbase-advanced-py/blob/master/CHANGELOG.md).\n\n___\n## Contributing\n\nIf you've found a bug within this project, open an issue on this repo and add the \"bug\" label to it.\nIf you would like to request a new feature, open an issue on this repo and add the \"enhancement\" label to it.\nDirect concerns or questions on the API to the [Advanced API Discord](https://discord.com/channels/1220414409550336183/1220464268743278613) (use this [invite link](https://discord.com/invite/cdp) if it's your first time accessing the Discord).\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Coinbase Advanced API Python SDK",
"version": "1.8.1",
"project_urls": {
"Homepage": "https://github.com/coinbase/coinbase-advanced-py"
},
"split_keywords": [
"coinbase",
" advanced trade",
" api",
" advanced api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "94710e42827d13bad292d6c8e0ab5ad6ba6a79a8695ce12111ec30ecc322fe16",
"md5": "4bfe7a8fa068118d4f62ea34fc5a8d21",
"sha256": "d798d75d9376b5d94f23babc408b1ef1b79c06de90f829391fed2bc6205d253b"
},
"downloads": -1,
"filename": "coinbase_advanced_py-1.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bfe7a8fa068118d4f62ea34fc5a8d21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74452,
"upload_time": "2024-11-15T20:27:46",
"upload_time_iso_8601": "2024-11-15T20:27:46.984829Z",
"url": "https://files.pythonhosted.org/packages/94/71/0e42827d13bad292d6c8e0ab5ad6ba6a79a8695ce12111ec30ecc322fe16/coinbase_advanced_py-1.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2beec5b00a351f7f33f6691cddcb313770f360dafddc1b72ca83e13b74064085",
"md5": "9507727be38893ce9439416908cf60b2",
"sha256": "06af499913d53e7e3e5ac82dda92a5dbc58dd07e6f36de534047797b8c1a1718"
},
"downloads": -1,
"filename": "coinbase-advanced-py-1.8.1.tar.gz",
"has_sig": false,
"md5_digest": "9507727be38893ce9439416908cf60b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 60996,
"upload_time": "2024-11-15T20:27:49",
"upload_time_iso_8601": "2024-11-15T20:27:49.376114Z",
"url": "https://files.pythonhosted.org/packages/2b/ee/c5b00a351f7f33f6691cddcb313770f360dafddc1b72ca83e13b74064085/coinbase-advanced-py-1.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-15 20:27:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coinbase",
"github_project": "coinbase-advanced-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"test_requirements": [],
"lcname": "coinbase-advanced-py"
}
JSON
