Wallets

The Wallets API lets you inspect the wallets available in your 100Pay app — list all supported crypto wallets, and retrieve balance breakdowns per symbol or across all currencies.

Wallet operations require your Secret API Key and must be called server-side only.

Initialize


import { Pay100 } from "@100pay-hq/100pay.js";
 
const client = new Pay100({
  publicKey: "your_public_key",
  secretKey: "your_secret_key",
});

Get Supported Wallets

Returns all wallets supported by your 100Pay app, including network details, addresses, fees, and balances.


const wallets = await client.wallet.getSupportedWallets();
 
wallets.data.forEach((wallet) => {
  console.log(`${wallet.symbol} on ${wallet.networks.join(", ")}`);
  console.log(`  Address: ${wallet.account.address}`);
  console.log(`  Available: ${wallet.balance.available}`);
});

Response


{
  "statusCode": 200,
  "message": "Supported wallets retrieved",
  "data": [
    {
      "name": "Tether USDT",
      "symbol": "USDT",
      "decimals": "18",
      "networks": ["bsc", "ethereum", "tron"],
      "hotwallet": "0xHOTWALLET...",
      "balance": {
        "available": "1000.00",
        "locked": "0.00"
      },
      "account": {
        "address": "0xYOUR_ADDRESS..."
      },
      "fee": {
        "transfer": 0.5,
        "convert": 1.0
      },
      "contractAddress": "0xCONTRACT...",
      "logo": "https://..."
    }
  ]
}

Get Wallet Balance

Retrieve balance information for your app’s wallets. Returns aggregated totals with optional currency conversion.

All balances


// Get all wallet balances
const result = await client.wallet.getBalance();
 
if ("balances" in result.data) {
  result.data.balances.forEach((b) => {
    console.log(`${b.symbol}: ${b.totalBalance} (${b.walletCount} wallets)`);
  });
  console.log("Total wallets:", result.data.summary.totalWallets);
}

Single symbol


// Get balance for a specific symbol
const result = await client.wallet.getBalance({ symbol: "USDT" });
 
if ("symbol" in result.data) {
  const b = result.data;
  console.log(`Total: ${b.totalBalance} ${b.symbol}`);
  console.log(`Successful: ${b.successfulBalance}`);
  console.log(`Pending: ${b.pendingBalance}`);
  console.log(`Credits: ${b.totalCredit} | Debits: ${b.totalDebit}`);
}

With conversion


// Convert all balances to USD
const result = await client.wallet.getBalance({ targetCurrency: "USD" });
 
if ("balances" in result.data) {
  const { convertedSummary } = result.data;
  console.log(`Total balance (USD): ${convertedSummary.totalBalance}`);
  console.log(`Total credit (USD): ${convertedSummary.totalCredit}`);
}
 
// Or convert a single symbol
const usdt = await client.wallet.getBalance({
  symbol: "USDT",
  targetCurrency: "NGN",
});

Parameters

Field	Type	Required	Description
`symbol`	`string`	—	Filter by a specific currency symbol (e.g. `"USDT"`, `"BTC"`, `"NGN"`)
`targetCurrency`	`string`	—	Convert all balances to this currency (e.g. `"USD"`, `"NGN"`)

Response — All Balances (no `symbol`)


{
  "success": true,
  "message": "Balances retrieved successfully",
  "data": {
    "balances": [
      {
        "symbol": "USDT",
        "totalBalance": 500,
        "successfulBalance": 500,
        "pendingBalance": 0,
        "totalCredit": 600,
        "totalDebit": 100,
        "transactionCount": 12,
        "walletCount": 1,
        "converted": {
          "currency": "USD",
          "totalBalance": 500,
          "exchangeRate": 1,
          "ratesSource": "database"
        }
      }
    ],
    "summary": {
      "totalWallets": 3,
      "totalSymbols": 3
    },
    "convertedSummary": {
      "currency": "USD",
      "totalBalance": 500,
      "successfulBalance": 500,
      "pendingBalance": 0,
      "totalCredit": 600,
      "totalDebit": 100,
      "conversionErrors": 0,
      "note": "All conversions successful"
    }
  },
  "meta": {}
}

Response — Single Symbol (with `symbol`)


{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "symbol": "USDT",
    "totalBalance": 500,
    "successfulBalance": 500,
    "pendingBalance": 0,
    "totalCredit": 600,
    "totalDebit": 100,
    "transactionCount": 12,
    "walletCount": 1,
    "converted": {
      "currency": "USD",
      "totalBalance": 500,
      "exchangeRate": 1,
      "ratesSource": "database"
    }
  },
  "meta": {}
}

Balance Fields

Field	Description
`totalBalance`	Full balance (successful + pending transactions)
`successfulBalance`	Confirmed settled balance
`pendingBalance`	Unconfirmed/in-progress balance
`totalCredit`	Sum of all incoming transactions
`totalDebit`	Sum of all outgoing transactions
`transactionCount`	Number of transactions
`walletCount`	Number of wallet addresses contributing
`converted`	Balance values in the `targetCurrency` (with exchange rate)

Distinguishing Response Shapes

The return type is a union — use a type guard to distinguish:


import {
  IWalletBalanceSingleResponse,
  IWalletBalanceAllResponse,
} from "@100pay-hq/100pay.js";
 
const result = await client.wallet.getBalance({ targetCurrency: "USD" });
 
if ("balances" in result.data) {
  // IWalletBalanceAllResponse — all symbols present
  const all = result as IWalletBalanceAllResponse;
  console.log(all.data.summary.totalWallets);
} else {
  // IWalletBalanceSingleResponse — single symbol
  const single = result as IWalletBalanceSingleResponse;
  console.log(single.data.symbol, single.data.totalBalance);
}

TypeScript Types


interface IWalletBalanceParams {
  symbol?: string;
  targetCurrency?: string;
}
 
interface IWalletBalanceItem {
  symbol: string;
  totalBalance: number;
  successfulBalance: number;
  pendingBalance: number;
  totalCredit: number;
  totalDebit: number;
  transactionCount: number;
  walletCount: number;
  converted: IConvertedBalance;
}
 
type IWalletBalanceResponse =
  | IWalletBalanceSingleResponse   // when symbol is provided
  | IWalletBalanceAllResponse;     // when no symbol filter

Next Steps

Currency Conversion — preview exchange rates before swapping
Asset Transfers — move funds between wallets
Subaccounts — create per-customer wallets