Wallet Addresses

Create and list a wallet's deposit addresses, and list the networks your vault supports.

Give a wallet a deposit address for a currency and network, list the addresses it already has, and check which networks your vault supports. Addresses are idempotent per wallet, currency, and network: asking again returns the address you already have.

Authentication: every endpoint on this page accepts your Owner API Key (x-api-key) or a user token (Authorization: Bearer). A user token only reaches wallets of its own user; any other wallet answers 404 WALLET_NOT_FOUND.

x-api-key: YOUR_OWNER_API_KEY

See API conventions for the envelope, errors, idempotency, pagination and filters, and network codes.

Renamed paths

/wallets/{wallet_id}/address is now /wallets/{wallet_id}/addresses. The old POST and GET …/address paths, and GET …/address/{currency}, still answer during the deprecation window and are removed in the next release. See Deprecated paths.

The address object

Field	Type	Description
id	string (UUID)	Address id.
address_id	string (UUID)	Same value as `id`, kept as an alias.
object	string	Always `address`.
wallet_id	string (UUID)	Wallet that owns the address.
currency	string	Uppercase currency code, e.g. `ETH`.
network	string	Canonical network code, e.g. `ETHEREUM`. Open enum: tolerate new values.
address	string	On-chain deposit address.
memo	string \| null	Destination tag or memo, when the network needs one.
created_at	string	UTC timestamp without milliseconds.
created_by	string \| null	Actor that created the address.

Create Deposit Address

POSThttps://api.sandbox.sovera.io/sovx/v1/wallets/:wallet_id/addresses

Return the wallet's deposit address for a currency on a network, creating it if needed. A new address answers 201 Created; an address that already exists for the same currency and network answers 200 OK with the stored address. Two concurrent requests for the same pair resolve to the same address.

Path Parameters

Parameter	Type	Required	Description
wallet_id	string (UUID)	Yes	Wallet to issue the address for.

Request Body

Field	Type	Required	Description
currency	string	Yes	Currency code, case-insensitive (e.g. `ETH`, `USDC`).
network	string	Yes	Canonical network code: `BITCOIN`, `ETHEREUM`, `SOLANA`, `TRON`, `POLYGON`, or `BNB_SMART_CHAIN`.

{
  "currency": "ETH",
  "network": "ETHEREUM"
}

Success Response (201 Created, or 200 OK when the address already existed):

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "address_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "object": "address",
    "wallet_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "currency": "ETH",
    "network": "ETHEREUM",
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "memo": null,
    "created_at": "2026-10-12T14:03:11Z",
    "created_by": "d5263d12-b5e8-5fc7-ba07-816c0c78a61a"
  },
  "meta": { "timestamp": "2026-10-12T14:03:11Z", "version": "v1", "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736" }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/addresses" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -H "x-idempotency-key: 0f8b2c4e-6a1d-4e3f-9b7c-2d5e8f1a3c6b" \
  -d '{
    "currency": "ETH",
    "network": "ETHEREUM"
  }'

Errors: 400 BAD_REQUEST the wallet can't issue addresses (create a new wallet) · 401 UNAUTHORIZED · 404 WALLET_NOT_FOUND · 422 VALIDATION_ERROR missing field or unknown network, with source.pointer (/network) · 429 RATE_LIMIT_EXCEEDED.

List Deposit Addresses

GEThttps://api.sandbox.sovera.io/sovx/v1/wallets/:wallet_id/addresses

List the wallet's deposit addresses, newest first. Filter by currency or network to find one address; a wallet with none 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 ASC` or `created_at DESC` (default).
filter[where][currency][eq\|inq]	string	No	Currency code, case-insensitive.
filter[where][network][eq\|inq]	string	No	Canonical network code.
filter[where][created_at][gte\|lte\|between]	string	No	UTC date-time ending in `Z`.

GET https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/addresses?filter[where][currency][eq]=BTC

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "ad1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "address_id": "ad1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
      "object": "address",
      "wallet_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "currency": "BTC",
      "network": "BITCOIN",
      "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
      "memo": null,
      "created_at": "2026-10-12T14:03:11Z",
      "created_by": "d5263d12-b5e8-5fc7-ba07-816c0c78a61a"
    }
  ],
  "meta": {
    "timestamp": "2026-10-12T14:05:40Z",
    "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/wallets/{{walletID}}/addresses?filter[where][currency][eq]=BTC" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 UNAUTHORIZED · 404 WALLET_NOT_FOUND · 422 VALIDATION_ERROR unknown filter, operator, network, or cursor, with source.parameter · 429 RATE_LIMIT_EXCEEDED.

List Vault Networks

GEThttps://api.sandbox.sovera.io/sovx/v1/vault/networks

List the networks enabled on your vault, with each network's native currency and the currencies you can hold on it. Use these codes in networks[].network when you create a wallet and in network when you create an address.

Query Parameters

Parameter	Type	Required	Description
filter[limit]	integer	No	Page size. Default 25, max 100.
filter[order]	string	No	`network ASC` (default) or `network DESC`.

The list is short, so it comes back in one page: navigation.next is always null.

Response Fields

Field	Type	Description
object	string	Always `network`.
network	string	Canonical network code.
display_name	string	Human-readable name, e.g. `BNB Smart Chain`.
native_currency	string	Asset that pays the network fee, e.g. `ETH`.
currencies	string[]	Currencies supported on the network.

GET https://api.sandbox.sovera.io/sovx/v1/vault/networks

Success Response (200 OK):

{
  "success": true,
  "data": [
    { "object": "network", "network": "BITCOIN", "display_name": "Bitcoin", "native_currency": "BTC", "currencies": ["BTC"] },
    { "object": "network", "network": "ETHEREUM", "display_name": "Ethereum", "native_currency": "ETH", "currencies": ["ETH", "USDC", "USDT"] }
  ],
  "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 -X GET "https://api.sandbox.sovera.io/sovx/v1/vault/networks" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 UNAUTHORIZED · 422 VALIDATION_ERROR invalid filter[limit] or filter[order] · 429 RATE_LIMIT_EXCEEDED.

Deprecated paths

These paths still answer during the deprecation window and are removed in the next release. Move to the new paths now.

Deprecated	Use instead	Notes
`POST /v1/wallets/{wallet_id}/address`	`POST /v1/wallets/{wallet_id}/addresses`	Same body and response.
`GET /v1/wallets/{wallet_id}/address`	`GET /v1/wallets/{wallet_id}/addresses`	Same paged list.
`GET /v1/wallets/{wallet_id}/address/{currency}`	`GET /v1/wallets/{wallet_id}/addresses?filter[where][currency][eq]={currency}`	Returns a single address object. Accepts an optional `network` query parameter to pick one network; no match is `404 ADDRESS_NOT_FOUND`.

Old network identifiers such as networks/bitcoin-testnet still resolve to their canonical code (BITCOIN) during the same window. Responses always carry the canonical code.

Wallet Addresses

On this page