Account Management
Read your customer account's aggregate balance and its full transaction ledger.
Read account-wide data for your customer: the aggregate balance held in custody and the ledger of movements across your account. Both endpoints report at the customer level; they don't scope to a single user. For one user, see User Account.
Authentication: both endpoints require your Owner API Key. A user token or a non-owner key answers 403 FORBIDDEN.
x-api-key: YOUR_OWNER_API_KEYSee API conventions for the envelope, errors, pagination and filters, and money.
Get Account Balance
Read your account's aggregate balance per currency. Every amount is a decimal string at the asset's scale (USD 4, BTC 8…).
Response Fields
| Field | Type | Description |
|---|---|---|
| object | string | Always account_balance. |
| customer_id | string | Your customer 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/accounts/balanceNo query parameters.
Success Response (200 OK):
{
"success": true,
"data": {
"object": "account_balance",
"customer_id": "corp-redundant-firewall",
"balances": [
{ "currency": "USD", "total": "10000.0000", "available": "9000.0000", "held": "1000.0000" },
{ "currency": "BTC", "total": "0.50000000", "available": "0.30000000", "held": "0.20000000" }
],
"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/accounts/balance" \
-H "x-api-key: YOUR_OWNER_API_KEY"Errors: 401 UNAUTHORIZED · 403 FORBIDDEN not an owner key · 429 RATE_LIMIT_EXCEEDED · 502 BAD_GATEWAY the ledger service is unavailable; retry later.
List Account Transactions
List the movements on your customer account, newest first. Each item is a transaction object. Account-level rows aren't tied to a user or wallet, so user_id and wallet_id are null, and idempotency_key is null too. Rows that come from the custody log record no completion time or actor, so their completed_at, created_by, and updated_by are null.
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.next. |
| filter[order] | string | No | created_at DESC (default) or created_at ASC. |
| filter[where][status][eq|inq] | string | No | PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, EXPIRED, BLOCKED. |
| filter[where][currency][eq|inq] | string | No | Currency code. |
| filter[where][tx_hash][eq] | string | No | On-chain transaction hash. |
| filter[where][idempotency_key][eq] | string | No | Accepted for symmetry; account rows carry no key, so it matches nothing. |
| filter[where][created_at][gte|lte|between] | string | No | UTC date-time ending in Z. |
This list pages forward only: follow navigation.next; navigation.previous is always null. A page may hold fewer items than filter[limit] when filters narrow it; keep following next while has_next is true.
GET https://api.sandbox.sovera.io/sovx/v1/accounts/transactions?filter[where][currency][eq]=USD&filter[limit]=25Success 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": null,
"wallet_id": null,
"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": null,
"description": null,
"created_at": "2026-05-19T20:24:01Z",
"updated_at": "2026-05-19T20:24:03Z",
"completed_at": null,
"created_by": null,
"updated_by": null
}
],
"meta": {
"timestamp": "2026-10-12T14:03:11Z",
"version": "v1",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"pagination": {
"records": { "limit": 25, "has_next": true, "has_previous": false },
"navigation": {
"next": "/v1/accounts/transactions?filter[limit]=25&cursor=LGHoC3t43si9_yVEikVSoItl",
"previous": null
}
}
}
}curl -g -X GET "https://api.sandbox.sovera.io/sovx/v1/accounts/transactions?filter[where][currency][eq]=USD&filter[limit]=25" \
-H "x-api-key: YOUR_OWNER_API_KEY"Errors: 401 UNAUTHORIZED · 403 FORBIDDEN not an owner key · 422 VALIDATION_ERROR unknown filter, operator, or cursor, with source.parameter · 429 RATE_LIMIT_EXCEEDED · 502 BAD_GATEWAY the ledger service is unavailable; retry later.