API reference

Connections

Create, read and list customer connections, and read a connected Deriv balance.

A connection links one of your customers' Deriv accounts to Deripay through your Deriv app, using either a Deriv OAuth access token or the customer's personal access token. Every deposit and withdrawal names a connection. Store the connection id on your backend against your own customer record. Treat it as sensitive: do not put it in URLs, browser storage or analytics.

The connection object

json

{
  "id": "con_6720f1a2b3c4d5e6f7a8",
  "object": "connection",
  "client_id": "YOUR_DERIV_CLIENT_ID",
  "external_customer_id": "user_1842",
  "deriv_login_id": "CR1234567",
  "accounts": [
    { "login_id": "CR1234567", "currency": "USD", "is_virtual": false }
  ],
  "authorization_status": "active",
  "default_phone_number": "254712345678",
  "created_at": "2026-11-03T09:00:00.000Z",
  "last_authorized_at": "2026-11-03T09:00:00.000Z"
}

Field	Type	Description
`id`	string	Connection id, `con_…`.
`object`	string	Always `connection`.
`client_id`	string	The Deriv OAuth client ID the customer connected through.
`external_customer_id`	string or null	Your id for the customer, as you sent it.
`deriv_login_id`	string or null	The selected Deriv login id, or the primary one.
`accounts`	array	Deriv accounts returned at connect time, each with `login_id`, `currency` and `is_virtual`. At most 20.
`authorization_status`	string	`active`, or `reconnect_required` once Deriv has rejected the token.
`default_phone_number`	string or null	Saved default mobile number, if any.
`created_at`	string	When the connection was first created.
`last_authorized_at`	string or null	When `POST /connections` last succeeded for it.

Create or update a connection

http

POST /api/v2/connections

Scope: connections. Rate limit: 30 per minute.

bash

curl https://deriapi.site/api/v2/connections \
  -H "Authorization: Bearer $DERIPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_DERIV_CLIENT_ID",
    "deriv_access_token": "DERIV_ACCESS_TOKEN",
    "token_expires_in": 3600,
    "external_customer_id": "user_1842",
    "preferred_account_id": "CR1234567"
  }'

Field	Required	Type	Description
`client_id`	yes	string, 6-64	Your Deriv OAuth client ID, registered under Deriv apps.
`deriv_access_token`	yes	string, 10-4000	Deriv OAuth access token or personal access token, with scopes `trade account_manage payment`.
`token_expires_in`	no	positive integer	`expires_in` from Deriv's token response.
`external_customer_id`	no	string, 1-128	Your own id for the customer.
`preferred_account_id`	no	string, 2-32	Deriv login id to use by default. Must be a real USD account.

Returns 201 with the connection object.

Upsert. Calling it again for the same Deriv account through the same client ID updates the existing connection and returns the same con_… id. Use this to reconnect after DERIV_RECONNECT_REQUIRED or to change the preferred account. A different client ID can produce a separate connection. Always store the id from the latest successful response.

Errors you may see: DERIV_APP_NOT_REGISTERED, DERIV_AUTH_FAILED, DERIV_ACCOUNT_MISMATCH, DERIV_ACCOUNT_NOT_ELIGIBLE. See Errors.

Get a connection

http

GET /api/v2/connections/{id}

Scope: read.

Returns the stored connection. Add ?refresh=true to re-read it from Deripay's payment network first, which updates accounts, deriv_login_id, authorization_status and default_phone_number.

bash

curl "https://deriapi.site/api/v2/connections/con_6720f1a2b3c4d5e6f7a8?refresh=true" \
  -H "Authorization: Bearer $DERIPAY_API_KEY"

An id that does not exist or belongs to another Deripay account returns 404 CONNECTION_NOT_FOUND.

List connections

http

GET /api/v2/connections

Scope: read.

Query	Description
`external_customer_id`	Only connections with this exact `external_customer_id`.
`limit`	1 to 100. Default 25.
`cursor`	A `con_…` id. Returns the page after it. Use `next_cursor` from the previous page.

Results are newest first.

bash

curl "https://deriapi.site/api/v2/connections?external_customer_id=user_1842" \
  -H "Authorization: Bearer $DERIPAY_API_KEY"

json

{
  "success": true,
  "data": {
    "items": [{ "id": "con_6720f1a2b3c4d5e6f7a8", "object": "connection", "...": "..." }],
    "total": 1,
    "next_cursor": null
  }
}

total is the number of matching connections. next_cursor is null when there are no more pages.

Get the Deriv balance

http

GET /api/v2/connections/{id}/balance

Scope: read.

json

{
  "success": true,
  "data": {
    "connection_id": "con_6720f1a2b3c4d5e6f7a8",
    "login_id": "CR1234567",
    "balance": 25.5,
    "currency": "USD"
  }
}

balance is the spendable USD balance in the customer's main Deriv wallet. Withdrawals are paid from that wallet, so check it before you offer a withdrawal amount. A token without the payment scope fails with DERIV_AUTH_FAILED; ask the customer to reconnect.

Set the default phone number

http

PATCH /api/v2/connections/{id}/default-phone

Scope: connections.

bash

curl -X PATCH https://deriapi.site/api/v2/connections/con_6720f1a2b3c4d5e6f7a8/default-phone \
  -H "Authorization: Bearer $DERIPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "0712345678" }'

Field	Required	Description
`phone_number`	yes	Mobile number, 6-20 characters, local (`0712…`) or international (`254712…`) form.

Returns the updated connection. The number is stored in international form, for example 254712345678. This is a Kenyan number store: for Tanzania and Uganda, send phone_number on each deposit and withdrawal instead. An invalid number returns 400 INVALID_PHONE_NUMBER.

The saved number is for your convenience, for example to prefill a form. Deposits and withdrawals still need phone_number in the request.

← Go-live checklist Markets and rates →