Account Management
Read your owner-level aggregate balance and full transaction history across all your end users.
Read account-wide data for your customer account: the aggregate balance held in custody and the transaction history across every user you manage. Both endpoints report at the owner level—they don't scope to a single user.
Authentication: every endpoint on this page requires your Owner API Key. Only owner clients can call them; a user token or any non-owner key returns 403 Forbidden.
x-api-key: YOUR_OWNER_API_KEYAll requests accept an optional x-trace-id header for request tracking; if omitted, one is generated.
The gateway reshapes the upstream custody payload into the schema shown below—it doesn't pass it through. Balance is trimmed to four fields per currency; each transaction unifies the order and the trade into a single transaction object.
Get Account Balance
Fetch your account's latest aggregate balance from custody. This is the owner-level total across all currencies your customer account holds—not a per-user view.
GET https://api.sandbox.sovera.io/sovx/v1/accounts/balanceNo query parameters.
Success Response (200 OK):
data is a flat array. Each item:
| Field | Type | Description |
|---|---|---|
currency | string | Currency code (lowercase). |
balance | number | Total balance. |
available | number | Available to trade or withdraw. |
held | number | Held (not available). |
{
"success": true,
"data": [
{
"currency": "usd",
"balance": 10000,
"available": 9000,
"held": 1000
},
{
"currency": "btc",
"balance": 0.5,
"available": 0.3,
"held": 0.2
}
],
"meta": {
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v1",
"trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
}
}sFox returns nine fields per item; the gateway exposes only these four and drops borrow_wallet, collateral_wallet, lending_wallet, trading_wallet, and staking_wallet.
curl -X GET "https://api.sandbox.sovera.io/sovx/v1/accounts/balance" \
-H "x-api-key: YOUR_OWNER_API_KEY"Errors: 401 invalid key · 403 not an owner client · 500 server error.
Get Account Transactions
Retrieve your account's transaction history across all users, newest first. Page and bound the result set, and narrow it with the filter[...] parameters below.
Query Parameters
All filters go under filter[...].
| 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][type] | string | No | Type/action. Accepts a comma-separated list. |
| filter[where][currency] | string | No | Currency code. |
| filter[where][status] | string | No | Transaction status (e.g. pending, done). |
| filter[where][from] | number | No | Start date, Unix timestamp in ms (inclusive). |
| filter[where][to] | number | No | End date, Unix timestamp in ms (inclusive). |
| filter[where][amount][gte] | number | No | Amount ≥ value. |
| filter[where][amount][lte] | number | No | Amount ≤ value. |
filter[where][from|to], filter[limit], filter[skip], filter[sort], and filter[where][type|currency|status] are forwarded to the custody provider; the gte/lte amount bounds are applied by the gateway over the returned set—so an amount range narrows the current page rather than the upstream query.
GET https://api.sandbox.sovera.io/sovx/v1/accounts/transactions?filter[limit]=20&filter[where][currency]=BTCSuccess Response (200 OK):
data is an array. Each item carries id and balance at the root, plus a transaction object with the rest of the detail.
| Field | Type | Description |
|---|---|---|
id | number | Numeric transaction ID in sFox. |
balance | number | Resulting account balance after the transaction. |
transaction | object | Order and transaction detail. |
transaction.order_id | string | Order ID (numeric string; empty when not applicable, e.g. charges or deposits). |
transaction.trade_id | string | Trade ID (numeric string; empty when not applicable). |
transaction.client_id | string (uuid) | Associated client (injected by the backend from the account). |
transaction.idempotency_id | string (uuid)|null | Idempotency ID. |
transaction.symbol | string|null | Trading pair (e.g. btc/usd), or null. |
transaction.created_at | string (ISO 8601) | Creation date. |
transaction.hash | string | On-chain hash (empty when not applicable). |
transaction.action | string | Movement type (e.g. Deposit, Sell, Charge). |
transaction.currency | string | Currency of the movement. |
transaction.memo | string | Note. |
transaction.amount | number | Amount (negative for outflows). |
transaction.net_proceeds | number | Net amount. |
transaction.price | number | Applied price. |
transaction.fees | number | Fees. |
transaction.status | string | Status (e.g. done). |
transaction.description | string|null | Description. |
{
"success": true,
"data": [
{
"id": 99938268,
"balance": 49071.06877634,
"transaction": {
"order_id": "11637477",
"trade_id": "71847575",
"client_id": "76f0b5a8-a683-4ee3-8b13-af3c807df325",
"idempotency_id": null,
"symbol": "usdt/usd",
"created_at": "2026-05-19T20:24:01.000Z",
"hash": "",
"action": "Sell",
"currency": "usd",
"memo": "",
"amount": 1004.95049505,
"net_proceeds": 1004.95049505,
"price": 1.00720535,
"fees": 10.04950495,
"status": "done",
"description": ""
}
}
],
"meta": {
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v1",
"trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
}
}id and balance sit at the item root; the rest of the order and trade detail nests inside transaction. The gateway normalizes keys to snake_case and unifies the date as created_at, dropping sFox fields it doesn't expose (atxid, client_order_id, algo_name, algo_id, hold_expires, the Unix timestamp, AccountTransferFee, wallet_display_id, and added_by_user_email).
curl -X GET "https://api.sandbox.sovera.io/sovx/v1/accounts/transactions?filter[limit]=20&filter[where][currency]=BTC" \
-H "x-api-key: YOUR_OWNER_API_KEY"Errors: 401 invalid key · 403 not an owner client · 500 server error.