在加密货币交易平台的集成开发中，有效追踪和管理交易状态至关重要。通过专用的 API 接口，开发者能够实时获取用户交易数据，并为用户提供透明、及时的交易信息反馈。本文将深入解析交易状态 API 和历史交易 API 的核心功能、请求参数、响应字段及使用示例，助你高效集成交易查询功能。
交易状态 API：实时监控交易进度
交易状态 API 专为开发者设计，用于获取用户实时法币入金交易列表。通过轮询该接口，开发者可以实时追踪交易状态，并在客户端应用中清晰展示用户的 Coinbase 法币入金交易记录。
核心功能与集成要点
为关联会话期间创建的所有交易，开发者必须在初始化法币入金流程时，通过查询参数提供可选的 partnerUserId 字段。若客户端应用无用户概念，可传递随机生成的 partnerUserId 以引用一次性会话。
该 API 返回按时间倒序排列的分页交易列表，确保最新交易优先显示。
请求方法与 URL 结构
请求方法：GET
基础 URL：
https://api.developer.coinbase.com/onramp/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size}请求参数详解
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
partner_user_id | 字符串 | 是 | 客户端应用中用于标识用户法币入金交易的唯一 ID。 |
page_key | 字符串 | 否 | 指向下一页交易的引用键，由上一页的响应返回。 |
page_size | 数字 | 否 | 每页返回的交易数量，默认值为 1。 |
响应字段解析
API 返回 JSON 格式响应，包含以下字段：
| 字段名 | 说明 |
|---|---|
transactions | 按时间倒序排列的 OnrampTransactions 列表。 |
next_page_key | 指向下一页交易的引用键。 |
total_count | 用户发出的交易总数。 |
法币入金交易数据结构
| 字段名 | 说明 | 可选值 |
|---|---|---|
status | 法币入金交易状态。 | ONRAMP_TRANSACTION_STATUS_IN_PROGRESS（处理中）, ONRAMP_TRANSACTION_STATUS_SUCCESS（成功）, ONRAMP_TRANSACTION_STATUS_FAILED（失败） |
purchase_currency | 购买的加密货币类型。 | 字符串 |
purchase_network | 用于向用户钱包交付加密货币的网络。 | 字符串 |
purchase_amount | 购买的加密货币数量。 | 字符串 |
payment_total | 用户需支付的法币总额。 | 字符串 |
payment_subtotal | 用户需支付的法币金额（不含费用）。 | 字符串 |
coinbase_fee | 收取的经纪费用。 | 字符串 |
network_fee | 收取的网络费用。 | 字符串 |
exchange_rate | 所购加密货币的单位价格。 | 字符串 |
country | 用户所在国家。 | 字符串 |
user_id | 用户的唯一标识符。 | 字符串 |
partner_user_ref | 对应 Onramp URL 中的 partnerUserId 参数（若提供）。 | 字符串 |
payment_method | 用户使用的支付方式。 | CARD（信用卡）, ACH_BANK_ACCOUNT（银行账户）, APPLE_PAY, FIAT_WALLET（法币钱包）, CRYPTO_WALLET（加密货币钱包） |
tx_hash | 链上发送的区块哈希。 | 字符串 |
transaction_id | 法币入金交易的唯一标识符。 | 字符串 |
wallet_address | 交易发送至的钱包地址。 | 字符串 |
type | 交易类型。 | ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND（购买并发送）, ONRAMP_TRANSACTION_TYPE_SEND（仅发送） |
请求示例
cdpcurl -k /tmp/cdp_api_key.json 'https://api.developer.coinbase.com/onramp/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size}'历史交易 API：批量获取交易记录
历史交易 API 提供指定日期范围内的 Coinbase 法币入金交易历史列表，适用于数据分析场景。该接口同样返回按时间倒序排列的分页结果，便于批量处理。
请求方法与 URL 结构
请求方法：GET
基础 URL：
https://api.developer.coinbase.com/onramp/v1/buy/transactions?page_key={next_page_key}&page_size={page_size}&start_date={start_date}&end_date={end_date}请求参数详解
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
page_key | 字符串 | 否 | 指向下一页交易的引用键，由上一页的响应返回。 |
page_size | 数字 | 否 | 每页返回的交易数量，默认值为 1000。 |
start_date | 字符串 | 否 | 返回交易范围的开始日期（包含），格式为 YYYY-MM-DD。默认值为 end_date 的前一个月。 |
end_date | 字符串 | 否 | 返回交易范围的结束日期（不包含），格式为 YYYY-MM-DD。默认值为明天。 |
响应字段解析
API 返回 JSON 格式响应，包含以下字段：
| 字段名 | 说明 |
|---|---|
transactions | 按时间倒序排列的 OnrampTransactions 列表。 |
next_page_key | 指向下一页交易的引用键。 |
历史交易 API 中的法币入金交易数据结构与交易状态 API 完全一致，确保数据格式的统一性。
请求示例
cdpcurl -k /tmp/cdp_api_key.json 'https://api.developer.coinbase.com/onramp/v1/buy/transactions?page_key={next_page_key}&page_size={page_size}&start_date={start_date}&end_date={end_date}'常见问题
1. 交易状态 API 和历史交易 API 有何区别？
交易状态 API 用于实时轮询特定用户的交易状态，适合集成到用户界面中提供即时反馈。而历史交易 API 则用于批量获取指定时间段内的所有交易记录，更侧重于数据分析和报表生成。
2. partner_user_id 参数是否必须提供？
在交易状态 API 中，partner_user_id 是必填参数，用于标识特定用户的交易。如果应用没有用户系统，可以使用随机生成的 ID 来关联一次性会话。
3. 如何处理分页？
两个 API 均支持分页。响应中的 next_page_key 字段提供了获取下一页数据的引用键，只需将其作为请求参数传入即可获取后续页面。
4. 交易状态有哪些可能的值？
交易状态主要包括三种：ONRAMP_TRANSACTION_STATUS_IN_PROGRESS（处理中）、ONRAMP_TRANSACTION_STATUS_SUCCESS（成功）和 ONRAMP_TRANSACTION_STATUS_FAILED（失败）。历史交易 API 通常只返回成功或失败的交易。
5. 如何指定查询的日期范围？
历史交易 API 通过 start_date 和 end_date 参数指定查询范围。日期格式必须为 YYYY-MM-DD，且 end_date 是不包含的，即查询范围是 [start_date, end_date)。
6. 这两个 API 的主要应用场景是什么？
交易状态 API 适用于需要实时展示交易进度的场景，如交易确认页面。历史交易 API 则适用于后台管理系统、对账系统和数据分析平台，用于生成交易报表和分析用户行为。
通过合理利用这两个 API，开发者可以构建功能完善、用户体验良好的加密货币交易应用，👉 获取进阶集成方法 进一步提升开发效率。