REST Public API Reference

The following is an API reference of CoPrA generated from Python source code and docstrings.

Warning

This is a complete reference of the public API of CoPrA. User code and applications should only rely on the public API, since internal APIs can (and will) change without any guarantees. Anything not listed here is considered a private API.

Module copra.rest

class copra.rest.Client(loop, url='https://api.pro.coinbase.com', auth=False, key='', secret='', passphrase='')[source]

Asyncronous REST client for Coinbase Pro.

__init__(loop, url='https://api.pro.coinbase.com', auth=False, key='', secret='', passphrase='')[source]
Parameters:
  • loop (asyncio loop) – The asyncio loop that the client runs in.
  • url (str) – (optional) The REST API server url. The default is https://api.pro.coinbase.com. This generally does not need to be changed. One reason to change it would be to test against the sandbox server.
  • auth (bool) – (optional) Whether or not the (entire) REST session is authenticated. If True, you will need an API key from the Coinbase Pro website. The default is False.
  • key (str) – (optional) The API key to use for authentication. Required if auth is True. The default is ‘’.
  • secret (str) – (optional) The secret string for the API key used for authenticaiton. Required if auth is True. The default is ‘’.
  • passphrase (str) – (optional) The passphrase for the API key used for authentication. Required if auth is True. The default is ‘’.
Raises:

ValueError – If auth is True and key, secret, and passphrase are not provided.
account(account_id)[source]

Retrieve information for a single account.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Parameters:

account_id (str) – The account id.
Returns:

A dict of account information.

Example:

{
  'id': 'a764610f-334e-4ece-b4dd-f31111ed58e7', 
  'currency': 'USD', 
  'balance': '1000.0000005931528000', 
  'available': '1000.0000005931528', 
  'hold': '0.0000000000000000', 
  'profile_id': '019be148-d490-45f9-9ead-0d1f64127716'
}

Raises:
  • ValueError – If the client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
account_history(account_id, limit=100, before=None, after=None)[source]

Retrieve a list account activity.

Account activity includes transactions that either increase or decrease the account balance. Transactions are sorted latest first.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Pagination

This method is paginated. See pagination for more details.

Parameters:
  • account_id (str) – The account id.
  • limit (int) – (optional) The number of results to be returned per request. The default (and maximum) value is 100.
  • before (int) – (optional) The before cursor value. The default is None.
  • after (int) – (optional) The after cursor value. The default is None.
Returns:

A 3-tuple (results, before cursor, after cursor)

results is a list of dicts each representing an instance of account activity. The different types of activity returned are:

  • transfer Funds moved to/from Coinbase to Coinbase Pro
  • match Funds moved as a result of a trade
  • fee Fee as a result of a trade
  • rebate Fee rebate

The details field contains type-specific details about the specific transaction.

Example:

(
  [
    {
      'created_at': '2018-09-28T19:31:21.211159Z', 
      'id': 10712040275, 
      'amount': '-600.9103845810000000', 
      'balance': '0.0000005931528000', 
      'type': 'match', 
      'details': {
                   'order_id': 'd2fadbb5-8769-4b80-91da-be3d9c6bd38d', 
                   'trade_id': '34209042', 
                   'product_id': 'BTC-USD'
                 }
    }, 
    {
      'created_at': '2018-09-23T23:13:45.771507Z', 
      'id': 1065316993, 
      'amount': '-170.0000000000000000', 
      'balance': '6.7138918107528000', 
      'type': 'transfer', 
      'details': {
                   'transfer_id': 'd00841ff-c572-4726-b9bf-17e783159256', 
                   'transfer_type': 'withdraw'
                 }
    }, 
    ...
  ],
  '1071064024',
  '1008063508'
)

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • before and after are both set.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
accounts()[source]

Get a list of Coinbase Pro trading accounts.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Returns:

A list of dicts where each dict contains information about a trading a account.

Example:

[
  {
    'id': 'a764610f-334e-4ece-b4dd-f31111ed58e7', 
    'currency': 'USD', 
    'balance': '1000.0000005931528000', 
    'available': '1000.0000005931528', 
    'hold': '0.0000000000000000', 
    'profile_id': '019be148-d490-45f9-9ead-0d1f64127716'
  },
  ...
]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
cancel(order_id)[source]

Cancel a previously placed order.

If the order had no matches during its lifetime its record may be purged. This means the order details will not be available with copra.rest.Client.get_order().

Authorization

This method requires authorization. The API key must have the “trade” permission.

Parameters:

order_id (str) – The id of the order to be cancelled. This is the server-assigned order id and not the optional client_oid.
Returns:

A list consisting of a single string entry, the id of the cancelled order.

Example:

["144c6f8e-713f-4682-8435-5280fbe8b2b4"]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
cancel_all(product_id=None, stop=False)[source]

Cancel “all” orders.

