Wallet REST

List the authenticated client's wallets, browse the transactions for each one, and move funds between wallets and trading platform accounts. The exchange-rate and transfer endpoints are in beta and may change without notice.

Overview

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

Typical Workflow

1. 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.
2. 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.
3. For a transfer between different currencies, quote the rate first with GET /wallet/v1/exchange-rate. Send the exchange_rate and rate_token it returns when you execute.
4. Preview the transfer with POST /wallet/v1/transfers/validate. It moves no money, and returns the fee, the net amount leaving the source account, and the estimated amount the destination receives.
5. Execute it with POST /wallet/v1/transfers between wallets in the same currency, POST /wallet/v1/transfers/exchange between wallets in different currencies, or POST /wallet/v1/transfers/platforms between a wallet and a trading platform account. Each takes a request_id as its idempotency key.

Available Endpoints

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

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:

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, ValidationError, CurrencyNotAllowed, DailyLimitError, DuplicateRequestID, Unauthorized, NotFound, InternalServerError