Global Addresses

Before You Start

Read the following guides before proceeding:

Overview

Global addresses allow users to receive deposits from multiple blockchains (Ethereum, Arbitrum, Polygon, etc.) that automatically bridge to their Base wallet. This is powered by Rhino.fi infrastructure.

Use case: A user wants to deposit USDC from Ethereum mainnet, but their Wirex wallet is on Base. Instead of manually bridging, they deposit to a global address that handles the bridging automatically.

How It Works

User deposits USDC          Rhino.fi               User's Base Wallet
on Ethereum                  Bridge
      |                        |                          |
      | 1. Send USDC to        |                          |
      |    global address      |                          |
      |----------------------->|                          |
      |                        |                          |
      |                        | 2. Detect deposit        |
      |                        |                          |
      |                        | 3. Bridge to Base        |
      |                        |------------------------->|
      |                        |                          |
      |                        |                          | 4. Wrap to WUSD
      |                        |                          |    in Smart Wallet
      |                        |                          |

1. User sends tokens to their chain-specific global address
2. Rhino.fi detects the deposit on the source chain
3. Tokens are bridged to Base chain
4. Tokens are wrapped into unified stablecoins (WUSD/WEUR) and deposited to user's Smart Wallet on Base

Supported Chains

Note: All EVM chains share the same global deposit address. TRON and Solana have separate addresses due to fundamental differences in address structure.

Supported Tokens

Creating Global Addresses

Global addresses are created via the Wirex SDK or Rhino.fi SDK directly.

Option A: Wirex SDK

import { createSDK } from '@wirexapp/wirexpay-sdk';

const sdk = await createSDK({ /* config */ });

// Generate global deposit addresses for all supported chains
const globalAddresses = await sdk.crypto.smartDeposit.createAddresses();

The SDK returns deposit addresses for each supported source chain.

Option B: Rhino.fi SDK

import { RhinoSdk, SupportedChains } from '@rhino.fi/sdk';

// Initialize SDK with API key (provided by Wirex)
const rhinoSdk = RhinoSdk({
  apiKey: process.env.RHINO_API_KEY,
});

// Supported chains for EVM deposits
const supportedEVMChains = [
  SupportedChains.ETHEREUM,
  SupportedChains.ARBITRUM_ONE,
  SupportedChains.POLYGON,
  SupportedChains.OPTIMISM,
  SupportedChains.BNB_SMART_CHAIN,
  SupportedChains.KAIA,
];

async function createGlobalAddresses(smartWalletAddress: string) {
  // Create deposit addresses for EVM chains
  const response = await rhinoSdk.api.depositAddresses.create({
    depositChains: supportedEVMChains,
    destinationChain: SupportedChains.BASE,
    destinationAddress: smartWalletAddress,
    bridgeIfNotSwappable: true,
    tokenOut: 'USDC',
    postBridgeData: {
      _tag: 'wirexwrap',
    },
    reusePolicy: 'reuse-existing',
  });

  if (response.response.status !== 200 || !response.data) {
    throw new Error(`Failed to create addresses: ${JSON.stringify(response.error)}`);
  }

  // Activate any inactive addresses
  const activationPromises = response.data
    .filter((addr) => !addr.isActive)
    .map((addr) =>
      rhinoSdk.api.depositAddresses.activate({
        depositAddress: addr.depositAddress,
        depositChain: addr.depositChain,
      })
    );

  await Promise.all(activationPromises);

  return response.data;
}

For TRON and Solana chains, create addresses separately:

// TRON addresses
const tronAddresses = await rhinoSdk.api.depositAddresses.create({
  depositChains: [SupportedChains.TRON],
  destinationChain: SupportedChains.BASE,
  destinationAddress: smartWalletAddress,
  // ... same options
});

// Solana addresses
const solanaAddresses = await rhinoSdk.api.depositAddresses.create({
  depositChains: [SupportedChains.SOLANA],
  destinationChain: SupportedChains.BASE,
  destinationAddress: smartWalletAddress,
  // ... same options
});

Linking Global Addresses to Wirex

After creating global addresses via Rhino.fi SDK, link them to the user on Wirex backend:

POST /api/v1/wallets/global

Headers:

• Authorization: Bearer {access_token}
• X-User-Address: {user_eoa_address}
• X-Chain-Id: {chain_id}

Request:

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE"
}

This links the global wallet to the user's account, allowing retrieval via the wallets endpoint.

Retrieving Global Addresses

Query wallets to find global wallet addresses:

GET /api/v1/wallets

Response:

[
  {
    "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
    "wallet_name": "Main Wallet",
    "wallet_status": "Confirmed",
    "wallet_type": "Primary",
    "balances": []
  },
  {
    "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
    "wallet_name": "Global Wallet",
    "wallet_status": "Confirmed",
    "wallet_type": "Global",
    "balances": []
  }
]

Filter by wallet_type: "Global" to identify global wallets.

Deposit Flow

1. User selects source chain — e.g., Ethereum mainnet
2. Display global address — Show the chain-specific deposit address
3. User sends tokens — Standard token transfer on source chain
4. Bridge processes — Rhino.fi bridges tokens to Base (typically 5-15 minutes)
5. Tokens wrapped — Tokens wrapped into WUSD/WEUR, balance webhook sent

Webhooks

When a deposit arrives via global address, two webhooks are sent:

Activity Webhook

Endpoint: POST {your_webhook_base_url}/v2/webhooks/activities

{
  "id": "eac95aab-ca2d-f6e4-ebd4-92312133a139",
  "user_address": "0x39Bdb53DDD0dd3666109f6839d62eE2a516f4b11",
  "type": "Crypto",
  "status": "Completed",
  "direction": "Inbound",
  "source": {
    "type": "ExternalWallet",
    "wallet": {
      "address": "0x3aa11B9433d49cc97EF8b9d723BdCDe31B04393A"
    }
  },
  "destination": {
    "type": "Wallet",
    "wallet": {
      "address": "0x7033b4FC3553E6F2ca0bd1E62f85AC5780A4Eb63"
    }
  },
  "source_amount": {
    "amount": 100.0,
    "token_symbol": "USDC",
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "destination_amount": {
    "amount": 100.0,
    "token_symbol": "WUSD",
    "token_address": "0xb4bB2032A73A53C0Aa7Dc9ee2d9658a978fA7bC2"
  }
}

Balance Webhook

Endpoint: POST {your_webhook_base_url}/v2/webhooks/balances

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "token_symbol": "WUSD",
  "token_address": "0xb4bB2032A73A53C0Aa7Dc9ee2d9658a978fA7bC2",
  "balance": 100.00,
  "reference_balance": 100.00,
  "reference_currency": "USD"
}

Note: The wallet_address is the user's Primary wallet on Base, not the global deposit address.

Timing Expectations

Bridge times depend on source chain finality and Rhino.fi processing.

Error Handling

Common Issues

Minimum Deposit Amounts

Minimum deposit amount is 1 USD/EUR equivalent. Deposits below this threshold may not be processed.

Integration Notes

• Global addresses are reusable — the same address works for multiple deposits
• Each user has unique global addresses per chain family (EVM, TRON, Solana)
• Bridging is automatic — no user action required after deposit
• Tokens are wrapped into unified stablecoins (WUSD/WEUR) — see Unified Balance