The default behavior of this method (and the underlying Coinbase API method) is to cancel only open orders. Stop orders, once placed, have a status method of active and will not be cancelled.

Setting stop = True will also cancel stop orders or copra.rest.Client.cancel() can be used to cancel invidual stop orders.

Authorization

This method requires authorization. The API key must have the “trade” permission.

Parameters:
  • product_id (str) – (optional) Only cancel orders for the specified product. The default is None.
  • stop (bool) – (optional) Also delete stop orders.
Returns:

A list of the ids of orders that were successfully cancelled.

Example:

[
  "144c6f8e-713f-4682-8435-5lia280fbe8b2b4",
  "debe4907-95dc-442f-af3b-cec12f42ebda",
  "cf7aceee-7b08-4227-a76c-3858144323ab",
  "dfc5ae27-cadb-4c0c-beef-8994936fde8a",
  "34fecfbf-de33-4273-b2c6-baf8e8948be4"
]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – For any error generated by the Coinbase Pro API server.
close()[source]

Close the client session and release all aquired resources.

closed

True if the client has been closed, False otherwise

coinbase_accounts()[source]

Get a list of your coinbase accounts.

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Returns:

A list of dicts where each dict contains information about a Coinbase account.

Example:

[
    {
        "id": "fc3a8a57-7142-542d-8436-95a3d82e1622",
        "name": "ETH Wallet",
        "balance": "0.00000000",
        "currency": "ETH",
        "type": "wallet",
        "primary": false,
        "active": true
    },
    {
        "id": "2ae3354e-f1c3-5771-8a37-6228e9d239db",
        "name": "USD Wallet",
        "balance": "0.00",
        "currency": "USD",
        "type": "fiat",
        "primary": false,
        "active": true,
        "wire_deposit_information": {
            "account_number": "0199003122",
            "routing_number": "026013356",
            "bank_name": "Metropolitan Commercial Bank",
            "bank_address": "99 Park Ave 4th Fl New York, NY 10016",
            "bank_country": {
                "code": "US",
                "name": "United States"
            },
            "account_name": "Coinbase, Inc",
            "account_address": "548 Market Street, San Fran, CA 94104",
            "reference": "BAOCAEUX"
        }
    },
    {
        "id": "1bfad868-5223-5d3c-8a22-b5ed371e55cb",
        "name": "BTC Wallet",
        "balance": "0.00000000",
        "currency": "BTC",
        "type": "wallet",
        "primary": true,
        "active": true
    },
    ...,
]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
create_report(report_type, start_date, end_date, product_id='', account_id='', report_format='pdf', email='')[source]

Create a report about your account history.

Reports provide batches of historic information about your account in various human and machine readable forms.

The report will be generated when resources are available. Report status can be queried via copra.rest.Client.report_status(). The url for the report file will be available once the report has successfully been created and is available for download.

Note

Reports are only available for download for a few days after being created. Once a report expires, the report is no longer available for download and is deleted.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Parameters:
  • report_type (str) – The type of report to generate. This must be either “fills” or “account”.
  • start_date (str) – The starting date of the requested report as a str in ISO 8601 format.
  • end_date (str) – The ending date of the requested report as a str in ISO 8601 format.
  • product_id (str) – (optional) ID of the product to generate a fills report for. e.g. “BTC-USD”. Required if type is fills.
  • account_id (str) – (optional) ID of the account to generate an account report for. Required if type is account.
  • report_format (str) – (optional) Format of the report to be generated. Can be either pdf or csv. The default is pdf.
  • email (str) – (optional) Email address to send the report to. The default is None.
Returns:

A dict of information about the report including its id which can be used to check its status.

Example:

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "pending",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": undefined,
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": undefined,
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • Invalid report_type provided.
    • report_type is fills and product_id is not provided.
    • report_type is account and account_id is not provided.
    • Invalid report_format provided.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
currencies()[source]

List known currencies.

Currency codes will conform to the ISO 4217 standard where possible. Currencies which have or had no representation in ISO 4217 may use a custom code.

Note

Not all currencies may be currently in use for trading.

Returns:A list of dicts where each dict contains information about a currency.

Example:

[
  {
    "id": "BTC",
    "name": "Bitcoin",
    "min_size": "0.00000001"
  }, 
  {
    "id": "USD",
    "name": "United States Dollar",
    "min_size": "0.01000000"
  },
  ...,
]
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
delete(path='/', params=None, auth=False)[source]

Base method for making DELETE requests.

Parameters:
  • path (str) – (optional) The path not including the base URL of the resource to be deleted. The default is ‘/’.
  • params (dict) – (optional) dict or MultiDict of key/value str pairs to be appended as the request’s query string. The default is None.
  • auth (boolean) – (optional) Indicates whether or not this request needs to be authenticated. The default is False.
Returns:

A 2-tuple: (response headers, response body).

