User Account

Read a user's balance across all wallets and the ledger of every movement recorded for them.

Read one user's money: the balance per currency across all their wallets, and the ledger of every movement recorded for them (deposits, withdrawals, trades, and transfers).

Authentication: both endpoints accept your Owner API Key (x-api-key) or a user token (Authorization: Bearer). A user token only reads its own user; another user_id answers 403 FORBIDDEN. A user outside your customer answers 404 USER_NOT_FOUND.

x-api-key: YOUR_OWNER_API_KEY

See API conventions for the envelope, errors, pagination and filters, money, statuses, and trading pairs.

Get User Balance

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

Read the user's balance per currency, summed across their wallets. Every amount is a decimal string at the asset's scale; held is total minus available, never negative.

Path Parameters

Parameter	Type	Required	Description
user_id	string (UUID)	Yes	User to read.

Response Fields

Field	Type	Description
object	string	Always `account_balance`.
user_id	string (UUID)	User id.
balances[]	array	One row per currency.
balances[].currency	string	Uppercase currency code.
balances[].total	string	Total balance.
balances[].available	string	Available to spend.
balances[].held	string	Reserved by pending movements.
as_of	string	UTC time the balance was read.

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

Success Response (200 OK):

{
  "success": true,
  "data": {
    "object": "account_balance",
    "user_id": "3afd8834-33a7-52b0-aa47-8138c9af062a",
    "balances": [
      { "currency": "BTC", "total": "0.50000000", "available": "0.45000000", "held": "0.05000000" },
      { "currency": "USDT", "total": "1250.000000", "available": "1250.000000", "held": "0.000000" }
    ],
    "as_of": "2026-10-12T14:03:11Z"
  },
  "meta": { "timestamp": "2026-10-12T14:03:11Z", "version": "v1", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }
}

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

Errors: 401 UNAUTHORIZED · 403 FORBIDDEN a user token for another user · 404 USER_NOT_FOUND · 429 RATE_LIMIT_EXCEEDED.

List User Transactions

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

List the movements recorded for the user, newest first. Each item is a transaction object. A user with no movements returns data: [].

Query Parameters

Parameter	Type	Required	Description
filter[limit]	integer	No	Page size. Default 25, max 100.
cursor	string	No	Opaque cursor from `meta.pagination.navigation`.
filter[order]	string	No	`created_at` or `updated_at`, `ASC` or `DESC`. Default `created_at DESC`.
filter[where][status][eq\|inq]	string	No	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`, `EXPIRED`, `BLOCKED`.
filter[where][currency][eq\|inq]	string	No	Currency code, case-insensitive exact match.
filter[where][tx_hash][eq]	string	No	On-chain transaction hash.
filter[where][idempotency_key][eq]	string	No	`x-idempotency-key` of the request that created the movement.
filter[where][created_at][gte\|lte\|between]	string	No	UTC date-time ending in `Z`.

GET https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/transactions?filter[where][created_at][gte]=2026-10-01T00:00:00Z&filter[limit]=25

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "a243e6ea-553a-5b40-bc5d-780249591cdd",
      "object": "transaction",
      "type": "SELL",
      "status": "COMPLETED",
      "status_reason": null,
      "customer_id": "corp-redundant-firewall",
      "user_id": "3afd8834-33a7-52b0-aa47-8138c9af062a",
      "wallet_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "currency": "USD",
      "amount": "1004.9504",
      "fee": "10.0495",
      "net_amount": "994.9009",
      "price": "1.0072",
      "pair": "USDT/USD",
      "base_currency": "USDT",
      "quote_currency": "USD",
      "balance_after": "49071.0687",
      "references": {
        "order_id": "7690141a-e24f-5d91-a3cc-364f32c11258",
        "withdrawal_id": null,
        "transfer_id": null,
        "deposit_id": null
      },
      "address": null,
      "network": null,
      "memo": null,
      "tx_hash": null,
      "idempotency_key": "9a7c3e1f-5b2d-4c8e-a6f0-1d3b5e7f9a2c",
      "description": null,
      "created_at": "2026-10-05T20:24:01Z",
      "updated_at": "2026-10-05T20:24:03Z",
      "completed_at": "2026-10-05T20:24:03Z",
      "created_by": "d5263d12-b5e8-5fc7-ba07-816c0c78a61a",
      "updated_by": "d5263d12-b5e8-5fc7-ba07-816c0c78a61a"
    }
  ],
  "meta": {
    "timestamp": "2026-10-12T14:03:11Z",
    "version": "v1",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "pagination": {
      "records": { "limit": 25, "has_next": false, "has_previous": false },
      "navigation": { "next": null, "previous": null }
    }
  }
}

curl -g -X GET "https://api.sandbox.sovera.io/sovx/v1/users/{{userID}}/accounts/transactions?filter[where][created_at][gte]=2026-10-01T00:00:00Z&filter[limit]=25" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 UNAUTHORIZED · 403 FORBIDDEN a user token for another user · 404 USER_NOT_FOUND · 422 VALIDATION_ERROR unknown filter, operator, or cursor, with source.parameter · 429 RATE_LIMIT_EXCEEDED.

The transaction object

Every ledger list (wallet, user, and account) returns this shape. A movement always states one currency, and every amount is a decimal string in it. For trades, currency is the quote asset of pair (USD in USDT/USD), so amount, fee, net_amount, and price all read in the quote asset.

Field	Type	Description
id	string	Movement id.
object	string	Always `transaction`.
type	string	`DEPOSIT`, `WITHDRAWAL`, `BUY`, `SELL`, `TRANSFER_IN`, `TRANSFER_OUT`, `CREDIT`, or `CHARGE`. Open enum.
status	string	`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`, `EXPIRED`, or `BLOCKED`.
status_reason	object \| null	`{code, message}` when the movement didn't succeed; `null` otherwise.
customer_id	string	Your customer id.
user_id	string \| null	User the movement belongs to.
wallet_id	string \| null	Wallet the movement belongs to.
currency	string \| null	Currency every amount is stated in.
amount	string \| null	Gross amount.
fee	string \| null	Fee charged, or `null`.
net_amount	string \| null	Amount after fees.
price	string \| null	Trade price in the quote asset; `null` for non-trades.
pair	string \| null	Trading pair as `BASE/QUOTE`; `null` for non-trades.
base_currency / quote_currency	string	Present only on trades.
balance_after	string \| null	Balance in `currency` after the movement.
references	object	`order_id`, `withdrawal_id`, `transfer_id`, `deposit_id`: the resource that produced the movement, or `null`.
address	string \| null	On-chain address, for deposits and withdrawals.
network	string \| null	Canonical network code.
memo	string \| null	Memo or destination tag.
tx_hash	string \| null	On-chain hash; `null` until broadcast and for internal movements.
idempotency_key	string \| null	`x-idempotency-key` of the request that created the movement.
description	string \| null	Free-text description.
created_at / updated_at / completed_at	string \| null	UTC timestamps without milliseconds; `completed_at` is `null` until the movement settles.
created_by / updated_by	string \| null	Actor that created or last changed the movement.