Withdrawals

Move crypto off a user's account — initiate a withdrawal, confirm it with a code, resend the code, cancel it, or read withdrawal history.

Move crypto off a user's account in two steps: initiate the withdrawal with a destination and amount, then confirm it with the code sent to the user. You can also resend the code, look up a single withdrawal, list them, or cancel one that hasn't gone through yet.

Authentication: every endpoint on this page accepts your Owner API Key (x-api-key) or a user token (Authorization: Bearer). A user token can only act on its own account.

x-api-key: YOUR_API_KEY

All requests accept an optional x-trace-id header for request tracking; if omitted, one is generated. The {{type}} path segment is always crypto.

Every response is wrapped in the standard { success, data, meta } envelope, and withdrawal statuses are uppercase (PENDING, COMPLETED, CANCELLED).

Initiate Withdrawal

POSThttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals

Start a crypto withdrawal for the user. Provide the currency, amount, and destination address; the response returns the withdrawal record you'll reference when confirming. The user is sent a code to authorize the transfer.

Request Body

Field	Type	Required	Description
currency	string	Yes	Currency to withdraw (e.g. `btc`).
amount	number	Yes	Amount of the currency to withdraw.
address	string	Yes	Destination wallet address.
memo	string	No	Memo or note for the withdrawal (max 255).

{
  "currency": "btc",
  "amount": 0.01,
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "memo": "Withdrawal to hardware wallet"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "withdraw": {
      "id": "9182",
      "status": "PENDING",
      "idempotency_key": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f",
      "is_duplicate": false
    },
    "currency": "btc",
    "amount": 0.01,
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
  },
  "meta": { "timestamp": "2026-01-15T10:30:00.000Z", "version": "v1", "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f" }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "currency": "btc",
    "amount": 0.01,
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "memo": "Withdrawal to hardware wallet"
  }'

Errors: 400 missing/invalid fields · 401 invalid key · 404 user not found · 500 server error.

Confirm Withdrawal

POSThttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals/:withdraw_id/confirm

Confirm a PENDING withdrawal with the code the user received. Pass the withdrawal id in the path and the code in the body. On success the withdrawal moves to COMPLETED and the transfer is released.

Request Body

Field	Type	Required	Description
code	string	Yes	One-time code sent to the user.

{
  "code": "123456"
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "id": "9182",
    "status": "COMPLETED"
  },
  "meta": { "timestamp": "2026-01-15T10:31:00.000Z", "version": "v1", "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f" }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}/confirm" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "code": "123456"
  }'

Errors: 400 invalid or expired code · 401 invalid key · 403 blocked after too many attempts · 404 withdrawal not found · 500 server error.

Resend Code

POSThttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals/:withdraw_id/verification/codes

Issue a fresh code to the user's email and reset the attempt counter. Send this with no body.

POST https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}/verification/codes

Success Response (200 OK):

{
  "success": true,
  "data": {
    "message": "Confirmation code resent to your email."
  },
  "meta": { "timestamp": "2026-01-15T10:35:00.000Z", "version": "v1", "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f" }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}/verification/codes" \
  -H "x-api-key: YOUR_API_KEY"

Errors: 400 withdrawal already completed/cancelled · 401 invalid key · 404 withdrawal not found · 500 server error.

Cancel Withdrawal

DELETEhttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals/:withdraw_id

Cancel a withdrawal that hasn't completed. Only pending withdrawals can be cancelled; once the transfer is released it can't be reversed here.

DELETE https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}" \
  -H "x-api-key: YOUR_API_KEY"

Errors: 400 withdrawal can't be cancelled in its current state · 401 invalid key · 404 withdrawal not found · 500 server error.

Get Withdrawal

GEThttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals/:withdraw_id

Return the details of a single withdrawal by its id.

Response Fields

Field	Type	Description
id	string	Withdrawal id (atx_id).
withdrawal_type	string	Type (`crypto`).
currency	string	Currency.
amount	number	Amount.
address	string	Destination address.
status	string	`PENDING` / `COMPLETED` / `CANCELLED`.
created_at	string (ISO 8601)	Creation timestamp.

GET https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "id": "9182",
    "withdrawal_type": "crypto",
    "currency": "btc",
    "amount": 0.01,
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "status": "PENDING",
    "created_at": "2026-01-15T10:30:00.000Z"
  },
  "meta": { "timestamp": "2026-01-15T10:30:00.000Z", "version": "v1", "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f" }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals/{{withdrawID}}" \
  -H "x-api-key: YOUR_API_KEY"

Errors: 401 invalid key · 404 withdrawal not found · 500 server error.

List Withdrawals

GEThttps://api.sandbox.sovera.io/sovx/v1/users/:user_id/accounts/crypto/withdrawals

List the user's withdrawals, most recent first. Pagination lives under meta.pagination; each item matches the Get Withdrawal shape.

Query Parameters

Parameter	Type	Required	Description
filter[limit]	number	No	Items per page (default: 20, max: 100).
filter[skip]	number	No	Offset.
filter[sort]	string	No	Sort by date: `ASC` or `DESC` (default `DESC`).
filter[where][status]	string	No	Normalized status: `PENDING` or `COMPLETED`.
filter[where][currency]	string	No	Currency code (case-insensitive match).

GET https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals?filter[limit]=20&filter[skip]=0

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "9182",
      "withdrawal_type": "crypto",
      "currency": "btc",
      "amount": 0.01,
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "status": "PENDING",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f",
    "pagination": {
      "records": { "skip": 0, "has_next": false, "has_previous": false, "total": 1, "limit": 20 },
      "navigation": {
        "first": "/users/{{userID}}/accounts/crypto/withdrawals?filter[limit]=20&filter[skip]=0",
        "last": "/users/{{userID}}/accounts/crypto/withdrawals?filter[limit]=20&filter[skip]=0",
        "previous": null,
        "next": null
      }
    }
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/crypto/withdrawals?filter[limit]=20&filter[skip]=0" \
  -H "x-api-key: YOUR_API_KEY"

Errors: 401 invalid key · 404 user not found · 500 server error.

Withdrawals

On this page