Response headers is a dict with the HTTP headers of the response. The response body is a JSON-formatted, UTF-8 encoded str.
Raises:

APIRequestError – Any error generated by the Coinbase Pro API server.
deposit_coinbase(amount, currency, coinbase_account_id)[source]

Deposit funds from a Coinbase account.

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Parameters:
  • amount (float) – The amount of the currency to deposit. This paramater may also be a string to avoid floating point issues.
  • currency (str) – The type of currency to deposit. i.e., BTC, LTC, USD, etc.
  • coinbase_account_id (str) – The id of the Coinbase account to deposit from. To get a list of Coinbase accounts, use: copra.rest.Client.coinbase_accounts().
Returns:

A dict with a deposit id and confirmation of the deposit amount and currency.

Example:

{
    "id": "593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "BTC",
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
deposit_payment_method(amount, currency, payment_method_id)[source]

Deposit funds from a payment method on file.

To get a list of available payment methods, use copra.rest.Client.payment_methods().

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Parameters:
  • amount (float) – The amount of the currency to deposit. This paramater may also be a string to avoid floating point issues.
  • currency (str) – The type of currency to deposit. i.e., USD, EUR, etc.
  • payment_method_id (str) – The id of the payment method to use.
Returns:

A dict with a deposit id, timestamp and other deposit information.

Example:

{
    "id": "593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "USD",
    "payout_at": "2016-08-20T00:31:09Z"
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
fees()[source]

Get your current maker & taker fee rates and 30-day trailing volume.

Note

Quoted rates are subject to change. More information on fees can found at: https://support.pro.coinbase.com/customer/en/portal/articles/2945310-fees.

Returns:A dict containing the maker fee, taker fee and 30-day trailing volume.

Example:

{
    "maker_fee_rate": "0.0015",
    "taker_fee_rate": "0.0025",
    "usd_volume": "25000.00"
}
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
fills(order_id='', product_id='', limit=100, before=None, after=None)[source]

Get a list of recent fills.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Pagination

This method is paginated. See pagination for more details.

Parameters:
  • order_id (str) – (optional) Limit list of fills to this order_id, Either this or product_id must be defined.
  • product_id (str) – (optional) Limit list of fills to this product_id. Either this or order_id must be defined.
  • limit (int) – (optional) The number of results to be returned per request. The default (and maximum) value is 100.
  • before (int) – (optional) The before cursor value. The default is None.
  • after (int) – (optional) The after cursor value. The default is None.
Returns:

A 3-tuple (fills, before cursor, after cursor)

fills is a list of dicts where each dict represents a fill.

Example:

[
  {
    "trade_id": 74, 
    "product_id": "BTC-USD",
    "price": "10.00",
    "size": "0.01",
    "order_id": "d50ec984-77a8-460a-b958-66f114b0de9b",
    "created_at": "2014-11-07T22:19:28.578544Z",
    "liquidity": "T",
    "fee": "0.00025",
    "settled": true,
    "side": "buy"
  },
  ...,
]

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • Both before and after are set.
    • Neither order_id nor product_id are set or both are set.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
get(path='/', params=None, auth=False)[source]

Base method for making GET requests.

Parameters:
  • path (str) – (optional) The path not including the base URL of the resource to be retrieved. The default is ‘/’.
  • params (dict) – (optional) dict or MultiDict of key/value str pairs to be appended as the request’s query string. The default is None.
  • auth (boolean) – (optional) Indicates whether or not this request needs to be authenticated. The default is False.
Returns:

A 2-tuple: (response headers, response body).

Response headers is a dict with the HTTP headers of the response. The response body is a JSON-formatted, UTF-8 encoded str.
Raises:

APIRequestError – Any error generated by the Coinbase Pro API server.
get_24hour_stats(product_id)[source]

Get 24 hr stats for a product.

Parameters:product_id (str) – The product id.
Returns:A dict of stats for the product including: open, high, low, volume, last price, and 30 day volume.

Example:

{
  'open': '6710.37000000', 
  'high': '6786.73000000', 
  'low': '6452.02000000', 
  'volume': '9627.98224214', 
  'last': '6484.03000000', 
  'volume_30day': '238376.24964395'
}
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
get_order(order_id)[source]

Get a single order by order id.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Parameters:order_id (str) – The order id.
Returns:A dict of information about the order.

Example:

{
  "id": "68e6a28f-ae28-4788-8d4f-5ab4e5e5ae08",
  "size": "1.00000000",
  "product_id": "BTC-USD",
  "side": "buy",
  "stp": "dc",
  "funds": "9.9750623400000000",
  "specified_funds": "10.0000000000000000",
  "type": "market",
  "post_only": false,
  "created_at": "2016-12-08T20:09:05.508883Z",
  "done_at": "2016-12-08T20:09:05.527Z",
  "done_reason": "filled",
  "fill_fees": "0.0249376391550000",
  "filled_size": "0.01291771",
  "executed_value": "9.9750556620000000",
  "status": "done",
  "settled": true
}

Note

Open orders may change state between the request and the response depending on market conditions.

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
historic_rates(product_id, granularity=3600, start=None, end=None)[source]

Get historic rates for a product.

Rates are returned in grouped buckets based on the requested granularity.

Note

The maximum number of data points for a single request is 300 candles. If your selection of start/end time and granularity will result in more than 300 data points, your request will be rejected. If you wish to retrieve fine granularity data over a larger time range, you will need to make multiple requests with new start/end ranges.

Historical rate data may be incomplete. No data is published for intervals where there are no ticks.

Warning

Historical rates should not be polled frequently. If you need real-time information, use the trade and book endpoints along with the websocket feed.

Parameters:
  • product_id (str) – The product id.
  • granularity (int) – (optional) Desired timeslice in seconds. The granularity field must be one of the following values: {60, 300, 900, 3600, 21600, 86400}. Otherwise, your request will be rejected. These values correspond to timeslices representing one minute, five minutes, fifteen minutes, one hour, six hours, and one day, respectively. The default is 3600 (1 hour).
  • start (str) – (optional) The start time as a str in ISO 8601 format. This field is optional. If it is set, then end must be set as well. If neither start nor end are set, start will default to the time relative to now() that would return 300 results based on the granularity.
  • end (str) – (optional) The end time as a str in ISO 8601 format. This field is optional. If it is set then start must be set as well. If it is not set, end will default to now().
Returns:

A list of lists where each list item is a “bucket” representing a timeslice of length granularity. The fields of the bucket are: [ time, low, high, open, close, volume ]

  • time - bucket start time as a Unix timestamp
  • low - lowest price during the bucket interval
  • high - highest price during the bucket interval
  • open - opening price (first trade) in the bucket interval
  • close - closing price (last trade) in the bucket interval
  • volume - volume of trading activity during the bucket interval

Example:

[
  [1538179200, 61.12, 61.75, 61.74, 61.18, 2290.8172972700004], 
  [1538175600, 61.62, 61.8, 61.65, 61.75, 2282.2335001199995], 
  [1538172000, 61.52, 61.79, 61.66, 61.65, 3877.4680861400007],
  ...
]

Raises:
  • ValueError –
    • granularity is not one of the possible values.
    • Either start or end is set but not both
  • APIRequestError – Any error generated by the Coinbase Pro API server.
holds(account_id, limit=100, before=None, after=None)[source]

Get any existing holds on an account.

Holds are placed on an account for any active orders or pending withdraw requests. As an order is filled, the hold amount is updated. If an order is canceled, any remaining hold is removed. For a withdraw, once it is completed, the hold is removed.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Pagination

This method is paginated. See pagination for more details.

Parameters:
  • account_id (str) – The acount ID to be checked for holds.
  • limit (int) – (optional) The number of results to be returned per request. The default (and maximum) value is 100.
  • before (int) – (optional) The before cursor value. The default is None.
  • after (int) – (optional) The after cursor value. The default is
Returns:

A 3-tuple (holds, before cursor, after cursor)

holds is a list of dicts where each dict represents a hold on the account.

Example:

(
  [
    {
      "id": "82dcd140-c3c7-4507-8de4-2c529cd1a28f",
      "account_id": "e0b3f39a-183d-453e-b754-0c13e5bab0b3",
      "created_at": "2014-11-06T10:34:47.123456Z",
      "updated_at": "2014-11-06T10:40:47.123456Z",
      "amount": "4.23",
      "type": "order",
      "ref": "0a205de4-dd35-4370-a285-fe8fc375a273",
    },
    ...
  ],
  '1071064024',
  '1008063508'
)

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • before and after are both set.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
limit_order(side, product_id, price, size, time_in_force='GTC', cancel_after=None, post_only=False, client_oid=None, stp='dc', stop=None, stop_price=None)[source]

Place a limit order or a stop entry/loss limit order.

Authorization

This method requires authorization. The API key must have the “trade” permission.

Parameters:
  • side (str) – Either buy or sell
  • product_id (str) – The product id to be bought or sold.
  • price (float) – The price the order is to be executed at. This paramater may also be a string to avoid floating point issues.
  • size (float) – The quantity of the cryptocurrency to buy or sell. This parameter may also be a string.
  • time_in_force (str) – (optional) Time in force policies provide guarantees about the lifetime of an order. There are four policies: GTC (good till canceled), GTT (good till time), IOC (immediate or cancel), and FOK (fill or kill) GTT requires that cancel_after be set. IOC and FOK require post_only be False. The default is GTC.
  • cancel_after (str) – (optional) The length of time before a GTT order is cancelled. Must be either min, hour, or day. time_in_force must be GTT or an error is raised. If cancel_after is not set for a GTT order, the order will be treated as GTC. The default is None.
  • post_only (bool) – (optional) Indicates that the order should only make liquidity. If any part of the order results in taking liquidity, the order will be rejected and no part of it will execute. This flag is ignored for IOC and FOK orders. This value must be False for all stop orders. The default is False.
  • stp (str) – (optional) Self trade preservation flag. The possible values are dc (decrease and cancel), co (cancel oldest), cn (cancel newest), or cb (cancel both). The default is dc.
  • stop (str) – (optional) If this is a stop order, this value must be either loss or entry. Requires stop_price to be set. The default is None.
  • stop_price (float) – (optioinal) The trigger price for stop orders. Required if stop is set. This may also be a string. The default is None.

Warning

As of 11/18, sending anything other than dc for stp while testing in Coinbase Pro’s sandbox yields an APIRequestError “Invalid stp…” even though the Coinbase API documentation claims the other options for stp are valid. Change this from dc at your own risk.

Note

To see a more detailed explanation of these parameters and to learn more about the order life cycle, please see the official Coinbase Pro API documentation at: https://docs.gdax.com/#channels.

Returns:

A dict of information about the order.

Example:

{
  'id': '97059421-3033-4cf4-99cb-925c1bf2c54f', 
  'price': '35.00000000', 
  'size': '0.00100000', 
  'product_id': 'BTC-USD', 
  'side': 'buy', 
  'stp': 'dc', 
  'type': 'limit', 
  'time_in_force': 'GTC', 
  'post_only': False, 
  'created_at': '2018-11-25T21:24:37.166378Z', 
  'fill_fees': '0.0000000000000000', 
  'filled_size': '0.00000000', 
  'executed_value': '0.0000000000000000', 
  'status': 'pending', 
  'settled': False
}

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • The side is not either “buy” or “sell”.
    • The time_in_force is not GTC, GTT, IOC or FOK.
    • time_in_force is GTT but cancel_after is not set
    • cancel_after for a limit order is set but isn’t min, hour or day.
    • cancel_after is set for a limit order but time_in_force isn’t GTT.
    • The time_in_force is IOC or FOK and post_only is True
    • stp is a value other than dc. co, cn, or cb.
    • stop is set to something other than loss or entry.
    • A stop order does not have stop_price set.
    • stop_price is set but stop is not
    • A stop_order has post_only set to True
  • APIRequestError – Any error generated by the Coinbase Pro API server.
market_order(side, product_id, size=None, funds=None, client_oid=None, stp='dc', stop=None, stop_price=None)[source]

Place a market order or a stop entry/loss market order.

Authorization

This method requires authorization. The API key must have the “trade” permission.

Parameters:
  • side (str) – Either buy or sell
  • product_id (str) – The product id to be bought or sold.
  • size (float) – The quantity of the cryptocurrency to buy or sell. Either size or funds must be set for a market order but not both. This may also be a string. The default is None.
  • funds (float) – This is the amount of quote currency to be used for a purchase (buy) or the amount to be obtained from a sale (sell). Either size or funds must be set for a market order but not both. This may also be a string. The default is None.
  • client_oid (str) – (optional) A self generated UUID to identify the order. The default is None.
  • stp (str) – (optional) Self trade preservation flag. The possible values are dc (decrease and cancel), co (cancel oldest), cn (cancel newest), or cb (cancel both). The default is dc.
  • stop (str) – (optional) If this is a stop order, this value must be either loss or entry. Requires stop_price to be set. The default is None.
  • stop_price (float) – (optional) The trigger price for stop orders. Required if stop is set. This may also be a string. The default is None.

Warning

As of 11/18, sending anything other than dc for stp while testing in Coinbase Pro’s sandbox yields an APIRequestError “Invalid stp…” even though the Coinbase API documentation claims the other options for stp are valid. Change this from dc at your own risk.

Note

To see a more detailed explanation of these parameters and to learn more about the order life cycle, please see the official Coinbase Pro API documentation at: https://docs.gdax.com/#channels.

Returns:

A dict of information about the order.

Example:

{
  'id': '37e81782-cc45-4ecc-a9ff-59c327bb1d40', 
  'size': '0.00100000', 
  'product_id': 'BTC-USD', 
  'side': 'sell', 
  'stp': 'dc', 
  'type': 'market', 
  'post_only': False, 
  'created_at': '2018-11-25T21:28:04.788042Z', 
  'fill_fees': '0.0000000000000000', 
  'filled_size': '0.00000000', 
  'executed_value': '0.0000000000000000', 
  'status': 'pending', 
  'settled': False
}

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • The side is not either “buy” or “sell”.
    • Neither size nor funds is set.
    • Both size and funds are set
    • stp is a value other than dc. co, cn, or cb.
    • stop is set to something other than loss or entry.
    • A stop order does not have stop_price set.
    • stop_price is set but stop is not
  • APIRequestError – Any error generated by the Coinbase Pro API server.
order_book(product_id, level=1)[source]

Get a list of open orders for a product.

By default, only the inside (i.e. best) bid and ask are returned. This is equivalent to a book depth of 1 level. If you would like to see a larger order book, specify the level query parameter.

Level | Description
1 Only the best bid and ask
2 Top 50 bids and asks (aggregated)
3 Full order book (non aggregated)

If a level is not aggregated, then all of the orders at each price will be returned. Aggregated levels return only one size for each active price (as if there was only a single order for that size at the level).

Levels 1 and 2 are aggregated. The first field is the price. The second is the size which is the sum of the size of the orders at that price, and the third is the number of orders, the count of orders at that price. The size should not be multiplied by the number of orders.

Level 3 is non-aggregated and returns the entire order book.

Note

This request is NOT paginated. The entire book is returned in one response.

Level 1 and Level 2 are recommended for polling. For the most up-to-date data, consider using the websocket stream.

Warning

Level 3 is only recommended for users wishing to maintain a full real-time order book using the websocket stream. Abuse of Level 3 via polling will cause your access to be limited or blocked.

Parameters:
  • product_id (str) – The product id of the order book.
  • level (int) – (optional) The level customizes the amount of detail shown. See bove for more detail. The default is 1.
Returns:

A dict representing the order book for the product id specified. The layout of the dict will vary based on the level. See the examples below.

Level 1:

{
  'sequence': 7068939079, 
  'bids': [['482.98', '54.49144003', 18]], 
  'asks': [['482.99', '4.57036219', 10]]
}

Level 2:

{
  'sequence': 7069016926, 
  'bids': [['489.13', '0.001', 1], ['487.99', '0.03', 1], ...],
  'asks': [['489.14', '40.72125158', 16], ['490.11', '0.5', 1], ...],
}

Level 3:

{
  'sequence': 7072737439, 
  'bids': 
    [
      ['468.9', '0.01100413', '48c3ed25-616d-430d-bab4-cb338b489a33'], 
      ['468.9', '0.224', 'b96424ea-e992-4df5-b503-df50dac1ac50'], 
      ...
    ],
  'asks': 
    [
      ['468.91', '5.96606527', 'cc37e457-020c-4843-9a3e-e6164dcf4e60'], 
      ['468.91', '0.00341509', '43e8158a-30c6-437b-9a51-9b9da00e4e22'],
      ...
    ]
}

Raises:
  • ValueError – level not 1, 2, or 3.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
orders(status=None, product_id=None, limit=100, before=None, after=None)[source]

Retrieve a list orders.

The status of an order may change between the request and response depending on market conditions.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Pagination

This method is paginated. See pagination for more details.

Parameters:
  • status (str) – (optional) Limit list of orders to one or more of these statuses: open, pending, active or all. status may be a single string or a list of strings. i.e, [‘open’, ‘active’]. ‘all’ returns orders of all statuses. The default is [‘open’, ‘active’, ‘pending’].
  • product_id (str) – (optional) Filter orders by product_id
  • limit (int) – (optional) The number of results to be returned per request. The default (and maximum) value is 100.
  • before (int) – (optional) The before cursor value. The default is None.
  • after (int) – (optional) The after cursor value. The default is None.
Returns:

A 3-tuple: (orders, before cursor, after cursor)

orders is a list of dicts where each dict represents an order.

Example:

([
  {
    "id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "price": "0.10000000",
    "size": "0.01000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "type": "limit",
    "time_in_force": "GTC",
    "post_only": false,
    "created_at": "2016-12-08T20:02:28.53864Z",
    "fill_fees": "0.0000000000000000",
    "filled_size": "0.00000000",
    "executed_value": "0.0000000000000000",
    "status": "open",
    "settled": false
  },
  {
    "id": "8b99b139-58f2-4ab2-8e7a-c11c846e3022",
    "price": "1.00000000",
    "size": "1.00000000",
    "product_id": "BTC-USD",
    "side": "buy",
    "stp": "dc",
    "type": "limit",
    "time_in_force": "GTC",
    "post_only": false,
    "created_at": "2016-12-08T20:01:19.038644Z",
    "fill_fees": "0.0000000000000000",
    "filled_size": "0.00000000",
    "executed_value": "0.0000000000000000",
    "status": "open",
    "settled": false
  }
 ],
 '1071064024',
 '1008063508'
)

Raises:
  • ValueError –
    • The client is not configured for authorization.
    • An invalid status string is provided.
    • before and after are both set.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
payment_methods()[source]

Get a list of the payment methods you have on file.

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Returns:

A list of dicts where each dict contains detailed information about a payment method the account has available.

Example:

[
    {
        "id": "bc6d7162-d984-5ffa-963c-a493b1c1370b",
        "type": "ach_bank_account",
        "name": "Bank of America - eBan... ********7134",
        "currency": "USD",
        "primary_buy": true,
        "primary_sell": true,
        "allow_buy": true,
        "allow_sell": true,
        "allow_deposit": true,
        "allow_withdraw": true,
        "limits": {
            "buy": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ],
            "instant_buy": [
                {
                    "period_in_days": 7,
                    "total": {
                        "amount": "0.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "0.00",
                        "currency": "USD"
                    }
                }
            ],
            "sell": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ],
            "deposit": [
                {
                    "period_in_days": 1,
                    "total": {
                        "amount": "10000.00",
                        "currency": "USD"
                    },
                    "remaining": {
                        "amount": "10000.00",
                        "currency": "USD"
                    }
                }
            ]
        }
    },
]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
post(path='/', data=None, auth=False)[source]

