Coinbase Pro API集成指南：交易、数据与账户管理

Coinbase Pro API 集成指南

简介

Coinbase Pro API 提供了一套强大的工具，允许开发者以编程方式访问 Coinbase Pro 交易所的功能。通过 API，您可以执行交易、获取市场数据、管理账户等等。 本文将引导您完成 Coinbase Pro API 的集成过程，并提供一些关键代码示例。

准备工作

在使用 Coinbase Pro API 之前，为了确保顺利集成和高效开发，您需要完成以下准备工作。 这些步骤涵盖了账户设置、API 密钥生成以及必要的安全措施，旨在保护您的交易安全和数据隐私：

1. Coinbase Pro 账户注册与验证： 访问 Coinbase Pro 官方网站，完成账户注册流程。 确保您提供的信息真实有效，并按照平台要求完成身份验证。 身份验证是使用 Coinbase Pro API 的先决条件，它有助于保障平台安全并符合监管要求。

Coinbase Pro 账户: 您需要一个有效的 Coinbase Pro 账户。如果您还没有账户，请前往 Coinbase Pro 官网注册。

API 密钥: 您需要生成 API 密钥才能访问 API。请按照以下步骤生成密钥：

• 登录您的 Coinbase Pro 账户。
• 点击右上角的用户名，然后选择“API”。
• 点击“+ 新建 API 密钥”。
• 设置密钥权限（例如，查看、交易）。建议为您的应用程序选择最小必要的权限集，以提高安全性。
• 为您的密钥设置一个名称。
• 输入您的双重身份验证代码。
• 复制您的 API 密钥、密钥密码和 API 密钥短语。 请务必妥善保管这些信息，因为它们将只显示一次。

编程语言和库: 选择您熟悉的编程语言（例如 Python、Java、Node.js）和相应的 HTTP 请求库（例如 requests、okhttp、axios）。 本文中，我们将使用 Python 和 requests 库作为示例。

API 认证

所有 Coinbase Pro API 请求都需要进行身份验证，以确保安全性和用户身份的识别。身份验证信息必须包含在每个 API 请求的头部中，缺少或不正确的身份验证信息会导致请求失败。

• CB-ACCESS-KEY : 您的 API 密钥，用于标识您的应用程序或账户。请务必妥善保管您的 API 密钥，避免泄露。
• CB-ACCESS-SIGN : 请求的数字签名，用于验证请求的完整性和真实性。数字签名是通过对请求的特定信息进行加密生成的，可以防止请求被篡改。
• CB-ACCESS-TIMESTAMP : 请求的时间戳（以秒为单位），用于防止重放攻击。时间戳表示请求发送的时间，服务器会验证时间戳是否在有效的时间范围内。
• CB-ACCESS-PASSPHRASE : 您的 API 密钥短语，是 API 密钥的密码，用于生成数字签名。密钥短语增加了 API 密钥的安全性，防止未经授权的使用。

数字签名的计算方式如下：

1. 将时间戳、请求方法（例如 GET、POST、DELETE）、请求路径（例如 /accounts、/orders）和请求主体（如果存在，例如 POST 请求中的 JSON 数据）连接成一个字符串。连接的顺序必须严格按照时间戳、方法、路径、主体的顺序。
2. 使用您的 API 密钥密码（ CB-ACCESS-PASSPHRASE ）作为密钥，对连接后的字符串进行 HMAC SHA256 加密。HMAC SHA256 是一种常用的加密算法，可以生成具有固定长度的哈希值。
3. 将加密结果转换为 Base64 编码。Base64 是一种将二进制数据转换为 ASCII 字符串的编码方式，方便在 HTTP 头部中传输。

以下 Python 代码演示了如何生成数字签名以及发送带身份验证信息的 API 请求：

