Wallet and Options transfers
Move USD between a customer’s Deriv Wallet and Options account.
Wallet–Options transfers are available to every approved workspace. Use a key with transfers:write to create, retry or dismiss a transfer, and transactions:read to read transfers.
Ask for the customer's consent before moving funds. Their Deriv authorization must include payment and trade access. Transfers use their linked real USD Wallet and eligible USD Options account. You cannot specify another customer's account as the destination.
The following paths start with /api/deriv/connections/{connection_id}:
| Method | Path | Purpose |
|---|---|---|
| POST | /transfers | Create or retry a transfer. |
| GET | /transfers | List up to 20 recent transfers. Filter by unresolved or deposit_transaction_id. |
| GET | /transfers/{request_id} | Read a transfer and check for an updated outcome. |
| POST | /transfers/{request_id}/dismiss | Close an unconfirmed transfer after the customer checks their balances and confirms closure. |
Generate and save a UUID as request_id before the first request. Send direction: "to_options" or "to_wallet", and a positive USD amount with at most nine whole digits and two decimal places. A decimal string such as "12.50" avoids rounding; exponent notation is rejected.
For to_options, you can include deposit_transaction_id to link the transfer to a completed deposit belonging to the same customer and integration. This prevents transferring that deposit twice.
Check the transfer's status:
| Status | Meaning |
|---|---|
submitting | The request is being submitted. Keep checking. |
completed | The funds moved. |
rejected | The transfer was refused. |
not_submitted | The transfer was not submitted. |
outcome_unknown | The result is unconfirmed. Keep checking. |
dismissed | The customer closed the unresolved transfer. Its financial outcome remains unconfirmed. |
After a 409, 502 or timeout, reuse the original UUID and request body. Money may already have moved. An unresolved transfer blocks new transfers on the same connection.
To dismiss an unresolved transfer, ask the customer to check both balances and confirm closure, then send {"customer_confirmed":true} to the dismissal endpoint. Dismissal allows another transfer; it does not reverse funds, issue a refund or establish that the original transfer failed.
Creation and retries are limited to 20 requests per workspace per ten minutes. On 429, follow Retry-After. If execution returns 503 SERVICE_UNAVAILABLE, keep checking the existing transfer. Reads and customer-confirmed dismissal remain available when execution is temporarily disabled, subject to authentication and service availability.
Transfer records have their own IDs and statuses. Read them through the transfer endpoints; payment SSE does not include them.