Base method for making POST requests.

Parameters:
  • path (str) – (optional) The path not including the base URL of the resource to be POST’ed to. The default is ‘/’
  • data (dict) – (optional) Dictionary of key/value str pairs to be sent in the body of the request. The default is None.
  • auth (boolean) – (optional) Indicates whether or not this request needs to be authenticated. The default is False.
Returns:

A 2-tuple: (response headers, response body).

Response headers is a dict with the HTTP headers of the response. The response body is a JSON-formatted, UTF-8 encoded str.
Raises:

APIRequestError – Any error generated by the Coinbase Pro API server.
products()[source]

Get a list of available currency pairs for trading.

The base_min_size and base_max_size fields define the min and max order size.

The quote_increment field specifies the min order price as well as the price increment. The order price must be a multiple of this increment (i.e. if the increment is 0.01, order prices of 0.001 or 0.021 would be rejected).

Note

Product ID will not change once assigned to a product but the min/max/quote sizes can be updated in the future.

Returns:A list of dicts representing the currency pairs available for trading.

Example:

[
  {
    'id': 'BTC-USD', 
    'base_currency': 'BTC', 
    'quote_currency': 'USD', 
    'base_min_size': '0.001', 
    'base_max_size': '70', 
    'quote_increment': '0.01', 
    'display_name': 'BTC/USD', 
    'status': 'online', 
    'margin_enabled': False, 
    'status_message': None, 
    'min_market_funds': '10', 
    'max_market_funds': '1000000', 
    'post_only': False, 
    'limit_only': False, 
    'cancel_only': False
  },
  ...
 ]
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
report_status(report_id)[source]

