Global Wallets

Before You Start

Read the following guides before proceeding:

Overview

A global wallet is an additional address registered against the corporation so that deposits arriving at
it are attributed to the corporation. It is a bookkeeping registration, not a deployment: the address
must already exist, and the API does not create, verify or fund it.

The registered wallet appears in GET /api/v1/wallets with wallet_type Global.

Register a Global Wallet

POST /api/v1/wallets/global

Requires Su. This is a superuser-only endpoint and cannot be delegated to a custom role.

Request body:

{
  "wallet_address": "0xAAFF0821A09A1Aac28B72dD3Ff410A7ea5FEb874",
  "wallet_name": "Treasury deposits"
}

Response:

{}

The wallet is recorded with wallet_type Global and wallet_status Unknown, and the calling
employee's address is stored as its creator.

The address is not validated beyond being non-zero. There is no check that it is deployed, that it
is an Account Abstraction wallet, that it carries the required modules, or that the corporation
controls it. A typo registers successfully and returns 200; deposits sent to the wrong address are
not recoverable through the API. Verify the address before calling.

wallet_status stays Unknown until the platform verifies the wallet. Unknown is not a failure
and not a success — it means verification has not run. Do not gate a deposit flow on Confirmed
without confirming with Wirex what verification applies to global wallets in your configuration.

Code

const response = await fetch(`${baseUrl}/api/v1/wallets/global`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${corporationToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    wallet_address: walletAddress,
    wallet_name: 'Treasury deposits'
  })
});

response = requests.post(
    f"{base_url}/api/v1/wallets/global",
    headers={
        "Authorization": f"Bearer {corporation_token}",
        "Content-Type": "application/json",
    },
    json={"wallet_address": wallet_address, "wallet_name": "Treasury deposits"},
)

body, _ := json.Marshal(map[string]string{
    "wallet_address": walletAddress,
    "wallet_name":    "Treasury deposits",
})

req, _ := http.NewRequest("POST", baseURL+"/api/v1/wallets/global", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+corporationToken)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Cross-Chain Deposits via Rhino.fi

Registering a global wallet is bookkeeping. The bridged multi-chain deposit address itself is created
client-side through Rhino.fi, exactly as it is on the retail side — the corporate and retail
integrations share the same infrastructure and the same Rhino.fi SDK.

Your Rhino.fi API key is delivered in the client application configuration:

GET /api/v1/config

The key is returned under auth.rhinoApiKey. Pass it to the Wirex SDK as rhinoApiKey to enable the
smart deposit address service, or to the Rhino.fi SDK directly.

Supported chains, supported tokens, the deposit flow and timing expectations are identical to retail
and are documented once, in Global Addresses. Read that page for the
mechanics; the only corporate-specific step is registering the resulting address against the
corporation with POST /api/v1/wallets/global so that arriving deposits are attributed correctly.

The two calls are independent. Creating a deposit address through Rhino.fi does not register it
with Wirex, and registering an address does not create a bridged deposit address for it.

Limitations

• There is no endpoint to rename, deregister or delete a global wallet.
• There is no endpoint to list global wallets separately — read GET /api/v1/wallets and filter on
  wallet_type.
• Registering the same address twice is rejected downstream and surfaces as
  Failed to create global wallet.
• POST /api/v1/wallets/global does not create a bridged deposit address. Create it through
  Rhino.fi first — see Cross-Chain Deposits via Rhino.fi.

Error Handling

{
  "error_reason": "ErrorInvalidField",
  "error_description": "wallet address must be a valid address",
  "error_category": {
    "category": "CategoryValidationFailure",
    "http_status_code": 400
  },
  "error_details": [
    { "key": "field", "details": "wallet_address" }
  ]
}

Validation Errors (400)

Permission Errors (403)

Server Errors (500)