Coinbase API接口指南：从入门到实践与应用

时间： 分类：知识 阅读：51

Coinbase API 接口使用指南：从入门到实践

Coinbase API 提供了强大的功能，允许开发者与 Coinbase 平台进行交互，实现自动化交易、数据获取、以及集成 Coinbase 服务到自己的应用程序中。本文将详细介绍 Coinbase API 的使用方法，涵盖认证、常用接口、以及示例代码，帮助你快速上手。

1. 认证 (Authentication)

访问 Coinbase API 必须通过身份验证，以确保只有授权用户才能访问其数据和功能。Coinbase API 主要支持两种身份验证机制：API 密钥 (API Keys) 和 OAuth2 协议。 选择合适的认证方法取决于应用程序的需求和安全考虑。

API 密钥 (API Keys): 这种方法涉及生成和使用唯一的密钥对，包括 API 密钥和 API 密钥密文（Secret Key）。 API 密钥是公开的标识符，用于识别发出请求的应用程序或用户。 API 密钥密文是保密的，用于签署请求以验证其真实性。 使用 API 密钥进行身份验证通常更简单快捷， 尤其适用于服务器端应用程序或命令行工具，因为它不需要用户交互式授权。 请务必妥善保管 API 密钥密文，避免泄露，推荐使用环境变量等安全方式存储。

OAuth2: OAuth2 是一种授权框架，允许第三方应用程序在用户授权的情况下访问 Coinbase 资源，而无需共享用户的 Coinbase 凭据。 用户需要在 Coinbase 平台上显式授予应用程序访问权限。 OAuth2 的流程涉及重定向用户到 Coinbase 授权页面，用户登录并授权应用程序，然后 Coinbase 会将授权码发送回应用程序。 应用程序使用授权码获取访问令牌 (Access Token)，该令牌用于后续的 API 请求。 OAuth2 适用于需要代表用户访问 Coinbase 数据的客户端应用程序，例如移动应用程序或 Web 应用程序。

鉴于其简便性和适用性， 建议优先考虑使用 API 密钥 (API Keys) 进行身份验证，尤其是在不需要用户交互授权的场景下。 API Keys 方便快捷，易于集成到各种应用程序中，可以显著简化开发过程。 然而，无论选择哪种认证方法，安全始终是至关重要的。 务必遵循 Coinbase 提供的安全最佳实践，例如定期轮换 API 密钥、限制 API 密钥的权限范围，以及安全地存储和管理密钥。

1.1 API 密钥

  • API 密钥是访问加密货币交易所、区块链数据提供商或其他相关服务的应用程序编程接口 (API) 的关键凭证。它们类似于网站的用户名和密码，但专为软件应用程序设计，而非人工用户。API 密钥允许您的应用程序以编程方式与服务进行交互，例如获取实时市场数据、执行交易、管理钱包或访问历史区块链信息。 每个 API 密钥通常都与特定的权限级别关联。这些权限决定了您的应用程序可以执行的操作。 例如，一个 API 密钥可能只允许您读取市场数据，而另一个则允许您进行交易。为了最大限度地提高安全性，务必了解并限制与每个 API 密钥关联的权限。 API 密钥的管理至关重要。您应该将它们视为敏感信息，并采取适当的预防措施来保护它们免遭未经授权的访问。这包括将它们存储在安全的位置，例如环境变量或密钥管理系统，并且绝不将它们硬编码到您的应用程序代码中或在公共存储库中共享它们。 当您不再需要 API 密钥时，应立即将其撤销。如果您的密钥遭到泄露，您应立即将其撤销并生成一个新密钥。许多服务提供商允许您监控 API 密钥的使用情况，这可以帮助您检测和应对任何可疑活动。 API 密钥是与加密货币服务进行编程交互的必要工具。正确理解和管理它们对于确保应用程序的安全性和功能至关重要。
