Coinbase 全球站 API 接口文档
一、概述
Coinbase 提供了一套功能丰富且高效的 API 接口，旨在为开发者和企业提供全面的自动化服务，帮助他们在其平台上进行各类操作。这些 API 支持访问多种功能，包括获取实时市场数据、执行交易操作、管理用户账户、进行资产转移和查询交易历史等。开发者可以通过安全的 HTTPS 请求与 Coinbase 平台进行交互，所有返回的数据均以 JSON 格式提供，便于与其他系统和应用进行集成与处理。Coinbase 的 API 设计灵活，支持多种交易所功能、钱包管理及账户管理，用户可以通过这些接口实现高效的资金管理和数据分析。无论是个人开发者进行小规模自动化操作，还是大型企业构建复杂的交易平台，Coinbase 的 API 都能提供可靠的技术支持和便捷的开发方式。API 的文档详细且易于理解，开发者可以轻松上手并快速实现各种功能，极大地提升了应用程序的开发效率。
二、API 认证
为了确保用户账户的安全性并防止未授权访问，Coinbase API 采用了基于 API 密钥的认证机制。这种机制通过生成和验证唯一的 API 密钥来对用户身份进行验证。用户需要在 Coinbase 账户的 API 管理页面中创建自己的 API 密钥，并在每次发起 API 请求时使用该密钥。每个 API 密钥都有独立的权限设置，允许用户根据自己的需求配置访问权限，包括查看账户余额、执行交易、管理账户设置等操作。
API 密钥由一个公钥和私钥组成，公钥用于识别请求者身份，而私钥则用于加密请求，确保请求在传输过程中不被篡改。为了进一步保障 API 密钥的安全，用户应避免将其暴露在公共或不安全的环境中，特别是在代码中或日志文件里。为加强安全性，用户还可以设置 IP 白名单限制，仅允许来自特定 IP 地址的请求通过。
除了基础的 API 密钥认证外，Coinbase 还提供了额外的安全措施，如两步验证 (2FA)，进一步增加账户的安全防护层级。通过这种方式，即便 API 密钥被泄露，未经授权的用户仍然无法通过认证。对于开发者而言，定期轮换 API 密钥并监控 API 请求日志是良好的安全实践，能够有效降低潜在的安全风险。
1. 生成 API 密钥
为了开始使用 Coinbase 提供的 API，用户需要先登录到 Coinbase 账户，并进入账户的“设置”页面。接着，在设置页面中找到并点击“API 密钥管理”选项，这将允许用户管理与 Coinbase API 相关的所有设置。用户可以在此处创建一个新的 API 密钥，系统会提供一个简单的向导来帮助用户完成创建过程。
在创建 API 密钥时，用户需要为其选择适当的权限，以确保 API 的访问控制符合安全要求。可用的权限选项包括只读权限（仅允许获取账户信息、行情数据等非敏感数据）、交易权限（允许执行买卖交易）、提现权限（允许提取资产至外部地址）等。用户应根据需要选择最小权限原则，以减少潜在的安全风险。
完成 API 密钥创建后，系统将生成并显示一个唯一的 API 密钥和一个与之关联的密钥签名。API 密钥用于身份验证，并允许应用程序通过 API 发起请求。密钥签名是通过私钥加密生成的，用于确保 API 请求的完整性和防篡改性。当 API 请求发送至 Coinbase 服务器时，系统将使用该签名进行验证，确保请求的来源和内容的合法性。
为保障账户的安全，强烈建议用户将 API 密钥和密钥签名保存在安全的地方，并避免与他人共享。若泄露了这些信息，恶意第三方可能会利用它们访问账户或进行未经授权的操作。
2. 认证方式
为了确保每个 API 请求的安全性和可靠性，所有请求必须包含以下认证信息，以便进行身份验证和请求完整性校验：
- API 密钥：每个 API 请求必须携带一个唯一的 API 密钥，该密钥用于识别发起请求的用户账户。在请求头部中，必须使用
CB-API-KEY参数传递此密钥，确保请求来源是合法的。 - API 签名：为了确保请求未被篡改，并验证请求的真实性，必须使用 HMAC-SHA256 算法对请求的内容进行签名。签名计算的输入包括 API 密钥、请求路径、请求体（如果有）、以及请求的时间戳等信息。签名计算完成后，生成的签名结果需要通过
CB-API-SIGN参数在请求头中发送。 - 请求时间戳：每个请求都必须带有一个时间戳，该时间戳采用 UNIX 时间戳格式（自 1970 年 1 月 1 日以来的秒数），以防止重放攻击。该时间戳将通过
CB-API-TIMESTAMP参数发送，并且请求的时间戳和实际请求发起的时间必须相差较小（通常是几秒钟内），否则请求会被视为无效。
为了更清晰地展示认证方式，以下是一个示例请求头格式：
CB-API-KEY:
CB-API-SIGN:
CB-API-TIMESTAMP:
其中，api_key 是您的 API 密钥，signature 是使用 HMAC-SHA256 算法生成的签名，timestamp 是请求发起时的 UNIX 时间戳。确保这些信息的准确性和一致性至关重要，因为任何不匹配都会导致请求被拒绝。
三、API 端点
Coinbase 的 API 提供了多个端点，分为市场数据接口、账户管理接口、交易接口等，具体的 API 路径和功能如下：
1.1 获取市场现货价格
该接口允许用户获取指定交易对的最新市场现货价格，包括成交价格、买卖报价等详细信息。通过该接口，用户能够实时了解市场行情，从而作出更为精准的交易决策。
- 请求方法：GET
- 请求路径：
/products/<product_id>/ticker - 请求示例：
http
GET /products/BTC-USD/ticker
- 响应示例：
{ "trade_id": 123456, "price": "50000.00", "size": "0.001", "bid": "49999.00", "ask": "50001.00", "time": "2025-02-08T12:00:00Z" }
字段说明：
- trade_id：该交易的唯一标识符，通常用于追踪具体的交易记录。
- price：最新成交的市场价格，通常表示最后一次交易的价格。
- size：此次交易的数量，表示成交的资产数量。
- bid：当前市场的最高买入价格，即买方愿意支付的价格。
- ask：当前市场的最低卖出价格，即卖方愿意接受的价格。
- time：数据的时间戳，表示该数据的生成时间，通常以UTC格式表示。
该接口返回的最新市场数据帮助用户了解当前市场的供需情况，以及可能的价格波动。通过该信息，用户可以根据实时市场状态调整交易策略。
1.2 获取交易历史
该接口用于返回指定交易对的历史交易数据，涵盖了特定时间范围内所有相关的交易信息。用户可以通过此接口查询到特定资产对（如比特币对美元的交易对）在不同时间点的交易记录，包括交易价格、交易数量、买卖方向等关键信息。接口的响应数据有助于用户追踪市场动态，分析历史交易趋势，或用于进一步的交易策略开发。
- 请求方法：GET
- 请求路径：
/products/<product_id>/trades - 请求说明：
请求中需要替换<product_id>为目标交易对的ID。例如，BTC-USD代表比特币对美元的交易对。 - 请求示例：
http
GET /products/BTC-USD/trades
- 响应示例：
响应结果为JSON格式，包含多个交易记录。每条记录描述一次具体的交易事件，其中包括以下字段：
- trade_id：交易的唯一标识符，确保每一笔交易都可以被独立识别和追踪。
- price：交易发生时的单价，以基础货币（如BTC或USD）表示。
- size：本次交易的数量，表示交易中资产的数量（例如比特币的数量）。
- side：交易的方向，指示该笔交易是买入（
buy）还是卖出（sell）。 - time：交易发生的时间，格式为ISO 8601标准时间戳（例如“2025-02-08T12:00:00Z”）。
示例响应数据：
[ { "trade_id": 123456, "price": "50000.00", "size": "0.001", "side": "buy", "time": "2025-02-08T12:00:00Z" }, { "trade_id": 123457, "price": "50010.00", "size": "0.002", "side": "sell", "time": "2025-02-08T12:01:00Z" } ]
此响应数据示例展示了两笔交易记录：第一笔是以50000美元的价格购买0.001比特币，第二笔是以50010美元的价格卖出0.002比特币。每笔交易都被清晰地标注了时间戳、交易方向及交易量，便于用户获取和分析市场交易的历史信息。
2.1 获取账户余额
用户可以查询其所有账户的余额，包括主账户和子账户。该功能适用于获取指定账户的当前资产余额，支持不同种类的货币（如法币和加密货币）。用户可以通过调用该接口查询每个账户的余额信息，并可以根据需要获取不同币种的实时余额。响应数据中包含了账户的唯一标识符、当前余额以及账户所持有的货币类型，确保用户能够轻松查看和管理他们的资金。
- 请求方法：GET
- 请求路径：
/accounts - 请求参数：
- currency（可选）：用于指定查询的货币类型（如 "BTC" 或 "USD"）。如果未指定，默认返回所有账户余额。
- type（可选）：用于指定账户类型（如 "main" 或 "sub"），以便获取主账户或子账户的余额。如果未指定，默认返回所有账户的余额。
- 请求示例：
http
GET /accounts
- 响应示例：
以下为示例响应，展示了用户的不同账户及其相应的余额信息。每个账户的响应数据包含账户 ID、余额以及货币类型：
[ { "id": "abc123", "balance": "1.2345", "currency": "BTC" }, { "id": "def456", "balance": "1000.00", "currency": "USD" } ]
在响应中，id字段代表账户的唯一标识符，balance字段表示该账户当前的余额，currency字段则指明该余额对应的货币类型。根据用户请求的货币类型和账户类型，响应的数据将展示相应的账户余额。
2.2 获取单个账户信息
用户可以通过API查询特定账户的详细信息，包括账户的ID、余额、货币类型以及账户创建和更新的时间等重要数据。这些信息对于用户管理其账户、进行资金监控和履行合规要求具有重要意义。
- 请求方法：GET
- 请求路径：
/accounts/<account_id>，其中<account_id>是用户账户的唯一标识符，通常是由字母和数字组成的字符串，用于在系统中准确定位特定账户。 - 请求示例：用户可以通过以下示例请求获取账户信息：
http
GET /accounts/abc123
- 响应示例：成功请求时，系统将返回账户的详细信息，包括账户ID、当前余额、使用的货币类型，以及账户的创建和最后更新时间。以下是响应的JSON格式示例：
{ "id": "abc123", "balance": "1.2345", "currency": "BTC", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2025-02-08T12:00:00Z" }
在上述响应中：
- id：这是账户的唯一标识符，能够唯一地确定用户的账户。
- balance：该字段表示账户当前的余额，单位为相应货币。余额以数字形式表示，支持小数点后多位。
- currency：表示账户中资金的货币类型。例如，如果该账户存储的是比特币，则该字段的值为"BTC"。
- created_at：账户创建的时间戳，表示该账户首次在系统中注册的时间。该时间格式遵循ISO 8601标准。
- updated_at：账户的最后更新时间戳，表示账户最近一次更新或修改的时间。
3.1 创建新订单
用户可以通过此接口在指定市场创建一个新的交易订单。该接口支持设置订单的详细参数，包括交易市场、交易方向、价格、数量以及订单类型等。创建订单的过程中，用户需要提供所有必要的交易信息，以确保订单能够准确创建并正确执行。
- 请求方法：POST
- 请求路径：
/orders - 请求参数：订单创建请求需要包括以下字段：
- product_id：指定交易对的标识符，例如
BTC-USD，表示比特币与美元的交易对。 - side：指定订单的方向，可以是
buy（买入）或sell（卖出）。 - price：指定订单的价格。对于限价订单，此字段是必需的。
- size：指定订单的数量，表示希望交易的资产数量。
- type：指定订单类型，可以是
limit（限价订单）或market（市价订单）。 - 请求示例：
http
POST /orders
Content-Type: application/
{ "product_id": "BTC-USD", "side": "buy", "price": "50000.00", "size": "0.001", "type": "limit" }
- 响应示例：
- 字段说明：响应中返回的各个字段代表订单的详细信息，包括订单的唯一标识、状态、交易对、方向、价格、数量以及创建时间等。
{ "id": "order123", "status": "open", "product_id": "BTC-USD", "side": "buy", "price": "50000.00", "size": "0.001", "created_at": "2025-02-08T12:00:00Z" }
响应中字段详细说明：
- id：订单的唯一标识符，用户可通过此 ID 查询或取消订单。
- status：订单的当前状态。常见状态包括
open（未成交）、filled（已完全成交）、partially_filled（部分成交）和cancelled（已取消）。 - product_id：指定交易对标识符，例如
BTC-USD，表示交易市场。 - side：订单的方向，可能的值为
buy或sell，分别表示买入和卖出。 - price：订单的限价价格，当订单类型为
limit时此字段为必填项。 - size：订单的数量，表示希望交易的资产数量。
- created_at：订单的创建时间，采用 ISO 8601 格式的时间戳。
3.2 获取订单信息
此接口用于返回指定订单的详细信息，帮助用户了解订单的状态、交易对、价格、数量等重要信息。此功能对于用户管理订单以及跟踪订单执行情况至关重要，特别是在高频交易或者需要实时监控订单状态的场景下。
- 请求方法：GET
- 请求路径：
/orders/<order_id> - 请求参数：
- order_id：指定订单的唯一标识符，通常是一个字符串（如 "order123"），该参数在路径中传递。
请求示例：
http GET /orders/order123
- 响应示例：
成功响应将返回订单的详细信息，包含以下字段：
- id：订单的唯一标识符，通常是一个字符串（如 "order123"）。
- status：订单当前的状态，可能的状态包括：
open（订单尚未完全成交），filled（订单已完全成交），partially_filled（订单部分成交），cancelled（订单已取消），pending（订单待处理）等。 - product_id：订单交易的市场标识符，通常是一个交易对的字符串，如 "BTC-USD" 表示比特币和美元的交易对。
- side：订单的方向，可能的值为：
buy（买入）或sell（卖出）。 - price：订单的指定价格，单位通常与交易对相关，如 "50000.00" 表示价格为 50000 美元。
- size：订单的交易数量或规模，通常是以交易对的基础资产为单位，举例来说，"0.001" 表示交易数量为 0.001 个比特币。
- created_at：订单的创建时间，采用 ISO 8601 格式表示，如 "2025-02-08T12:00:00Z" 表示该订单在 2025 年 2 月 8 日 12 点 00 分 00 秒（UTC 时间）创建。
- filled_size：已成交的数量，表示订单中已经被匹配并执行的数量。例如 "0.0005" 表示该订单已经成交了 0.0005 个比特币。
- remaining_size：剩余未成交的数量，等于订单的
size减去已成交的filled_size。 - last_filled_at：上次成交的时间，采用 ISO 8601 格式表示。
- avg_fill_price：订单的平均成交价格，是该订单的已成交部分的加权平均价格。
响应示例：
{ "id": "order123", "status": "open", "product_id": "BTC-USD", "side": "buy", "price": "50000.00", "size": "0.001", "created_at": "2025-02-08T12:00:00Z", "filled_size": "0.0005", "remaining_size": "0.0005", "last_filled_at": "2025-02-08T12:30:00Z", "avg_fill_price": "49990.00" }
3.3 取消订单
用户可以取消一个尚未被执行的订单。取消订单的操作适用于所有类型的未成交订单，无论其当前状态如何。此操作将从订单簿中移除该订单，并将其标记为已取消状态。取消请求一旦成功，用户将无法恢复该订单。
- 请求方法：DELETE
- 请求路径：
/orders/<order_id> - 请求参数：订单的唯一标识符
<order_id>，这是用户在提交订单时系统自动生成的ID。用户必须提供准确的订单ID才能执行取消操作。 - 请求示例：
DELETE /orders/order123
- 响应示例：
在成功取消订单的情况下，系统将返回以下JSON格式的响应：
{
"id": "order123",
"status": "canceled",
"product_id": "BTC-USD",
"side": "buy",
"price": "50000.00",
"size": "0.001",
"created_at": "2025-02-08T12:00:00Z"
}
响应中包含的字段说明如下：
- id：订单的唯一标识符，取消后的订单仍保留其原始ID，便于追溯。
- status：订单当前的状态。对于成功取消的订单，状态将更新为
"canceled"。 - product_id：订单所涉及的交易对ID，表示用户交易的资产对（如：
BTC-USD表示比特币与美元的交易对）。 - side：订单类型，表示买入或卖出。此字段为
"buy"表示用户希望买入资产。 - price：订单的价格，表示用户愿意为每个单位资产支付的金额。在此示例中，用户的价格为
50000.00。 - size：订单的数量，表示用户希望买入或卖出的资产数量。在此示例中，数量为
0.001比特币。 - created_at：订单创建的时间戳，格式为ISO 8601。该字段显示订单的创建时间，便于追溯历史订单。
四、错误处理
Coinbase API 在遇到错误时会返回一个标准的错误响应，其中包含错误代码和详细的错误信息。错误响应的格式如下：
- 响应示例：
{ "message": "Invalid API Key", "error": "Unauthorized", "status": 401 }
常见错误代码包括：
- 401 Unauthorized：认证失败，API 密钥无效。
- 400 Bad Request：请求参数错误。
- 404 Not Found：请求的资源不存在。
- 500 Internal Server Error：服务器错误。
五、请求限制
为了防止滥用并确保系统的稳定性与可靠性，Coinbase 对 API 请求的频率实施了严格的限制。这些限制旨在防止过度请求对平台服务造成负担，同时也保障其他用户的正常访问。为确保 API 的公平使用，所有用户必须遵守以下请求频率限制：
- 每秒最多 10 次请求。此限制适用于所有通过 API 发出的请求，无论是查询市场数据、获取账户信息，还是进行交易操作。
- 每分钟最多 100 次请求。此限制适用于所有 API 请求的总量，超过此频率将触发错误响应。
当用户的请求频率超过上述限制时，API 会返回 429 Too Many Requests 错误代码。这表示请求的次数已超出允许的最大值，系统将要求用户暂时停止发送请求并等待一段时间后重新尝试。此等待期的时长通常由服务端动态决定，以防止服务被过度加载。
为了避免触发该错误代码，建议用户在开发应用时实现请求的节流机制或使用适当的重试策略。开发者可以通过监控 API 响应中的 Retry-After 头信息来获取建议的等待时间，以便更智能地管理请求频率。
用户还应关注账户的使用情况，避免在短时间内发出大量重复请求，以优化操作效率并避免受到频率限制的影响。在进行高频交易或数据拉取时，尤其需要谨慎控制 API 调用的频率，确保不会违反规定。
六、WebSocket API
Coinbase 提供了强大的 WebSocket API，允许用户通过持久的双向连接实时获取各类市场数据、订单信息、交易执行情况等关键内容。WebSocket API 是一种基于事件驱动的协议，能够提供低延迟的数据传输，确保用户和系统之间的交互及时性。借助 WebSocket，开发者可以创建一个持续的连接，从而实时接收和订阅不同类别的数据流，如实时市场行情、订单簿、交易记录等。WebSocket API 还支持高频交易和流式数据传输，非常适合需要高实时性的数据交换场景。
- 请求方法：GET
- 请求路径：
wss://ws-feed.pro.coinbase.com - 连接模式：WebSocket 协议（wss）
- 支持的消息类型：市场数据、订单信息、交易记录、系统状态等
- 认证要求：对于某些特定数据流，可能需要进行身份验证，通过 API 密钥或 OAuth 进行认证
- 连接保持：WebSocket 连接会保持持久开放，直到明确关闭，支持实时更新，无需重复请求
- 数据传输格式：所有数据以 JSON 格式传输，方便解析和处理
WebSocket API 是连接到 Coinbase Pro 的核心工具之一，它能够提供几乎毫秒级的数据更新速度，对于需要高实时性和精确交易执行的应用来说，WebSocket 是一个理想的选择。通过 WebSocket API，用户可以订阅不同的市场对（例如 BTC-USD、ETH-USD 等），以便接收这些市场对的最新行情和交易信息。API 还支持订阅订单簿的更新，帮助用户获得每个市场中订单的深度和流动性情况。
开发者还可以通过 WebSocket API 设置自定义的消息订阅规则，根据不同的需求订阅特定的数据流。例如，开发者可以订阅实时价格波动、交易量、买卖盘更新等，也可以监听特定的订单状态或交易执行情况，从而实现个性化的数据展示或交易策略。