Get the status of a report.

Once a report request has been accepted for processing, the status is available by polling the report resource endpoint.

The possible status values are:

  • pending - The report request has been accepted and is awaiting processing.
  • creating - The report is being created.
  • ready - The report is ready for download from file_url.

The final report will be uploaded and available at file_url once the status indicates ready.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Parameters:

report_id (str) – The id of the report. This is obtained from copra.rest.Client.create_report().
Returns:

A dict summarizing the current status of the report. Examples follow.

Creating report:

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "creating",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": undefined,
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": undefined,
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

Finished report:

{
    "id": "0428b97b-bec1-429e-a94c-59232926778d",
    "type": "fills",
    "status": "ready",
    "created_at": "2015-01-06T10:34:47.000Z",
    "completed_at": "2015-01-06T10:35:47.000Z",
    "expires_at": "2015-01-13T10:35:47.000Z",
    "file_url": "https://example.com/0428b97b.../fills.pdf",
    "params": {
        "start_date": "2014-11-01T00:00:00.000Z",
        "end_date": "2014-11-30T23:59:59.000Z"
    }
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
server_time()[source]

Get the API server time.

Returns:A dict with two fields: iso and epoch. iso is an ISO 8601 str, and epoch is a float. Both represent the current time at the API server.

Example:

{
  'iso': '2018-09-29T03:02:27.753Z', 
  'epoch': 1538190147.753
}
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
stablecoin_conversion(from_currency_id, to_currency_id, amount)[source]

Convert to and from a stablecoin.

Authorization

This method requires authorization. The API key must have the “trade” permission.

Note

As of November, 1018, Coinbase Pro only supports USD-USDC conversions

Parameters:
  • from_currency_id (str) – The id of the currency to convert from.
  • to_currency_id (str) – The id of the currency to convert to.
  • amount (float) – The amount of currency to convert. This paramater may also be a string to avoid floating point issues.
Returns:

A dict summarizing the conversion.

Example:

{
    "id": "8942caee-f9d5-4600-a894-4811268545db",
    "amount": "10000.00",
    "from_account_id": "7849cc79-8b01-4793-9345-bc6b5f08acce",
    "to_account_id": "105c3e58-0898-4106-8283-dc5781cda07b",
    "from": "USD",
    "to": "USDC"
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
ticker(product_id)[source]

Get information about the last trade for a specific product.

Note

Polling is discouraged in favor of connecting via the websocket stream and listening for match messages.

Parameters:product_id (str) – The product id of the tick to be retrieved.
Returns:A dict containing information about the last trade (tick) for the product.
Example:
{
  'trade_id': 51554088, 
  'price': '6503.14000000', 
  'size': '0.00532605', 
  'bid': '6503.13', 
  'ask': '6503.14', 
  'volume': '6060.89272148', 
  'time': '2018-09-27T13:18:42.571000Z'
}
Raises:APIRequestError – Any error generated by the Coinbase Pro API server.
trades(product_id, limit=100, before=None, after=None)[source]

List the latest trades for a product.

The trade side indicates the maker order side. The maker order is the order that was open on the order book. buy side indicates a down-tick because the maker was a buy order and their order was removed. Conversely, sell side indicates an up-tick.

Pagination

This method is paginated. See pagination for more details.

Parameters:
  • product_id (str) – The product id whose trades are to be retrieved.
  • limit (int) – (optional) The number of results to be returned per request. The default (and maximum) value is 100.
  • before (int) – (optional) The before cursor value. The default is None.
  • after (int) – (optional) The after cursor value. The default is None.
Returns:

A 3-tuple: (trades, before cursor, after cursor)

trades is a list of dicts representing trades for the product specified.

Example:

(
  [
    {
      'time': '2018-09-27T22:49:16.105Z', 
      'trade_id': 51584925, 
      'price': '6681.01000000', 
      'size': '0.02350019', 
      'side': 'sell'
    }, 
    {
      'time': '2018-09-27T22:49:12.39Z', 
      'trade_id': 51584924, 
      'price': '6681.00000000', 
      'size': '0.01020000', 
      'side': 'buy'
    },
    ...
  ],
  '51590012', 
  '51590010'
)

Raises:
  • ValueError – before and after paramters are both provided.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
trailing_volume()[source]

Return your 30-day trailing volume for all products.

This is a cached value that’s calculated every day at midnight UTC.

Authorization

This method requires authorization. The API key must have either the “view” or “trade” permission.

Returns:

A list of dicts where each dict contains information about a specific product that was traded.

Example:

[
    {
        "product_id": "BTC-USD",
        "exchange_volume": "11800.00000000",
        "volume": "100.00000000",
        "recorded_at": "1973-11-29T00:05:01.123456Z"
    },
    {
        "product_id": "LTC-USD",
        "exchange_volume": "51010.04100000",
        "volume": "2010.04100000",
        "recorded_at": "1973-11-29T00:05:02.123456Z"
    }
]

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
withdraw_coinbase(amount, currency, coinbase_account_id)[source]

Withdraw funds to a coinbase account.

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Parameters:
  • amount (float) – The amount of the currency to withdraw. This paramater may also be a string to avoid floating point issues.
  • currency (str) – The type of currency to withdraw. i.e., BTC, LTC, USD, etc.
  • coinbase_account_id (str) – The id of the Coinbase account to withdraw to. To get a list of Coinbase accounts, use: copra.rest.Client.coinbase_accounts().
Returns:

A dict with the withdrawal id, and confirmation of the withdrawl amount and currency.

Example:

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount":"10.00",
    "currency": "BTC",
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
withdraw_crypto(amount, currency, crypto_address)[source]

Withdraw funds to a crypto address.

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Parameters:
  • amount (float) – The amount of the currency to withdraw. This paramater may also be a string to avoid floating point issues.
  • currency (str) – The type of currency to withdraw. i.e., BTC, LTC, USD, etc.
  • crypto_address (str) – The crypto address of the recipient.
Returns:

A dict with the withrawal id and confirmation of the withdrawl amount and currency.

Example:

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount":"10.00",
    "currency": "BTC",
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.
withdraw_payment_method(amount, currency, payment_method_id)[source]

Withdraw funds to a payment method on file.

To get a list of available payment methods, use copra.rest.Client.payment_methods().

Authorization

This method requires authorization. The API key must have the “transfer” permission.

Parameters:
  • amount (float) – The amount of the currency to withdraw. This paramater may also be a string to avoid floating point issues.
  • currency (str) – The type of currency to withdraw. i.e., USD, EUR, etc.
  • payment_method_id (str) – The id of the payment method on file to use.
Returns:

A dict with a withdrawal id, timestamp, and other withdrawal information.

Example:

{
    "id":"593533d2-ff31-46e0-b22e-ca754147a96a",
    "amount": "10.00",
    "currency": "USD",
    "payout_at": "2016-08-20T00:31:09Z"
}

Raises:
  • ValueError – The client is not configured for authorization.
  • APIRequestError – Any error generated by the Coinbase Pro API server.