import time import hmac import hashlib import base64 import requests import api_key = "YOUR_API_KEY" api_secret = "YOUR_API_SECRET" api_passphrase = "YOUR_API_PASSPHRASE" def generate_signature(timestamp, method, request_path, body=''): message = str(timestamp) + method + request_path + body hmac_key = base64.b64decode(api_secret) signature = hmac.new(hmac_key, message.encode('utf-8'), hashlib.sha256) signature_b64 = base64.b64encode(signature.digest()).decode('utf-8') return signature_b64 def make_request(method, endpoint, body=None): timestamp = str(time.time()) request_path = '/' + endpoint if body: body = .dumps(body) # Convert body to JSON string signature = generate_signature(timestamp, method, request_path, body if body else '') headers = { 'CB-ACCESS-KEY': api_key, 'CB-ACCESS-SIGN': signature, 'CB-ACCESS-TIMESTAMP': timestamp, 'CB-ACCESS-PASSPHRASE': api_passphrase, 'Content-Type': 'application/' } base_url = "https://api.pro.coinbase.com" url = base_url + request_path try: if method == 'GET': response = requests.get(url, headers=headers) elif method == 'POST': response = requests.post(url, headers=headers, data=body) elif method == 'DELETE': response = requests.delete(url, headers=headers) else: raise ValueError(f"Unsupported HTTP method: {method}") response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx) return response.() except requests.exceptions.RequestException as e: print(f"Request failed: {e}") if response is not None: try: print(f"Response content: {response.()}") except .JSONDecodeError: print(f"Response content: {response.text}") return None

# 示例用法：获取账户信息
accounts = make_request('GET', 'accounts')
if accounts:
    print(accounts)

# 示例用法：创建一个新的订单
new_order = {
    "size": "0.01",
    "price": "10000",
    "side": "buy",
    "product_id": "BTC-USD"
}
order = make_request('POST', 'orders', body=new_order)
if order:
    print(order)

请将 YOUR_API_KEY, YOUR_API_SECRET, 和 YOUR_API_PASSPHRASE 替换为您自己的 API 密钥信息。

获取账户信息

要获取您的账户详细信息，您可以使用 GET /accounts API 端点。这个端点允许你检索与你的账户相关的各种信息，包括账户余额、账户类型、创建日期等等。

使用此端点时，你需要确保提供正确的身份验证凭据，例如 API 密钥或访问令牌，以便服务器能够验证你的身份并授权你访问账户信息。未经授权的请求将被拒绝。

GET /accounts 端点通常会返回一个 JSON 对象，其中包含账户的详细信息。你可以解析这个 JSON 对象来提取你需要的信息。具体的返回格式和字段可能会因不同的加密货币交易所或服务提供商而异。请参考你所使用的 API 文档来了解详细的返回格式说明。

例如，一个典型的返回结果可能包含以下字段：

• account_id : 账户的唯一标识符。
• currency : 账户所持有的货币类型（例如，BTC、ETH、USD）。
• balance : 账户余额。
• available_balance : 可用余额（即可用于交易的余额）。
• pending_balance : 待处理余额（例如，正在进行的交易）。
• created_at : 账户创建的时间戳。
• status : 账户状态 (例如，活跃、冻结)。

请注意，在使用 GET /accounts 端点时，务必遵守 API 的使用限制，例如请求频率限制。过多的请求可能会导致你的 API 密钥被暂时或永久禁用。建议使用适当的缓存机制来减少对 API 的请求次数。

获取账户信息

通过 make_request 函数发起一个HTTP GET请求，目标端点为'accounts'，以获取用户的账户信息。 accounts = make_request('GET', 'accounts') 这段代码执行的核心在于与服务器建立连接，并发送请求以检索账户数据。如果请求成功，服务器将返回包含账户信息的JSON或其他格式的数据。

接下来，代码检查 accounts 变量是否包含有效数据。 if accounts: 如果 accounts 不为空（例如，请求成功且返回了数据），则将账户信息打印到控制台。 print("Accounts:", accounts) 打印输出的格式取决于服务器返回的数据结构，通常会包含账户ID、账户类型、当前余额、可用余额等关键信息。

上述代码段旨在检索并显示用户的账户信息，包括但不限于：账户ID、账户类型（例如，储蓄账户、交易账户）、账户余额、可用余额以及账户所使用的货币类型。 账户余额表示账户中持有的总金额，而可用余额则表示可以立即使用的金额，可能已扣除未决交易或冻结金额。货币类型则指明账户余额所使用的货币单位，例如人民币（CNY）、美元（USD）或欧元（EUR）。这些信息对于用户了解其财务状况至关重要。

下单

要提交交易订单，您可以使用 POST /orders 应用程序编程接口（API）端点。此端点允许您指定订单的各种参数，从而控制交易策略。您需要提供以下参数：

