Wallets

Open a wallet

Opens an on-chain deposit wallet on the requested network for your master account, or for the sub-account named in Zuba-Account-Id, whose deposits then settle into that sub-account’s balance. Idempotent per owner, network and clientRef: if the wallet already exists it is returned with 201 → 200, provided at least one asset on that network is still enabled for you; when none is, opening is refused and the existing wallet is read through GET /v1/wallets instead. Send any of the wallet’s assets to its address on that network; the deposit is credited once it confirms on-chain, provided it meets the per-transfer minimum. A smaller transfer, or a transfer on a network other than the wallet’s own, is not credited, does not appear in GET /v1/deposits, and cannot be recovered.

POST

wallets

Open a wallet

curl --request POST \
  --url https://api.example.com/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "network": "eip155:1",
  "clientRef": "customer-1234"
}
'

import requests

url = "https://api.example.com/v1/wallets"

payload = {
    "network": "eip155:1",
    "clientRef": "customer-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({network: 'eip155:1', clientRef: 'customer-1234'})
};

fetch('https://api.example.com/v1/wallets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/wallets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'network' => 'eip155:1',
    'clientRef' => 'customer-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/wallets"

	payload := strings.NewReader("{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/wallets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "assets": [
    "USDT",
    "USDC"
  ],
  "createdAt": "2026-09-09T12:00:00.000Z",
  "id": "9b2f4c1e-3d7a-4e8b-9f01-2c3d4e5f6a7b",
  "network": "eip155:1",
  "status": "active",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "customer-1234"
}

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "assets": [
    "USDT",
    "USDC"
  ],
  "createdAt": "2026-09-09T12:00:00.000Z",
  "id": "9b2f4c1e-3d7a-4e8b-9f01-2c3d4e5f6a7b",
  "network": "eip155:1",
  "status": "active",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "customer-1234"
}

{
  "details": [
    {
      "field": "accounts.0.data.crAccount",
      "message": "crAccount must be exactly 10 digits for Nigerian accounts"
    }
  ],
  "error": "BAD_REQUEST",
  "message": "Validation failed",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "category": "BUSINESS_DECLINE",
  "code": "STATE_CONFLICT",
  "detail": "The wallet for this owner, network and clientRef is inactive or archived and cannot be re-opened. Contact support.",
  "request_id": "req_01HZY7",
  "status": 409,
  "title": "The request conflicts with the current state",
  "type": "https://errors.zuba.com/business-decline/state-conflict",
  "instance": "/v1/wallets",
  "retryable": false
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

Enter Auth0 JWT token

Headers

Zuba-Account-Id

string<uuid>

Optional. Names an owned sub-account (UUID) to act on. Omit to act at the master (tenant) level. Naming an account this key does not own returns 403 not_account_owner.

Body

application/json

network

enum<string>

required

Network to open the wallet on, as a CAIP-2 chain id (e.g. "eip155:1" for Ethereum mainnet).

Available options:

eip155:1,

eip155:8453,

eip155:4217,

eip155:42431,

solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp,

tron:mainnet,

solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1

Example:

"eip155:1"

clientRef

string

Optional client reference. Omit for the owner's single default wallet on this network; pass distinct values (e.g. your end-customer id) to open distinct wallets. Must be 1 to 100 single-byte characters with no line break, must not begin or end with whitespace, and must not start with "pool-", a prefix reserved for platform-minted order-funding addresses.

Required string length: 1 - 100

Pattern: ^[\x21-\xff](?:[\x01-\x09\x0b\x0c\x0e-\xff]*[\x21-\xff])?$

Example:

"customer-1234"

Response

The owner already held a wallet on this network for this clientRef.

address

string

required

On-chain address to send funds to. Deposits are credited only on the wallet's own network: an EVM address is syntactically valid on every EVM chain, but a transfer to it on another chain is not credited.

Example:

"0x1234567890abcdef1234567890abcdef12345678"

assets

string[]

required

Stablecoins your account is credited for when they arrive at this address. Any other token, and any listed token sent on another network, is not credited. Empty when nothing on this network is currently offered to your account, and empty on a wallet whose status is not active, which credits nothing.

Example:

["USDT", "USDC"]

createdAt

string

required

When the wallet was opened, ISO-8601.

Example:

"2026-09-09T12:00:00.000Z"

string<uuid>

required

Wallet id.

Example:

"9b2f4c1e-3d7a-4e8b-9f01-2c3d4e5f6a7b"

network

enum<string>

required

Available options:

eip155:1,

eip155:8453,

eip155:4217,

eip155:42431,

solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp,

tron:mainnet,

solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1

Example:

"eip155:1"

status

enum<string>

required

active: receives deposits. inactive: frozen; deposits are held for review and the wallet cannot be re-requested. Contact support.

Available options:

active,

inactive

Example:

"active"

accountId

string<uuid>

The sub-account that owns the wallet; deposits to it settle into that sub-account's balance. Absent when the wallet belongs to your master account.

clientRef

string

The client reference the wallet was opened with, if any.

Example:

"customer-1234"

Open a wallet

curl --request POST \
  --url https://api.example.com/v1/wallets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "network": "eip155:1",
  "clientRef": "customer-1234"
}
'

import requests

url = "https://api.example.com/v1/wallets"

payload = {
    "network": "eip155:1",
    "clientRef": "customer-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({network: 'eip155:1', clientRef: 'customer-1234'})
};

fetch('https://api.example.com/v1/wallets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/wallets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'network' => 'eip155:1',
    'clientRef' => 'customer-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/wallets"

	payload := strings.NewReader("{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/wallets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/wallets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"network\": \"eip155:1\",\n  \"clientRef\": \"customer-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "assets": [
    "USDT",
    "USDC"
  ],
  "createdAt": "2026-09-09T12:00:00.000Z",
  "id": "9b2f4c1e-3d7a-4e8b-9f01-2c3d4e5f6a7b",
  "network": "eip155:1",
  "status": "active",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "customer-1234"
}

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "assets": [
    "USDT",
    "USDC"
  ],
  "createdAt": "2026-09-09T12:00:00.000Z",
  "id": "9b2f4c1e-3d7a-4e8b-9f01-2c3d4e5f6a7b",
  "network": "eip155:1",
  "status": "active",
  "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRef": "customer-1234"
}

{
  "details": [
    {
      "field": "accounts.0.data.crAccount",
      "message": "crAccount must be exactly 10 digits for Nigerian accounts"
    }
  ],
  "error": "BAD_REQUEST",
  "message": "Validation failed",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "category": "BUSINESS_DECLINE",
  "code": "STATE_CONFLICT",
  "detail": "The wallet for this owner, network and clientRef is inactive or archived and cannot be re-opened. Contact support.",
  "request_id": "req_01HZY7",
  "status": 409,
  "title": "The request conflicts with the current state",
  "type": "https://errors.zuba.com/business-decline/state-conflict",
  "instance": "/v1/wallets",
  "retryable": false
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{
  "error": "BAD_REQUEST",
  "message": "Bad Request",
  "path": "/v1/resource",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}