> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Reward Wallet Balance

> Retrieve the authenticated user's reward wallet balance and details

## 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

<ParamField header="x-client-key" type="string" required>
  Your public API client key that identifies your environment
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from OAuth flow or direct login
</ParamField>

## Query Parameters

<ParamField query="x-us-env" type="boolean" default={false}>
  Set to `true` to route request to US backend environment (if available for your client)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the reward wallet
</ResponseField>

<ResponseField name="balance" type="string">
  Current balance in the wallet (decimal string for precision)
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (e.g., "usdc", "usdt")
</ResponseField>

<ResponseField name="isWithdrawable" type="boolean">
  Whether funds can be withdrawn from this wallet
</ResponseField>

<ResponseField name="type" type="string">
  Wallet type identifier, always "REWARD" for this endpoint
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "098aeb90-e7f7-4f81-bc2e-4963330122c5",
    "balance": "45.75",
    "currency": "usdc",
    "isWithdrawable": true,
    "type": "REWARD"
  }
  ```

  ```json 401 - Authentication Error theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Authorization Error theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/wallet/reward" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  url = "https://dev.api.baanx.com/v1/wallet/reward"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }

  response = requests.get(url, headers=headers)
  reward_wallet = response.json()

  print(f"Rewards Balance: {reward_wallet['balance']} {reward_wallet['currency']}")
  print(f"Withdrawable: {reward_wallet['isWithdrawable']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://dev.api.baanx.com/v1/wallet/reward', {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  const rewardWallet = await response.json();
  console.log(`Rewards: ${rewardWallet.balance} ${rewardWallet.currency}`);
  ```

  ```typescript TypeScript theme={null}
  interface RewardWallet {
    id: string;
    balance: string;
    currency: string;
    isWithdrawable: boolean;
    type: 'REWARD';
  }

  const response = await fetch('https://dev.api.baanx.com/v1/wallet/reward', {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  const rewardWallet: RewardWallet = await response.json();
  ```
</CodeGroup>

## Integration Patterns

### Display Rewards Dashboard

```javascript theme={null}
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

```javascript theme={null}
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

<Note>
  **Balance Precision**: Balances are returned as strings to maintain precision for decimal values. Always parse as decimal types in your application.
</Note>

<Tip>
  **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.
</Tip>

<Warning>
  **Withdrawal Restrictions**: Some reward programs may have vesting periods, minimum balance requirements, or other restrictions. Always check `isWithdrawable` before attempting withdrawals.
</Warning>

## 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:

```javascript theme={null}
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:

```javascript theme={null}
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;
}
```

## Related Endpoints

* [Withdraw from Reward Wallet](/api-reference/wallet/reward-withdraw) - Initiate withdrawal to external wallet
* [Estimate Reward Withdrawal Fees](/api-reference/wallet/reward-withdraw-estimation) - Calculate network fees before withdrawal
* [Get Wallet History](/api-reference/wallet/history) - View reward transaction history