Onramp Reporting and Analytics

Transaction Status

The Transaction Status API provides developers with a list of user Onramp transactions. Developers can poll the real time status of transactions and show users a view of their Coinbase Onramp transactions made within the client app.

To link all transactions created during the session, developers must provide the (optional) field partnerUserId as a query parameter when initializing Coinbase Onramp.

Transaction Status returns a paginated list of all transactions from newest to oldest. If the client app doesn’t have a concept of a user, clients can pass a random partnerUserId to reference a one-off session.

Method

GET

URL

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

Request Parameters

The Transaction Status API is an RPC endpoint that accepts an argument as part of its URL path.

Name	Type	Req	Description
partner_user_id	String	Y	ID referring to user Onramp transactions in client app.
page_key	String	N	Reference to next page of transactions. Returned in previous page’s response.
page_size	Number	N	Number of transactions to return per page. Default is 1.

Response Fields

The Transaction Status API returns a JSON response including the following fields.

Name	Description
transactions	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.

OnrampTransaction Schema

Name	Description	Value
status	Current status of the Onramp transaction.	ONRAMP_TRANSACTION_STATUS_CREATED ONRAMP_TRANSACTION_STATUS_IN_PROGRESS ONRAMP_TRANSACTION_STATUS_SUCCESS ONRAMP_TRANSACTION_STATUS_FAILED
purchase_currency	Crypto currency being purchased.	String
purchase_network	Network used to deliver crypto to the user’s wallet.	String
purchase_amount	Amount of crypto currency being purchased.	String
payment_total	Total amount of fiat the user will pay.	String
payment_subtotal	Amount of fiat the user will pay, exclusive of fees	String
coinbase_fee	Amount of fiat charged to cover brokerage fees.	String
network_fee	Amount of fiat charged to cover network fees.	String
exchange_rate	Unit price of the crypto currency being purchased.	String
country	Country the user resides in.	String
user_id	Unique identifier representing the user.	String
payment_method	Type of payment method the user is paying with.	CARD ACH_BANK_ACCOUNT APPLE_PAY FIAT_WALLET CRYPTO_WALLET
tx_hash	The block hash of the onchain send.	String

Example Request/Response

Request (cURL)

curl -H "Authorization: Bearer $JWT" 'https://api.developer.coinbase.com/onramp/v1/buy/user/{partner_user_id}/transactions?page_key={next_page_key}&page_size={page_size}'

Response 200 (JSON)

{
    "transactions": [
        {
            "status":"ONRAMP_TRANSACTION_STATUS_SUCCESS",
            "purchase_currency": "USDC",
            "purchase_network": "base",
            "purchase_amount": {
                "value": "5",
                "currency": "USDC"
            },
            "payment_total": {
                "value": "5.07",
                "currency": "USD"
            },
            "payment_subtotal": {
                "value": "5",
                "currency": "USD"
            },
            "coinbase_fee": {
                "value": "0",
                "currency": "USD"
            },
            "network_fee": {
                "value": "0.07",
                "currency": "USD"
            },
            "exchange_rate": {
                "value": "1",
                "currency": "USDC"
            },
            "tx_hash": "0x31814ba2fef2a400a9816767370be09ca12d9e9753b972198fe330a0ecedcbf6",
            "created_at": "2023-09-26T20:06:07.076Z",
            "country": "US",
            "user_id": "9f86d081884c7d659a2feaa0c55ad01",
            "payment_method": "CARD",
            "transaction_id": "1ee7a7ec-fdd1-6032-ad91-0e2bacb520d3"
    }
],
"next_page_key":"eyJndF9za2lwIjowLCJvdF9za2lwIjoxfQ==",
"total_count":"3"
}

Transactions

The Transactions API provides clients with a list of Coinbase Onramp transactions between two dates. Transactions returns a paginated list of all transactions from newest to oldest. The Transactions API is indented for analytics purposes.

If you need real time information about a specific transaction, use the Transaction Status API.

Method

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}

Request Parameters

Name	Type	Req	Description
page_key	String	N	Reference to next page of transactions. Returned in previous page’s response.
page_size	Number	N	Number of transactions to return per page. Default is 1000.
start_date	String	N	The start date (inclusive) of the range of transactions to return. YYYY-MM-DD format. Default is one month before end_date.
end_date	String	N	The end date (exclusive) of the range of transactions to return. YYYY-MM-DD format. Default is tomorrow.

Response Fields

The Transaction Status API returns a JSON response including the following fields.

Name	Description
transactions	List of OnrampTransactions in reverse chronological order.
next_page_key	A reference to the next page of transactions.

OnrampTransaction Schema

Name	Description	Value
status	Current status of the CBPay transaction.	ONRAMP_TRANSACTION_STATUS_CREATED ONRAMP_TRANSACTION_STATUS_IN_PROGRESS ONRAMP_TRANSACTION_STATUS_SUCCESS ONRAMP_TRANSACTION_STATUS_FAILED
purchase_currency	Crypto currency being purchased.	String
purchase_network	Network used to deliver crypto to the user’s wallet.	String
purchase_amount	Amount of crypto currency being purchased.	String
payment_total	Total amount of fiat the user will pay.	String
payment_subtotal	Amount of fiat the user will pay, exclusive of fees	String
coinbase_fee	Amount of fiat charged to cover brokerage fees.	String
network_fee	Amount of fiat charged to cover network fees.	String
exchange_rate	Unit price of the crypto currency being purchased.	String
country	Country the user resides in.	String
user_id	Unique identifier representing the user.	String
payment_method	Type of payment method the user is paying with.	CARD ACH_BANK_ACCOUNT APPLE_PAY FIAT_WALLET CRYPTO_WALLET
tx_hash	The block hash of the onchain send.	String
wallet_address	The address of the wallet the transaction was sent to.	String

Example Request/Response

Request (cURL)

curl -H "Authorization: Bearer $JWT" 'https://api.developer.coinbase.com/onramp/v1/buy/user/transactions?page_key={next_page_key}&page_size={page_size}&start_date={start_date}&end_date={end_date}'

Response 200 (JSON)

{
    "transactions": [
        {
            "status":"ONRAMP_TRANSACTION_STATUS_SUCCESS",
            "purchase_currency": "USDC",
            "purchase_network": "base",
            "purchase_amount": {
                "value": "5",
                "currency": "USDC"
            },
            "payment_total": {
                "value": "5.07",
                "currency": "USD"
            },
            "payment_subtotal": {
                "value": "5",
                "currency": "USD"
            },
            "coinbase_fee": {
                "value": "0",
                "currency": "USD"
            },
            "network_fee": {
                "value": "0.07",
                "currency": "USD"
            },
            "exchange_rate": {
                "value": "1",
                "currency": "USDC"
            },
            "tx_hash": "0x31814ba2fef2a400a9816767370be09ca12d9e9753b972198fe330a0ecedcbf6",
            "created_at": "2023-09-26T20:06:07.076Z",
            "country": "US",
            "user_id": "9f86d081884c7d659a2feaa0c55ad01",
            "payment_method": "CARD",
            "transaction_id": "1ee7a7ec-fdd1-6032-ad91-0e2bacb520d3",
            "wallet_address": "0x3d7b51da8AA41270C6e052eE261db4514Ba4D50A"
    }
],
"next_page_key":"eyJndF9za2lwIjowLCJvdF9za2lwIjoxfQ==",
}