Customer Vault
Read the health of your treasury vault and the live balance of your treasury wallet.
Withdrawals pay out from your treasury vault, and network fees come from a sponsor wallet with a backup gas wallet behind it. Read the overall health of those wallets, or just the treasury balance, before you start a large payout. Sovera sets up the vault for you; these endpoints only read it.
Authentication: both endpoints take your dashboard session token as a Bearer token. The session must own the {customer_id} in the path; any other id answers 404 CUSTOMER_NOT_FOUND.
Authorization: Bearer YOUR_SESSION_TOKENResponses use the standard envelope. Balances and thresholds are {amount, currency} objects with the amount as a decimal string at the asset's scale—see Money and amounts.
Get Vault Health
Return the live balances of the treasury, sponsor, and backup gas wallets, the thresholds they're measured against, and an overall status.
Status
status | Meaning | status_reason.code |
|---|---|---|
HEALTHY | Every wallet was read and sits above its threshold. | — |
DEGRADED | A wallet couldn't be read, or sits below its threshold. | WALLET_BALANCE_UNAVAILABLE, TREASURY_BELOW_THRESHOLD, GAS_BELOW_THRESHOLD |
UNHEALTHY | The treasury couldn't be read, or the sponsor's gas is below the backup threshold. | WALLET_BALANCE_UNAVAILABLE, GAS_BELOW_THRESHOLD |
Response Fields
| Field | Type | Description |
|---|---|---|
| object | string | Always vault_health. |
| customer_id | string | Owning customer. |
| vault_id | string | Your vault id. |
| status | string | HEALTHY, DEGRADED, or UNHEALTHY. |
| status_reason | object | null | {code, message} when not HEALTHY. |
| treasury_wallet_share_percent | string | null | Share of deposits kept in the treasury wallet, e.g. "10.00". |
| treasury_threshold | object | null | Minimum treasury balance ({amount, currency}). |
| gas_low_threshold | object | null | Sponsor gas level that raises a low-gas alert. |
| gas_backup_threshold | object | null | Sponsor gas level below which the backup gas wallet takes over. |
| wallets | array | One entry per configured wallet: role (TREASURY, SPONSOR, BACKUP_GAS), wallet_id, status (AVAILABLE or UNAVAILABLE), status_reason, balances[], is_below_threshold (TREASURY is compared with treasury_threshold; SPONSOR and BACKUP_GAS with gas_low_threshold). |
| checked_at | string | When the balances were read (UTC). |
GET https://api.sandbox.sovera.io/sovx/v1/customers/corp-redundant-firewall/vault/healthSuccess Response (200 OK):
{
"success": true,
"data": {
"object": "vault_health",
"customer_id": "corp-redundant-firewall",
"vault_id": "ebe03a8d34ea",
"status": "DEGRADED",
"status_reason": {
"code": "WALLET_BALANCE_UNAVAILABLE",
"message": "The backup gas wallet balance could not be retrieved."
},
"treasury_wallet_share_percent": "10.00",
"treasury_threshold": { "amount": "100.000000", "currency": "USDT" },
"gas_low_threshold": { "amount": "0.050000000000000000", "currency": "ETH" },
"gas_backup_threshold": { "amount": "0.010000000000000000", "currency": "ETH" },
"wallets": [
{
"role": "TREASURY",
"wallet_id": "3fbb9fa90d57",
"status": "AVAILABLE",
"status_reason": null,
"balances": [
{ "amount": "0.420000000000000000", "currency": "ETH" },
{ "amount": "1250.500000", "currency": "USDT" }
],
"is_below_threshold": false
},
{
"role": "SPONSOR",
"wallet_id": "a1b2c3d4e5f6",
"status": "AVAILABLE",
"status_reason": null,
"balances": [{ "amount": "0.031000000000000000", "currency": "ETH" }],
"is_below_threshold": true
},
{
"role": "BACKUP_GAS",
"wallet_id": "b2c3d4e5f6a7",
"status": "UNAVAILABLE",
"status_reason": {
"code": "WALLET_BALANCE_UNAVAILABLE",
"message": "Balance could not be retrieved from the custody provider."
},
"balances": [],
"is_below_threshold": false
}
],
"checked_at": "2026-10-12T14:03:21Z"
},
"meta": {
"timestamp": "2026-10-12T14:03:21Z",
"version": "v1",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/corp-redundant-firewall/vault/health" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"Errors: 401 UNAUTHORIZED missing or invalid session · 404 CUSTOMER_NOT_FOUND not owned by the session, or deleted · 404 VAULT_NOT_CONFIGURED no vault is set up for this customer yet.
Get Treasury Balance
Return the live balance of every asset in your treasury wallet.
Response Fields
| Field | Type | Description |
|---|---|---|
| object | string | Always treasury_balance. |
| customer_id | string | Owning customer. |
| vault_id | string | Your vault id. |
| wallet_id | string | Treasury wallet id. |
| balances | array | {amount, currency} per asset. |
| total_assets | integer | Number of entries in balances. |
| as_of | string | When the balance was read (UTC). |
GET https://api.sandbox.sovera.io/sovx/v1/customers/corp-redundant-firewall/vault/treasury/balanceSuccess Response (200 OK):
{
"success": true,
"data": {
"object": "treasury_balance",
"customer_id": "corp-redundant-firewall",
"vault_id": "ebe03a8d34ea",
"wallet_id": "3fbb9fa90d57",
"balances": [
{ "amount": "0.420000000000000000", "currency": "ETH" },
{ "amount": "1250.500000", "currency": "USDT" }
],
"total_assets": 2,
"as_of": "2026-10-12T14:03:21Z"
},
"meta": {
"timestamp": "2026-10-12T14:03:21Z",
"version": "v1",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}curl -X GET "https://api.sandbox.sovera.io/sovx/v1/customers/corp-redundant-firewall/vault/treasury/balance" \
-H "Authorization: Bearer YOUR_SESSION_TOKEN"Errors: 401 UNAUTHORIZED missing or invalid session · 404 CUSTOMER_NOT_FOUND not owned by the session, or deleted · 404 VAULT_NOT_CONFIGURED no vault set up · 404 TREASURY_WALLET_NOT_CONFIGURED no treasury wallet set up.
Customer Webhooks
Register the HTTPS endpoint the platform pushes events to—including the withdrawal and transfer verification codes—then verify it.
User Onboarding Workflow
Complete guide to onboarding a new user: create the account, activate it, issue a token, create a wallet, and generate a deposit address.