获取 API Key: 登录 Coinbase 开发者平台 (通常需要在 Coinbase 账户中启用开发者功能)，创建新的 API Key。创建过程中，你需要指定 API Key 的权限范围 (scope)。 权限范围决定了该 API Key 可以访问哪些资源。 例如，你需要交易权限才能进行买卖操作，需要账户读取权限才能查询账户余额。
  • 存储 API Key: 强烈建议将 API Key 存储在安全的地方，例如环境变量或者密钥管理服务中，避免硬编码在代码中，防止泄露。
  • 使用 API Key: API Key 通过 HTTP 请求头 CB-ACCESS-KEY 和 CB-ACCESS-SIGN 传递。 CB-ACCESS-TIMESTAMP 也必须包含在请求头中，值为 Unix 时间戳。 CB-ACCESS-SIGN 是利用你的 API Secret (在创建 API Key 时获得) 对请求的某些部分进行 HMAC-SHA256 加密生成的。

    • 1.2 OAuth2

    OAuth2 协议为第三方应用程序提供了安全且标准化的方式，代表用户访问 Coinbase 账户。 它避免了应用程序直接处理用户 Coinbase 账户密码的需要，增强了安全性并简化了用户体验。

    • 创建 OAuth2 应用: 在 Coinbase 开发者平台上注册你的应用程序，这将为你分配一个唯一的 Client ID 和 Client Secret。 Client ID 用于标识你的应用程序，而 Client Secret 则用于验证你的应用程序的身份。 务必妥善保管 Client Secret，避免泄露。
    • 授权流程:
      1. 用户通过你提供的链接访问 Coinbase 的授权服务器，该链接包含了你的 Client ID 和所需权限的范围。 用户在此页面审查你的应用程序请求的权限，并选择是否授予访问权限。
      2. 如果用户授权你的应用程序，Coinbase 会将用户重定向回你在开发者平台注册时指定的重定向 URI，并附带一个授权码 (Authorization Code)。 该授权码是一个短期的凭证，用于换取 Access Token。
      3. 你的应用程序使用 Client ID、Client Secret 和授权码，通过 HTTPS POST 请求向 Coinbase 的 Token Endpoint (例如 https://api.coinbase.com/oauth/token ) 请求 Access Token。 该请求需要包含 grant_type=authorization_code 参数。
      4. Coinbase 验证你的应用程序的身份和授权码的有效性后，将返回一个 JSON 对象，其中包含 Access Token 和 Refresh Token。 Access Token 用于访问受保护的资源，而 Refresh Token 用于在 Access Token 过期后获取新的 Access Token。
    • 使用 Access Token: Access Token 必须包含在每个 API 请求的 HTTP 头部中，以验证你的应用程序的身份。 使用标准的 Authorization: Bearer 格式，将 Access Token 作为 Bearer Token 传递。 例如，如果要获取用户的账户信息，你可以发送一个带有 Authorization 头部的 GET 请求到 https://api.coinbase.com/v2/accounts 。
    • 刷新 Access Token: Access Token 具有有限的有效期，通常为几个小时。 为了避免用户需要重新授权你的应用程序，可以使用 Refresh Token 获取新的 Access Token。 使用 Client ID、Client Secret 和 Refresh Token，通过 HTTPS POST 请求向 Coinbase 的 Token Endpoint 请求新的 Access Token，这次需要包含 grant_type=refresh_token 参数。 Coinbase 将返回一个新的 Access Token 和 Refresh Token。 请注意，旧的 Refresh Token 可能会失效，因此建议在每次刷新 Access Token 后保存新的 Refresh Token。

    2. 常用 API 接口

    Coinbase API 提供了功能全面的接口集，覆盖加密货币交易生态系统的各个关键方面。这些接口可用于自动化交易策略、构建投资组合管理工具以及集成支付解决方案。具体来说，API涵盖以下几个核心领域：

    • 账户管理： 允许用户安全地访问和管理其Coinbase账户。这包括检索账户余额、历史交易记录、以及账户的详细信息，例如账户ID和账户类型。开发者可以利用这些API构建用户界面，方便用户查看和管理他们的资产。
    • 交易： 支持用户执行各种交易操作，例如买入和卖出加密货币。API 提供了创建市价单、限价单等不同类型的订单的能力，并允许开发者监控订单状态和取消未成交订单。通过API进行的交易会遵循Coinbase平台的交易规则和手续费结构。
    • 付款： 简化了加密货币的支付和收款流程。开发者可以使用这些API创建支付请求、发送加密货币到其他地址、以及验证交易的完成情况。这些API对于构建支持加密货币支付的电子商务平台或者应用程序非常有用。
    • 市场数据： 提供实时的市场信息，包括各种加密货币的价格、交易量、以及历史数据。开发者可以利用这些数据构建价格监控工具、量化交易模型以及市场分析平台。API通常会提供不同时间粒度的数据，例如分钟、小时或天。

    通过熟练掌握这些API接口，开发者可以构建强大的应用程序，充分利用 Coinbase 平台提供的功能和服务。在开发过程中，务必仔细阅读 Coinbase API 的官方文档，并遵循其最佳实践，以确保安全可靠的集成。

    2.1 账户 (Accounts)

    • GET /v2/accounts : 获取用户的所有账户列表。
      • 返回用户拥有的所有账户信息，涵盖账户的唯一标识符 (ID)、账户对应的加密货币或法币种类 (currency)、可用余额 (balance)，以及冻结余额等详细信息。该接口允许用户全面了解其资产配置概况。
    • GET /v2/accounts/:account_id : 获取指定账户的详细信息。
      • 通过提供 account_id ，可以检索特定账户的详细信息。返回的数据包括账户名称、账户类型 (fiat 法币账户或 crypto 加密货币账户)、创建时间、账户状态（例如，是否激活）以及其他与账户相关的配置信息。
    • GET /v2/accounts/:account_id/transactions : 获取指定账户的交易历史记录。
      • 以分页方式返回指定账户的交易记录，包括买入 (buy)、卖出 (sell)、充值 (deposit)、提现 (withdrawal)、转账 (transfer) 以及其他类型的交易。该接口支持时间范围查询，允许用户指定查询的起始时间 (start_time) 和结束时间 (end_time)，便于用户追踪特定时间段内的交易活动。还可以通过参数控制每页返回的交易记录数量 (limit) 和页码 (page)。
    • POST /v2/accounts/:account_id/primary : 设置指定账户为主要账户。
      • 允许用户将某个账户指定为主要账户。主要账户通常用于默认的交易操作和资金结算。

    2.2 交易 (Buys/Sells)

    • GET /v2/accounts/:account_id/buys : 获取指定账户的买入订单列表。该接口允许开发者检索特定账户的所有买入订单，并可根据创建时间、订单状态等参数进行筛选和排序，以便进行订单管理和分析。返回数据通常包含订单ID、创建时间、购买金额、购买币种、订单状态（例如：pending, completed, canceled）等详细信息。
    • POST /v2/accounts/:account_id/buys : 创建买入订单。通过该接口，用户可以提交新的买入订单请求。
      • 需要指定购买的金额、币种、以及支付方式。 amount 参数定义购买金额， currency 参数指定购买的加密货币种类（如BTC, ETH）， payment_method_id 参数指定支付方式，可能是银行账户、信用卡或其他已绑定的支付渠道。还可能需要指定价格限制（如限价单）或其他高级订单参数，以满足特定的交易策略需求。
    • GET /v2/accounts/:account_id/buys/:buy_id : 获取指定买入订单的详细信息。通过提供唯一的 buy_id ，可以检索特定买入订单的完整信息，包括订单创建时间、执行价格、手续费、订单状态、已成交数量、剩余未成交数量等关键数据，便于用户跟踪订单执行情况。
    • GET /v2/accounts/:account_id/sells : 获取指定账户的卖出订单列表。该接口与买入订单列表接口类似，但返回的是指定账户的所有卖出订单信息。可以利用该接口检索历史卖单，分析交易行为。
    • POST /v2/accounts/:account_id/sells : 创建卖出订单。该接口允许用户提交新的卖出订单请求。
      • 需要指定出售的金额、币种、以及收款方式。类似于买入订单， amount 参数定义出售金额， currency 参数指定出售的加密货币种类， payment_method_id 参数指定收款方式，即资金将转入的账户。同样可能需要指定价格限制和高级订单参数。
    • GET /v2/accounts/:account_id/sells/:sell_id : 获取指定卖出订单的详细信息。与获取买入订单详细信息接口类似，通过提供唯一的 sell_id ，可以检索特定卖出订单的完整信息，用于订单跟踪和状态查询。

    2.3 付款 (Payments)

    • POST /v2/accounts/:account_id/transactions/:transaction_id/complete : 完成处于pending状态的交易。此接口允许用户确认并完成先前发起的交易，例如，在双因素认证或其他安全措施验证通过后，将交易状态从待处理更改为已完成。 :account_id 代表用户的账户ID， :transaction_id 代表待完成交易的唯一ID。正确使用此接口对于确保交易顺利执行至关重要。
    • GET /v2/prices/:currency_pair/buy : 获取指定货币对的买入价格。此接口返回购买特定加密货币的价格，适用于用户希望以指定货币购买另一种加密货币的场景。 :currency_pair 参数指定了需要查询的货币对，例如"BTC-USD"表示比特币兑美元的价格。该价格通常包含交易费用和平台利润，反映了用户实际购买的成本。
    • GET /v2/prices/:currency_pair/sell : 获取指定货币对的卖出价格。该接口返回出售特定加密货币的价格，适用于用户希望将指定货币兑换成另一种加密货币的场景。同样， :currency_pair 参数指定了要查询的货币对。此价格通常低于买入价，其中的差额代表了交易平台的利润。
    • POST /v2/prices/:currency_pair/spot : 获取货币对的即时价格。 该接口提供货币对的最新市场价格，反映了当前供求关系。 与buy和sell接口不同，spot接口返回的是中间价格，不包含交易费用或平台利润。 可以作为基准价格用于参考，或者在计算交易价格之前使用。 :currency_pair 参数同样指定了要查询的货币对。此接口提供的数据通常用于实时行情显示和交易策略制定。

    2.4 市场数据 (Market Data)

    • GET /v2/currencies : 获取支持的加密货币列表。
      • 返回 Coinbase 平台支持的所有加密货币的详细信息，包括但不限于：
        • 币种代码 (Currency Code): 用于唯一标识该币种的字符串，例如 "BTC" 代表比特币。
        • 币种名称 (Currency Name): 币种的完整名称，例如 "Bitcoin"。
        • 最小购买量 (Minimum Order Size): 允许的最小交易数量，用于限制微小订单。
        • 最大购买量 (Maximum Order Size): 允许的最大交易数量，用于控制巨额订单。
        • 支持的网络 (Supported Networks): 该币种支持的区块链网络，例如 "Ethereum Mainnet (ERC-20)"。 这指示了该币种可能存在的不同版本，例如通过以太坊发行的代币。
        • 可交易状态 (Tradeable Status): 指示该币种当前是否允许交易，例如 "online" 表示可交易，"offline" 表示不可交易。这可能受到维护、监管或其他因素的影响。
    • GET /v2/exchange-rates : 获取加密货币汇率信息。
      • 允许指定基础货币 (base currency) 和目标货币 (target currency)，从而获取两者之间的汇率。 例如，可以查询 BTC/USD（比特币/美元）的汇率。
        • 基础货币 (Base Currency): 你希望转换的原始货币，例如比特币 (BTC)。
        • 目标货币 (Target Currency): 你希望转换成的目标货币，例如美元 (USD)。
        • 返回的数据将包含汇率，例如 "1 BTC = 50000 USD"。
        • API通常会返回包含时间戳的汇率，以便追踪历史汇率数据。
        • 汇率可能来自不同的交易所或数据源，API 应明确说明数据来源。

    3. 示例代码 (Python)

    以下是一个使用 Python 和 requests 库获取 Coinbase 账户余额的示例代码。为了安全起见，API Key 和 Secret 不应硬编码在脚本中，而应从环境变量中读取。请务必替换示例代码中的 API Key、Secret 和账户 ID 为你自己的有效值。

    requests 库是 Python 中用于发送 HTTP 请求的标准库。如果尚未安装，可以使用 pip install requests 命令进行安装。

    import requests import time import hmac import hashlib import os

    API_KEY = os.environ.get('COINBASE_API_KEY') # 从环境变量中获取 API Key API_SECRET = os.environ.get('COINBASE_API_SECRET') # 从环境变量中获取 API Secret ACCOUNT_ID = 'YOUR_ACCOUNT_ID' # 替换为你的账户ID

    def generate_signature(timestamp, method, request_path, body=''): """ 生成 Coinbase API 请求所需的签名。 Args: timestamp (str): Unix 时间戳。 method (str): HTTP 请求方法 (例如: GET, POST, DELETE)。 request_path (str): 请求路径 (例如: /v2/accounts)。 body (str): 请求体 (如果存在)。 Returns: str: 计算出的 HMAC SHA256 签名。 """ message = str(timestamp) + method + request_path + body hmac_object = hmac.new(API_SECRET.encode('utf-8'), message.encode('utf-8'), hashlib.sha256) signature = hmac_object.hexdigest() return signature

    def get_account_balance(account_id): """ 获取指定 Coinbase 账户的余额。 Args: account_id (str): 要查询的账户 ID。 """ url = f'https://api.coinbase.com/v2/accounts/{account_id}' method = 'GET' timestamp = str(int(time.time())) request_path = f'/v2/accounts/{account_id}' signature = generate_signature(timestamp, method, request_path) 

    headers = {
    'CB-ACCESS-KEY': API_KEY,
    'CB-ACCESS-SIGN': signature,
    'CB-ACCESS-TIMESTAMP': timestamp,
    'CB-VERSION': '2021-03-31'  # 建议指定 API 版本以确保 API 行为的可预测性
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # 检查 HTTP 状态码，如果不是 200 则抛出异常
    data = response.()  # 将响应解析为 JSON 格式
    balance = data['data']['balance']['amount']
    currency = data['data']['balance']['currency']
    print(f'账户 {account_id} 余额: {balance} {currency}')
except requests.exceptions.RequestException as e:
    print(f'请求失败: {e}')
except KeyError:
    print('无法解析响应数据，请检查 API Key 和 Secret 是否正确，以及账户 ID 是否存在。也可能是API返回格式发生了变化，请检查Coinbase API 文档。')
except Exception as e:
    print(f'发生未知错误: {e}')

    if __name__ == '__main__': get_account_balance(ACCOUNT_ID)

    4. 错误处理 (Error Handling)

    Coinbase API 通过返回不同类型的 HTTP 状态码和 JSON 格式的错误消息来指示请求是否成功。理解并妥善处理这些错误是构建健壮应用程序的关键。常见的 HTTP 状态码及其含义包括：

    • 400 Bad Request : 请求参数无效或缺失。这意味着客户端发送的请求格式不正确，例如，参数类型错误、缺少必要的参数或参数值超出范围。详细的错误信息通常会包含在响应的 JSON 数据中，说明具体哪个参数存在问题。
    • 401 Unauthorized : 认证失败，通常是由于缺少有效的 API 密钥，或者 API 密钥已过期或被吊销。 检查请求头中的 Authorization 字段是否正确设置，并且 API 密钥具有访问所需资源的权限。
    • 403 Forbidden : 权限不足。即使已经通过认证，也可能因为 API 密钥没有足够的权限访问特定的资源或执行特定的操作。检查 API 密钥的权限设置，确保其具有执行相关操作的权限。
    • 404 Not Found : 请求的资源不存在。 这可能是因为请求的 URL 不正确，或者请求的资源已被删除。 仔细检查 URL 的拼写和资源 ID 是否正确。
    • 429 Too Many Requests : 请求过于频繁，触发了速率限制。Coinbase API 对请求频率有限制，超过限制会导致此错误。 建议实施指数退避算法来重试请求，并监控 API 的使用情况，避免超出速率限制。 响应头通常会包含 Retry-After 字段，指示在多长时间后可以重试请求。
    • 500 Internal Server Error : 服务器内部错误。 这通常是 Coinbase 服务器端的问题，客户端无法直接解决。可以稍后重试请求，并检查 Coinbase 的状态页面以获取更多信息。 如果问题持续存在，可以联系 Coinbase 的支持团队。
    • 503 Service Unavailable : 服务不可用。 Coinbase 服务暂时不可用，通常是由于维护或过载导致。可以稍后重试请求，并检查 Coinbase 的状态页面以获取更多信息。

    在应用程序代码中，务必捕获并处理这些错误码。 采取的措施包括：

    • 重试请求： 对于临时性错误，例如 429 Too Many Requests 或 503 Service Unavailable ，可以使用指数退避策略重试请求。
    • 记录错误日志： 将错误信息记录到日志文件中，以便进行调试和监控。日志应包含错误码、错误消息、请求 URL 和相关参数。
    • 向用户显示友好的错误信息： 不要向用户显示原始的错误码和错误消息。 相反，应提供用户友好的错误信息，帮助他们了解发生了什么问题，并提供解决方案。
    • 监控错误率： 监控应用程序的错误率，以便及时发现和解决问题。 使用监控工具可以帮助你跟踪错误数量和类型，并设置警报，以便在错误率超过阈值时收到通知。
    • 验证请求参数： 在发送请求之前，验证请求参数是否有效。 这可以避免 400 Bad Request 错误，并提高应用程序的可靠性。

    通过有效的错误处理，可以提高应用程序的健壮性和可靠性，并为用户提供更好的体验。 仔细阅读 Coinbase API 的文档，了解更多关于错误处理的信息。

    5. 速率限制 (Rate Limiting)

    Coinbase API 实施速率限制，旨在防止恶意滥用并确保所有用户的服务质量。速率限制的具体数值取决于所调用的 API 接口，不同端点的限制各有不同。当应用程序超出预设的速率限制时，API 将返回一个 429 Too Many Requests HTTP 状态码错误，表明请求已被服务器限制。

    为了最大限度地减少触发速率限制的可能性，并确保应用程序的稳定性和可靠性，建议采取以下最佳实践：

    • 缓存 API 响应数据： 实施有效的缓存策略，将频繁请求的 API 数据存储在本地。通过缓存，可以显著减少对 Coinbase API 的重复请求，减轻服务器压力，并加快应用程序的响应速度。需要根据数据的更新频率，合理设置缓存过期时间，保持数据的准确性。
    • 利用分页 (Pagination) 获取数据： 在需要获取大量数据时，不要一次性请求所有数据。采用分页机制，将数据分割成多个较小的页面进行逐步获取。这可以显著降低单次请求的数据量，避免超出速率限制，并提高数据传输的效率。
    • 实施重试机制 (Retry Mechanism)： 当应用程序收到 429 Too Many Requests 错误时，不要立即放弃。实施重试机制，在等待一段合理的时间后，重新尝试发送请求。 429 响应头中通常会包含 Retry-After 字段，指示服务器建议的等待时间。合理设置重试次数和等待时间，避免对服务器造成过大的压力。 使用指数退避算法，随着重试次数的增加，等待时间也相应增加。
    • 避免不必要的 API 调用： 仔细审查应用程序的逻辑，确保只在必要时才调用 API。避免循环调用、冗余调用或请求不必要的数据。优化数据处理流程，减少对 API 的依赖，从而降低触发速率限制的风险。 仔细检查请求参数，只请求必要的数据字段。
    • 监控 API 使用情况： 定期监控应用程序的 API 使用情况，跟踪请求数量和错误率。通过分析监控数据，可以及时发现潜在的速率限制问题，并采取相应的优化措施。可以利用 Coinbase 提供的 API 使用统计功能，或者使用第三方监控工具。
    • 阅读官方文档： 仔细阅读 Coinbase API 的官方文档，了解每个 API 接口的速率限制详情。 了解速率限制的计算方式，例如按分钟、按小时或按天计算。

    相关推荐：