Wallet REST

List the authenticated client's wallets and browse the transactions for each one.

Overview

The Wallet APIs let an application read the authenticated client's wallets and their transaction history. List every wallet with its balances via the wallets endpoint, then page through the movements for a single wallet via the transactions endpoint. All endpoints are standard REST calls and require the payment OAuth2 scope.

REST API

These are standard REST APIs using HTTP methods (GET). All requests require the Deriv-App-ID: YOUR_APP_ID header and an Authorization: Bearer YOUR_OAUTH_TOKEN token carrying the payment scope.

OpenAPI Specification

View the complete OpenAPI specification for detailed schema definitions and examples:

OpenAPI Spec →

Typical Workflow

List the client's wallets with GET /wallet/v1/wallets. Each entry carries its balances in the wallet's native currency; supply conversion_currency to also receive a converted total.
Fetch the movements for one wallet with GET /wallet/v1/transactions/{wallet_type}. Results are cursor-paginated; follow links.next and links.prev to page through them.

Available Endpoints

List WalletsGet

Returns the wallets belonging to the authenticated client, with each balance shown in the wallet's native currency. Supply a conversion_currency to also receive each balance converted into that currency, and use start_date_time and end_date_time to bound the balance as of window./wallet/v1/wallets

Wallet TransactionsGet

Returns a cursor-paginated list of transactions for one of the authenticated client's wallets, identified by wallet_type. Filter by request_id, transaction_currency, and a date range. Each row carries a channel showing how the money moved and a category computed relative to the caller./wallet/v1/transactions/{wallet_type}

Authentication

All endpoints require the Deriv-App-ID header and an Authorization: Bearer YOUR_OAUTH_TOKEN header. The token must carry the payment scope; otherwise the API returns 403 Forbidden.

OAuth2 Scopes

Endpoint	Scope
`GET /wallet/v1/wallets`	`payment`
`GET /wallet/v1/transactions/{wallet_type}`	`payment`

1curl -X GET "https://api.derivws.com/wallet/v1/wallets?conversion_currency=USD" \
2  -H "Deriv-App-ID: YOUR_APP_ID" \
3  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Response Status Codes

The API uses standard HTTP status codes to indicate success or failure:

2xx Success

200 OK — Request successful

4xx/5xx Errors

400 Bad Request — Invalid parameters

401 Unauthorized — Invalid or missing authentication

403 Forbidden — Token lacks the payment scope

404 Not Found — Wallet not found

500 Internal Server Error — Server-side error

503 Service Unavailable — Request rejected by the gateway circuit breaker

504 Gateway Timeout — Upstream service timeout

Error Response Format

All error responses follow a consistent envelope with an errors array. Each entry carries a numeric status, a machine-readable code, and a human-readable message:

1{
2  "errors": [
3    {
4      "status": 400,
5      "code": "BadRequest",
6      "message": "conversion_currency must be a 3-letter ISO currency code"
7    }
8  ]
9}

Error codes include: BadRequest, Unauthorized, NotFound, InternalServerError

Withdrawal Status List Wallets

Any other questions? Get in touch