Wallet Addresses

Create and read on-chain deposit addresses for a wallet, per currency and network.

Create and read the on-chain deposit addresses a wallet uses to receive funds. Each address is scoped to a currency and a network—create one per asset you want to accept, then hand the address to whoever's funding the wallet.

Authentication: every endpoint on this page accepts your Owner API Key (x-api-key) or a user token (Authorization: Bearer).

x-api-key: YOUR_OWNER_API_KEY

All requests accept an optional x-trace-id header for request tracking; if omitted, one is generated.

The address object always exposes address_id, currency, network, and address—nothing else.

Create Address

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

Create a deposit address for a wallet on a given currency and network. If the wallet already holds an address for that pairing, the existing one comes back instead of a new one. The response carries the wallet's own fields plus the addresses involved—same shape as List Addresses.

Request Body

Field	Type	Required	Description
currency	string	Yes	Currency code. Lowercased on receipt (e.g. `btc`, `eth`, `usdc`).
network	string	Yes	Network for the address (e.g. `bitcoin-testnet`, `ethereum-sepolia`).

{
  "currency": "btc",
  "network": "bitcoin-testnet"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "wallet_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "vault_wallet_id": "vault-7f3a2b1c",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "name": "Main Wallet",
    "description": "Primary trading wallet",
    "addresses": [
      {
        "address_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "currency": "btc",
        "network": "bitcoin-testnet",
        "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
      }
    ],
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/address" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY_OR_USER_TOKEN" \
  -d '{
    "currency": "btc",
    "network": "bitcoin-testnet"
  }'

Errors: 400 missing currency or network · 401 invalid key · 404 wallet not found · 500 server error.

List Addresses

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

List every deposit address on a wallet, with the wallet's own metadata wrapped around them. Each address carries its currency and network. A wallet with no addresses yet returns an empty addresses array.

GET https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/address

Success Response (200 OK):

{
  "success": true,
  "data": {
    "wallet_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "vault_wallet_id": "vault-7f3a2b1c",
    "user_id": "f4057807-52cf-4083-9ecb-283ef354fb2b",
    "name": "Main Wallet",
    "description": "Primary trading wallet",
    "addresses": [
      {
        "address_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "currency": "btc",
        "network": "bitcoin-testnet",
        "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
      }
    ],
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/address" \
  -H "x-api-key: YOUR_OWNER_API_KEY_OR_USER_TOKEN"

Errors: 401 invalid key · 404 wallet not found · 500 server error.

Get Address by Currency

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

Fetch the deposit address for a single currency on a wallet. Pass the currency code as the last path segment (e.g. btc, eth, usdc). Returns 404 if the wallet has no address for that currency yet.

GET https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/address/btc

Success Response (200 OK):

{
  "success": true,
  "data": {
    "address_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "currency": "btc",
    "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
    "network": "bitcoin-testnet"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/wallets/{{walletID}}/address/btc" \
  -H "x-api-key: YOUR_OWNER_API_KEY_OR_USER_TOKEN"

Errors: 401 invalid key · 404 wallet not found or no address for that currency · 500 server error.

List Vault Networks

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

List the networks available in the client's vault. The client must have a vault_id configured—without one the call returns 400.

Response Fields

data is an array of networks. Each item carries:

Field	Type	Description
name	string	Network identifier (e.g. `networks/bitcoin-testnet`).
display_name	string	Human-readable name (e.g. `Bitcoin Testnet`).
currency	string	Currency code (e.g. `btc`).

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

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "name": "networks/bitcoin-testnet",
      "display_name": "Bitcoin Testnet",
      "currency": "btc"
    },
    {
      "name": "networks/ethereum-sepolia",
      "display_name": "Ethereum Sepolia",
      "currency": "eth"
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/vault/networks" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 400 vault not configured · 401 invalid key · 500 server error.

Wallet Addresses

Create Address

Request Body

List Addresses

Get Address by Currency

List Vault Networks

Response Fields

On this page