• product_id : 指定要交易的交易对。例如，对于比特币兑美元的交易，应使用“BTC-USD”。 确保您使用的交易对在交易所是可用并且活跃的。
• side : 指定交易方向。接受两个可能的值： buy 表示买入订单， sell 表示卖出订单。买入订单用于购买指定数量的标的资产，而卖出订单用于出售。
• type : 定义订单类型，它决定了订单的执行方式。常见的订单类型包括：
  • market : 市价单，以当前市场最佳可用价格立即执行。市价单保证执行，但不保证执行价格。
  • limit : 限价单，只有在达到或超过指定价格时才会执行。限价买单只有在价格等于或低于指定价格时才会执行，限价卖单只有在价格等于或高于指定价格时才会执行。
  • stop : 止损单，只有在市场价格达到指定的止损价格时才会变成市价单执行。 止损单用于限制潜在的损失或保护利润。
  • stop_limit : 止损限价单，只有在市场价格达到指定的止损价格时，才会变成限价单。
• size 或 funds : 用于指定订单大小。
  • size : 指定要购买或出售的资产数量。例如，如果您想购买 1 个比特币，则 size 值为 1。
  • funds : 指定要花费的金额（用于买入订单）或希望收到的金额（用于卖出订单）。例如，如果您想用 1000 美元购买比特币，则 funds 值为 1000。
  您必须提供 size 或 funds 中的一个，但不能同时提供两者。 选择哪一个取决于您的交易目标。
• price (如果 type 是 limit 或 stop_limit ): 只有当订单类型是限价单或止损限价单时，才需要 price 参数。它指定了订单执行的价格。对于限价买单， price 是您愿意支付的最高价格，对于限价卖单， price 是您希望收到的最低价格。对于止损限价单，当触发止损价格时，该价格将用作限价单的价格。

以下 Python 代码示例演示了如何提交一个限价买单，并提供了详细注释说明每个参数的作用：

Place a Limit Order

通过限价单，您可以指定希望买入或卖出加密货币的具体价格。以下代码展示了如何使用API提交限价单：

order_data = { 'product_id': 'BTC-USD', 'side': 'buy', 'type': 'limit', 'price': '30000', 'size': '0.001' }

这段代码定义了一个名为 order_data 的字典，它包含了创建限价单所需的所有关键信息。 product_id 指定了交易的币对（例如，BTC-USD，表示比特币兑美元）。 side 指定了交易方向（'buy' 表示买入，'sell' 表示卖出）。 type 设置为 'limit'，表明这是一个限价单。 price 设置了您希望交易的价格（这里是30000美元）。 size 指定了交易的数量（这里是0.001个比特币）。请注意， price 和 size 必须是字符串类型。

order = make_request('POST', 'orders', order_data) if order: print("Order:", order)

这段代码调用 make_request 函数，将订单数据通过POST请求发送到 'orders' API端点。 make_request 函数负责处理与API的通信，包括身份验证和错误处理。 如果订单成功提交，API将返回订单的详细信息，并打印到控制台。 如果 order 为 None ，则表示订单创建失败，通常是因为余额不足、API密钥无效或服务器错误。 在生产环境中，您应该添加更完善的错误处理机制，以便更好地诊断和解决问题。 请确保您的API密钥具有足够的权限来创建订单。

取消订单

在加密货币交易平台或相关应用中，取消订单是用户常见的操作。您可以使用 DELETE /orders/ REST API 端点来提交取消订单的请求。其中， 必须替换为需要取消的订单的唯一标识符，即订单ID。务必确认订单ID的准确性，以避免取消错误的订单。订单取消的权限通常受到时间窗口的限制；某些订单可能在执行后或接近成交时无法取消。 为了成功取消订单，您的API请求需要包含有效的身份验证信息，例如API密钥或Token，这用于验证您是否有权取消该订单。服务器通常会返回一个状态码，例如200 OK，表示订单已成功取消，或者返回一个错误代码，如果取消操作失败，例如订单不存在或已完成交易。请注意，订单取消的确认应以服务器返回的最终状态为准，而非仅仅依赖于客户端的请求发送结果。在某些高并发的交易系统中，取消请求也可能需要排队处理，因此订单状态的更新可能会有一定的延迟。

取消订单

要取消特定订单，您需要提供该订单的唯一标识符。请将以下代码中的 YOUR_ORDER_ID 替换为您要取消的订单的实际ID。订单ID通常是一个由字母和数字组成的字符串，可以在您的交易历史记录或订单确认邮件中找到。

order_id = "YOUR_ORDER_ID" # 替换为您的订单ID

接下来，我们需要构建取消订单的API端点。通常，这涉及将订单ID附加到基本的“orders”路径。以下代码演示了如何使用f-string格式化API端点。

cancel_endpoint = f'orders/{order_id}'

