How to Use the Coinbase Onramp Transaction Status and History APIs

For developers integrating cryptocurrency onramp solutions, understanding transaction statuses and accessing historical data are critical tasks. The Coinbase Onramp APIs provide robust tools for retrieving real-time status updates and historical transaction records programmatically. This guide explains the key features, request parameters, and response structures for these two essential APIs.

Understanding the Transaction Status API

The Transaction Status API delivers a real-time list of a user's onramp transactions. Developers can poll this API to get the latest status of transactions, enabling them to display an up-to-date view of all Coinbase Onramp transactions made within their client application.

To link all transactions created during a specific session, developers should provide the optional partnerUserId field as a query parameter when initializing the Coinbase Onramp. This API returns a paginated list of transactions, ordered from newest to oldest. For applications without a user concept, a random partnerUserId can be used to reference a one-off session.

API Endpoint and Method

The Transaction Status API uses a GET request to the following URL structure:

https://api.developer.coinbase.com/onramp/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size}

Key Request Parameters

Response Structure

The API returns a JSON response containing these main fields:

• transactions: A list of OnrampTransactions in reverse chronological order.
• next_page_key: A reference to the next page of transactions.
• total_count: The total number of transactions made by the user.

Onramp Transaction Schema Explained

Each transaction object includes detailed information:

• status: Current status of the transaction (IN_PROGRESS, SUCCESS, or FAILED).
• Financial details: purchase_currency, purchase_amount, payment_total, payment_subtotal.
• Fee breakdown: coinbase_fee and network_fee.
• exchange_rate: The unit price of the purchased cryptocurrency.
• User information: country, user_id.
• Payment method: How the user paid (CARD, ACH_BANK_ACCOUNT, etc.).
• Blockchain data: tx_hash (transaction hash) and wallet_address.
• Identifiers: transaction_id and partner_user_ref.

👉 View real-time transaction tools

Accessing Historical Data with the Transactions API

While the Status API provides real-time information, the Transactions API offers a historical view of Coinbase Onramp transactions between two specified dates. This API is particularly valuable for analytics and reporting purposes, providing a paginated list of all transactions from newest to oldest.

Historical API Endpoint

The Transactions API uses a GET request to this 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}

Request Parameters for Historical Data

Understanding the Historical Response

The response includes:

• transactions: List of historical OnrampTransactions in reverse chronological order.
• next_page_key: Reference to the next page of historical transactions.

The transaction schema for historical data is similar to the status API but focuses on completed transactions (either SUCCESS or FAILED status).

Practical Implementation Guide

Implementing these APIs requires careful attention to parameter handling and response parsing. Here's a step-by-step approach:

1. Initialize with partnerUserId: When directing users to the onramp, include the partnerUserId parameter to maintain session continuity.
2. Polling for real-time status: Use the Status API to regularly check transaction progress, especially for time-sensitive applications.
3. Handling pagination: Both APIs use pagination. Always check for next_page_key in responses to retrieve complete data sets.
4. Date range management: For historical data, ensure proper date formatting (YYYY-MM-DD) and logical range selection.
5. Error handling: Implement robust error handling for API failures, invalid parameters, and unexpected response formats.

👉 Explore more API strategies

Frequently Asked Questions

What's the difference between the Status API and Transactions API?
The Status API provides real-time information about current user transactions, ideal for displaying immediate progress updates. The Transactions API offers historical data between specific dates, better suited for reporting and analytics purposes.

How should I handle pagination in these APIs?
Both APIs return a next_page_key when more results are available. Your application should check for this field and make subsequent requests with the provided key until no more pages remain.

What happens if I don't provide a partnerUserId?
Without a partnerUserId, you cannot link transactions to specific users or sessions. For applications without user accounts, generate a random ID to maintain transaction reference capability.

Can I retrieve failed transactions through these APIs?
Yes, both APIs return transactions regardless of status. You can filter responses based on the status field to identify successful, failed, or in-progress transactions.

What timezone do the date parameters use?
The date parameters (start_date and end_date) use UTC timezone. Ensure your date calculations account for this when querying historical transaction data.

How frequently should I poll the Status API?
Polling frequency depends on your application needs. For most use cases, checking every 30-60 seconds provides reasonable updates without excessive API calls.