Statistics and CSV exports

Request GET /api/deriv/statistics for JSON or GET /api/deriv/statistics/export for CSV. Both require transactions:read and include only your integration's activity. Your key identifies the integration, so omit partner_id.

Filters are optional. The default period is the last 30 calendar days, including today, in Africa/Nairobi. Set an IANA timezone when you need a different reporting timezone. Unknown filters and repeated query parameters are rejected.

The response includes totals, time intervals, breakdowns, recent transactions and a comparison with the preceding period of the same length. Amounts are decimal strings. A missing percentage means the calculation has no denominator; a missing completion duration means usable timing data is unavailable.

For reporting, payments that need customer action or reconciliation count as pending. The partner portal's analytics also break failed transactions down by cause; see failed transactions and reporting issues. successful means payment completed. Past reports can change when pending transactions are resolved.

Earnings estimate the exchange-rate spread on completed transactions. Read the returned calculation basis, shares and exclusions before using these figures. They are estimates and cannot be treated as a payout balance. Partial reporting periods are marked, and comparisons are not adjusted for an incomplete current period.

CSV accepts the same filters as JSON. When adding amounts, group by both currency and amount_basis. Keep collection or payout amounts separate from USD Wallet amounts. Total attempt and customer counts appear once, on USD rows. The reference includes the CSV header and sample rows.

Sync earnings

To keep earnings in your own database, read the earnings ledger instead of requesting statistics once per customer_reference and period. GET /api/deriv/statistics/earnings returns one row per completed transaction, in completion order, up to 500 rows per page. Each row carries its reference, connection_id, customer_reference, completed_at and the gross, partner and Deripay earnings.

1. Start the first sync with completed_since, for example completed_since=2026-01-01. This has no 366-day limit.
2. Upsert each row by reference, then save next_cursor.
3. While has_more is true, request the next page with only cursor=<next_cursor>.
4. On your next scheduled run, continue with the saved cursor. You receive only completions that are new since the last read.

A cursor keeps the customer_reference filter it started with, so send it on its own. The ledger runs about two minutes behind real time, so completions that are still being recorded are not skipped; complete_through shows its current position. earnings_included is false when a transaction lacks the rate or amounts needed for an estimate, and its earnings are then 0.00. customer_reference is the connection's current reference.

If a cursor is rejected or lost, restart with completed_since set to the latest completed_at you stored. Rows you already have are returned again; upserting by reference keeps them once.

For a summary, GET /api/deriv/statistics/earnings/customers returns one row per customer_reference for a completion period, using the same from, to and timezone rules as statistics. Add granularity=day, week or month to split each customer into calendar periods; period is the period's start date. totals covers every page. Transactions without a customer reference are grouped under null. Request later pages with only cursor.

Ledger rows and customer rows add up to the earnings in /api/deriv/statistics for the same completion period. The ledger does not resend a row that is corrected after you read it, so reconcile your stored totals with the customer report, for example once a day for the previous day.

Reports and portal exports share a limit of 60 requests per minute per workspace. Follow Retry-After when you reach it.