Create a report

posthttps://api.exchange.coinbase.com/reports

Generates a report. You can create reports with historical data for all report types. Balance reports can be snapshots of historical or current data.

Reports provide batches of historic information about your profile in various human and machine readable forms.

info

A report is generated when resources are available. You can poll the report resource endpoint at /reports/{report_id} for its status. When status is ready, the final report is uploaded and available at {file_url}.

API Key Permissions

This endpoint requires either the "view" or "trade" permission.

Expired reports

Reports are only available for download for a few days after being created. Once a report expires, the report is no longer available for download and is deleted.

Balance Reports

Balance statements represent historical or current point-in-time “snapshots” in native and fiat converted units. Balance statement reports:

• Can be generated for a specific portfolio (API and UI) or all portfolios (UI only). In the UI, all portfolios can be grouped by portfolio or asset (with balances totaled across portfolios).

• Include balances for crypto and fiat assets supported on the Exchange (USD, EUR, GBP).

• Include balances in both native units (e.g., 1 BTC) as well as fiat-converted units assets (e.g., $20000 USD worth of BTC) where price data is available.

• Are generated for all assets (crypto and fiat) in the user’s account as of the requested timestamp. They cannot be generated for a specific asset (as is possible with the account and fill reports).

caution

API calls are tied to a specific portfolio but you can group by all portfolios in the UI.

Timestamps

• Range: Timestamps are UTC-exclusive. For example, to generate a balance as of December 31st, 2022 EOD UTC (11:59:59 PM UTC), input January 1st, 2023 12:00:00 AM UTC.

• Granularity: The API is the most granular and lets you specify a timestamp to the very second. The UI lets you specify the day and hour.

Fiat Conversion

• For fiat balances (USD, EUR, GBP), the conversion price is 1:1 and is reported in that specific fiat currency. EUR/GBP is not converted to USD balance.

• For crypto balances the conversion price is the volume weighted average of closing prices in USD (when available). It is calculated by fetching 1 hour candles between [t-24 hours to t] and taking a volume weighted average of the closing price of the candles (when available).

  • Requested timestamp = t; Start range = t - 24 hours; End range = t
  • Candles may not be available; e.g., delisted assets may not have candles at the requested timestamp.
  • If a USD pair is not listed for trading at the requested timestamp, fiat conversion is not possible.

Request Details

The Balance Report API:

• Leverages the existing /reports endpoint.
• Adds a new report type of balance.
• Adds a balance object to the request with datetime (and group_by_potfolio_id for the UI only).
• Keeps the same response schema (with the possibility that "type"="balance").

Example of Balance Report API Request

// Create balance statement for the portfolio tied to the API key
{
    "balance": {
        "datetime": "2022-02-25T05:00:00.000Z",
    },
    "email": "user1@example.com",
    "format": "csv",
    "type": "balance"
}

Body params

typestring

Type of report to generate. Possible values: [account, balance, fills, otc-fills, rfq-fills, tax-invoice, 1099k-transaction-history]

yearstring

required for 1099k-transaction-history-type reports

formatstring

Possible values: [pdf, csv]

pdf

​

emailstring

Email to send generated report notification to

profile_idstring

If this field is specified, it must be the profile_id that is linked to the API key.

balanceobject

datetimestring

Designated date and time of the balance statement. Timezone is always UTC. If this field is empty, a report of the user’s current balance will be generated.

group_by_profileboolean

Not applicable if generating report through an API key; only available through report generation via the Exchange user interface (UI).

​

​

fillsobject

start_datestring

Start date for items to be included in report.

end_datestring

End date for items to be included in report

product_idstring

Product - Which product to generate the report for

accountobject

start_datestring

Start date for items to be included in report.

end_datestring

End date for items to be included in report

account_idstring

Account - Which account to generate the report for

otc-fillsobject

start_datestring

Start date for items to be included in report.

end_datestring

End date for items to be included in report

product_idstring

Product - Which product to generate the report for

tax-invoiceobject

start_datestring

Start date for items to be included in report.

end_datestring

End date for items to be included in report

product_idstring

Product - Which product to generate the report for

rfq-fillsobject

start_datestring

Start date for items to be included in report.

end_datestring

End date for items to be included in report

product_idstring

Product - Which product to generate the report for

Responses