现在，我们可以向API发送一个 DELETE 请求来取消订单。 DELETE 请求是一种HTTP方法，用于指示服务器删除指定资源。 make_request 函数（这里仅为示例）负责处理与API的通信，包括身份验证、错误处理和数据序列化。它接收请求方法（ 'DELETE' ）和API端点（ cancel_endpoint ）作为参数。

cancelled_order = make_request('DELETE', cancel_endpoint)

我们需要检查订单是否已成功取消。如果 cancelled_order 变量包含一个值（例如，来自API的确认消息），则表示取消操作已成功。我们可以使用 print 语句将确认消息输出到控制台。

if cancelled_order: print("已取消订单:", cancelled_order)

请将 YOUR_ORDER_ID 替换为您要取消的订单 ID。

获取市场数据

Coinbase Pro API 提供了一系列强大的端点，用于访问实时和历史市场数据，方便用户进行交易决策和市场分析。 这些端点允许开发者获取各种信息，例如交易对详情、实时价格、历史价格走势以及订单簿数据。

• GET /products : 此端点返回 Coinbase Pro 上所有可用交易对的详细信息。 这些信息包括交易对 ID (例如 BTC-USD), 交易对的基本货币和报价货币，最小订单规模，以及交易状态等。 开发者可以利用此端点动态地了解平台支持的交易品种。
• GET /products/ /ticker : 通过指定交易对 ID，此端点实时返回该交易对的最新成交价、成交量、最高价和最低价等信息。 ticker 数据提供了对市场即时状态的快速概览，对于高频交易和算法交易至关重要。 例如，访问 /products/BTC-USD/ticker 将返回比特币与美元交易对的最新价格。
• GET /products/ /candles : 此端点允许用户检索指定交易对的历史 K 线数据。 K 线数据是金融市场分析的重要工具，它以图形方式展示了特定时间段内的开盘价、收盘价、最高价和最低价。 用户可以通过指定时间粒度（例如 1 分钟、5 分钟、1 小时等）来获取不同时间范围内的历史数据，并利用这些数据进行技术分析和趋势预测。

以下 Python 代码示例展示了如何使用 Coinbase Pro API 获取 BTC-USD 交易对的最新成交价：

Get Ticker Data

ticker = make_request('GET', 'products/BTC-USD/ticker') if ticker: print("Ticker:", ticker)

错误处理

在使用 API 时，开发者可能会遇到各种错误。Coinbase Pro API（现已迁移至Advanced Trade API）采用标准的 HTTP 状态码来指示错误情况。强烈建议开发者始终检查响应的状态码，并根据不同的状态码采取相应的处理措施，确保应用程序的健壮性和用户体验。API 的错误处理对于构建可靠的应用程序至关重要。

以下是使用 API 时常见的错误类型，以及它们所代表的含义和可能的解决方法：

• 400 Bad Request : 此错误表明请求的格式不正确，或者请求缺少必要的参数。可能的原因包括：参数类型错误、参数值超出范围、缺少必填参数等。开发者应仔细检查请求参数是否符合 API 文档的规范。
• 401 Unauthorized : 此错误表示身份验证失败，通常是由于 API 密钥无效、过期或权限不足导致的。开发者应检查 API 密钥是否正确配置，并确保拥有访问所需资源的权限。重新生成 API 密钥或联系 Coinbase 支持团队可以解决此问题。
• 403 Forbidden : 此错误表明您没有权限访问请求的资源。这可能是由于 API 密钥没有被授予访问特定端点的权限，或者您的账户被禁止访问该资源。检查您的 API 密钥权限设置，并确保您有权执行所需的操作。
• 429 Too Many Requests : 此错误表示您已超出速率限制。Coinbase Pro API 对每个 API 密钥都有速率限制，以防止滥用和维护系统的稳定性。开发者应实现速率限制处理机制，例如使用指数退避算法，以避免触发此错误。可以查看API文档了解具体的速率限制策略。
• 500 Internal Server Error : 此错误表明服务器内部发生错误。这通常是由于 Coinbase 服务器的问题，开发者无法直接解决。建议稍后重试请求。如果问题持续存在，请联系 Coinbase 支持团队。

您的代码应该能够优雅地处理这些错误，并向用户提供有用的错误信息，以便他们了解发生了什么问题，并采取适当的措施。 make_request 函数中的 try...except 块已经初步处理了网络请求错误（例如连接超时、连接被拒绝）和 JSON 解码错误。为了实现更健壮的错误处理，您还需要针对特定 API 端点可能返回的不同错误类型进行检查。例如，针对订单创建 API，您需要处理资金不足、订单大小超出限制等错误。