Skip to main content
GET
/
v1
/
wallet
/
reward
Get Reward Wallet Balance
curl --request GET \
  --url https://api.example.com/v1/wallet/reward \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'
{
  "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
  "balance": "45.75",
  "currency": "usdc",
  "isWithdrawable": true,
  "type": "REWARD"
}

​
Overview

Reward wallets accumulate platform incentives, cashback earnings, and promotional credits. This endpoint retrieves the current balance, currency, and withdrawal status of the authenticated user’s reward wallet. Balance updates reflect earned rewards, redemptions, and withdrawals. Use Cases:
  • Display user’s accumulated rewards in your application
  • Show available rewards before redemption or withdrawal
  • Track reward earnings over time
  • Verify reward wallet status for promotional campaigns
Reward Types:
  • Transaction cashback (percentage back on card purchases)
  • Referral bonuses
  • Platform incentives and promotions
  • Loyalty rewards
  • Staking rewards

​
Authentication

​
x-client-key
string
required
Your public API client key that identifies your environment
​
Authorization
string
required
Bearer token obtained from OAuth flow or direct login

​
Query Parameters

​
x-us-env
boolean
default:false
Set to true to route request to US backend environment (if available for your client)

​
Response

​
id
string
Unique identifier for the reward wallet
​
balance
string
Current balance in the wallet (decimal string for precision)
​
currency
string
Currency code (e.g., “usdc”, “usdt”)
​
isWithdrawable
boolean
Whether funds can be withdrawn from this wallet
​
type
string
Wallet type identifier, always “REWARD” for this endpoint
{
  "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
  "balance": "45.75",
  "currency": "usdc",
  "isWithdrawable": true,
  "type": "REWARD"
}

​
Code Examples

curl -X GET "https://dev.api.baanx.com/v1/wallet/reward" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Integration Patterns

​
Display Rewards Dashboard

async function getRewardsSummary() {
  const response = await fetch('/v1/wallet/reward', {
    headers: {
      'x-client-key': CLIENT_KEY,
      'Authorization': `Bearer ${accessToken}`
    }
  });

  const wallet = await response.json();

  return {
    totalRewards: parseFloat(wallet.balance),
    currency: wallet.currency.toUpperCase(),
    canWithdraw: wallet.isWithdrawable,
    displayText: `${wallet.balance} ${wallet.currency.toUpperCase()}`
  };
}

​
Check Withdrawal Eligibility

async function canWithdrawRewards() {
  const wallet = await fetch('/v1/wallet/reward').then(r => r.json());

  const minWithdrawal = 1.0;
  const balance = parseFloat(wallet.balance);

  if (!wallet.isWithdrawable) {
    return { eligible: false, reason: 'Withdrawals not enabled' };
  }

  if (balance < minWithdrawal) {
    return {
      eligible: false,
      reason: `Minimum withdrawal is ${minWithdrawal} ${wallet.currency}`
    };
  }

  return { eligible: true, balance, currency: wallet.currency };
}

​
Important Notes

Balance Precision: Balances are returned as strings to maintain precision for decimal values. Always parse as decimal types in your application.
Real-Time Updates: Reward balances update in real-time as users earn rewards through transactions, referrals, or platform activities. Consider implementing webhooks or periodic polling for live balance updates.
Withdrawal Restrictions: Some reward programs may have vesting periods, minimum balance requirements, or other restrictions. Always check isWithdrawable before attempting withdrawals.

​
Edge Cases

​
Pending Rewards

Some rewards may have confirmation delays:
  • Transaction cashback typically credits within 24-48 hours
  • Referral bonuses may require referred user to complete verification
  • Promotional rewards may vest over time

​
Minimum Balance

Platform may enforce minimum balances: 
const MIN_REWARD_BALANCE = 0.01;

if (parseFloat(wallet.balance) < MIN_REWARD_BALANCE) {
  console.log('Reward balance too low to display');
}

​
Currency Variations

Rewards may be in different currencies: 
async function getTotalRewardsUSD() {
  const wallet = await fetch('/v1/wallet/reward').then(r => r.json());

  if (wallet.currency === 'usdc' || wallet.currency === 'usdt') {
    return parseFloat(wallet.balance);
  }

  const rate = await getExchangeRate(wallet.currency, 'USD');
  return parseFloat(wallet.balance) * rate;
}