Wallets

Wallets are blockchain wallets belonging to an account. Each wallet is associated with a chain and can be assigned to one or more networks. Wallets hold balances in native and token currencies.

Wallet Model

Field	Type	Description
id	string (UUID)	Unique wallet identifier
name	string	Wallet name
account_id	string (UUID)	Parent account ID
chain_id	string (UUID)	Chain this wallet operates on
address	string	Blockchain address
custody_wallet_id	string (UUID)	Internal custody wallet reference
type	string	Wallet type (see below)
status	integer	Wallet status (see below)
created_at	string (ISO 8601)	Creation timestamp
updated_at	string (ISO 8601)	Last update timestamp
deleted_at	string (ISO 8601) | null	Soft deletion timestamp

Wallet Types

Value	Description
hot	Hot wallet -- connected to the network, used for frequent transactions
cold	Cold wallet -- offline storage, used for long-term asset security

Wallet Statuses

Value	Label
1	Active
2	Passive

Wallet with Networks

When listing wallets, each wallet includes its assigned networks with balance information:

{
  "id": "...",
  "name": "My Wallet",
  "networks": [
    {
      "id": "...",
      "name": "Ethereum Mainnet",
      "network_id": 1,
      "chain_id": "...",
      "native_currency": {
        "id": "...",
        "name": "ETH",
        "symbol": "ETH",
        "decimals": 18,
        "address": null,
        "logo_url": null,
        "balance": "1.5"
      }
    }
  ]
}

Wallet Detail

When fetching a single wallet, the response includes full balance details for all currencies on each network:

{
  "id": "...",
  "name": "My Wallet",
  "networks": [
    {
      "id": "...",
      "name": "Ethereum Mainnet",
      "network_id": 1,
      "chain_id": "...",
      "native_currency": {
        "id": "...",
        "name": "ETH",
        "symbol": "ETH",
        "decimals": 18,
        "balance": "1.5"
      },
      "currencies": [
        {
          "id": "...",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "logo_url": "https://example.com/usdc.png",
          "balance": "1000.00"
        }
      ]
    }
  ]
}

Endpoints

Method	Path	Description
POST	/v1/wallets/{account_id}	Create a new wallet
GET	/v1/wallets/{account_id}	List wallets by account
GET	/v1/wallets/{account_id}/{wallet_id}	Get wallet detail
POST	/v1/wallets/{wallet_id}/networks/{network_id}	Assign network to wallet
POST	/v1/wallets/{wallet_id}/withdraw	Withdraw from wallet