Swipelux
Balances

Balances

Query and monitor wallet balances across your platform

Balances

Query wallet balances in real-time to display accurate fund information to your users.

Balance queries return the current state of wallets. For tracking balance changes and transaction events, see Webhooks.

Overview

The Balances API allows you to:

  • Query individual wallet balances
  • List all balances for a customer
  • Check balances across different networks
  • Monitor balance changes

Get Wallet Balance

Retrieve the current balance for a specific wallet.

Endpoint

GET /v1/wallets/:walletId/balance

Request Example

curl https://wallet.swipelux.com/v1/wallets/wal_abc123/balance \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "walletId": "wal_abc123",
  "network": "polygon",
  "balances": [
    {
      "currency": "USDC",
      "amount": "1250.50",
      "decimals": 6
    },
    {
      "currency": "USDT",
      "amount": "0.00",
      "decimals": 6
    }
  ],
  "lastUpdated": "2024-01-15T10:30:00Z"
}

Get Customer Balances

Retrieve all wallet balances for a customer across all networks.

Endpoint

GET /v1/customers/:customerId/balances

Request Example

curl https://wallet.swipelux.com/v1/customers/cus_abc123/balances \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "customerId": "cus_abc123",
  "totalBalance": {
    "amount": "2500.75",
    "currency": "USD"
  },
  "wallets": [
    {
      "walletId": "wal_poly_001",
      "network": "polygon",
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "balances": [
        {
          "currency": "USDC",
          "amount": "1250.50"
        }
      ]
    },
    {
      "walletId": "wal_eth_002",
      "network": "ethereum",
      "address": "0x9876543210987654321098765432109876543210",
      "balances": [
        {
          "currency": "USDC",
          "amount": "1250.25"
        }
      ]
    }
  ]
}

Response Fields

FieldTypeDescription
walletIdstringUnique wallet identifier
networkstringNetwork the wallet is on (polygon, ethereum, etc.)
balances[]arrayArray of token balances
balances[].currencystringCurrency/token symbol
balances[].amountstringBalance amount (decimal string)
balances[].decimalsnumberToken decimals
lastUpdatedstringISO timestamp of last balance update

Balance Tracking

For real-time balance change notifications, use webhooks. See Webhooks documentation for:

  • balance.updated events
  • transfer.completed events
  • payin.completed events
  • payout.completed events

Common Use Cases

Display User Balance

Show the current balance to users in your application:

async function displayUserBalance(customerId) {
  const response = await fetch(
    `https://wallet.swipelux.com/v1/customers/${customerId}/balances`,
    { headers: { 'X-API-Key': process.env.API_KEY } }
  );
  
  const data = await response.json();
  return {
    total: data.totalBalance.amount,
    currency: data.totalBalance.currency,
    wallets: data.wallets
  };
}

Check Sufficient Balance

Verify a user has sufficient funds before initiating a payout:

async function canAffordPay-out(walletId, amount, currency) {
  const response = await fetch(
    `https://wallet.swipelux.com/v1/wallets/${walletId}/balance`,
    { headers: { 'X-API-Key': process.env.API_KEY } }
  );
  
  const { balances } = await response.json();
  const currencyBalance = balances.find(b => b.currency === currency);
  
  return parseFloat(currencyBalance?.amount || '0') >= parseFloat(amount);
}

Best Practices

Balance Consistency: Balances may have a slight delay (a few seconds) after transactions complete due to blockchain confirmation times.

Caching: Balance queries can be cached for short periods (30-60 seconds) to reduce API calls. Use webhooks for real-time updates.

Next Steps

Pay-in to wallet POST

Get pay-in resources for crypto or fiat pay-ins

Create transfers for customer POST

Create crypto-to-crypto transfers between wallets

On this page