> ## 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 Wallet Transaction History

> Retrieve paginated transaction history for credit, reward, or internal wallets

## Overview

Retrieve paginated transaction history for any wallet type. Returns up to 10 transactions per page, ordered by date descending (newest first). Supports credit, reward, and internal wallet types with filtering and pagination.

**Use Cases:**

* Display transaction history to users
* Generate transaction reports or statements
* Audit wallet activity
* Track deposits, withdrawals, and purchases
* Reconcile balances

## Authentication

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

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

## Query Parameters

<ParamField query="walletId" type="string" required>
  Wallet identifier obtained from wallet details endpoint (e.g., from GET /v1/wallet/credit, /v1/wallet/reward, or /v1/wallet/internal)
</ParamField>

<ParamField query="walletType" type="string" required>
  Type of wallet to query: `CREDIT`, `REWARD`, or `INTERNAL`
</ParamField>

<ParamField query="walletCurrency" type="string">
  Wallet currency (required only if walletType is `INTERNAL`). Examples: "usdc", "usdt", "xrp"
</ParamField>

<ParamField query="page" type="string">
  Page number for pagination, zero-indexed. Defaults to page 0 if omitted or invalid. Each page returns up to 10 transactions.
</ParamField>

<ParamField query="x-us-env" type="boolean" default={false}>
  Route to US backend environment
</ParamField>

## Response

Returns an array of transaction objects, up to 10 per page.

<ResponseField name="name" type="string">
  Transaction description (e.g., "Credit withdrawal", "Card purchase", "Deposit")
</ResponseField>

<ResponseField name="amount" type="string">
  Transaction amount (decimal string)
</ResponseField>

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

<ResponseField name="sign" type="string">
  Transaction direction: `"debit"` for outgoing, `"credit"` for incoming
</ResponseField>

<ResponseField name="date" type="string">
  ISO 8601 timestamp of the transaction
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "name": "Credit withdrawal",
      "amount": "10.00",
      "currency": "usdc",
      "sign": "debit",
      "date": "2024-02-02T15:01:09.091Z"
    },
    {
      "name": "Card purchase - Starbucks",
      "amount": "5.50",
      "currency": "usdc",
      "sign": "debit",
      "date": "2024-02-01T10:30:45.123Z"
    },
    {
      "name": "Deposit",
      "amount": "100.00",
      "currency": "usdc",
      "sign": "credit",
      "date": "2024-01-31T09:15:22.456Z"
    }
  ]
  ```

  ```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}
  # Credit wallet history
  curl -X GET "https://dev.api.baanx.com/v1/wallet/history?walletId=098aeb90-e7f7-4f81-bc2e-4963330122c5&walletType=CREDIT&page=0" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Internal wallet history (requires currency)
  curl -X GET "https://dev.api.baanx.com/v1/wallet/history?walletId=098aeb90-e7f7-4f81-bc2e-4963330122c5&walletType=INTERNAL&walletCurrency=usdc&page=0" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

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

  def get_wallet_history(wallet_id, wallet_type, page=0, currency=None):
      url = "https://dev.api.baanx.com/v1/wallet/history"
      headers = {
          "x-client-key": "YOUR_CLIENT_KEY",
          "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }

      params = {
          "walletId": wallet_id,
          "walletType": wallet_type,
          "page": str(page)
      }

      if wallet_type == "INTERNAL" and currency:
          params["walletCurrency"] = currency

      response = requests.get(url, headers=headers, params=params)
      return response.json()

  credit_history = get_wallet_history(
      "098aeb90-e7f7-4f81-bc2e-4963330122c5",
      "CREDIT",
      page=0
  )

  for tx in credit_history:
      sign_symbol = "-" if tx['sign'] == 'debit' else "+"
      print(f"{tx['date']}: {sign_symbol}{tx['amount']} {tx['currency']} - {tx['name']}")
  ```

  ```javascript JavaScript theme={null}
  async function getWalletHistory(walletId, walletType, page = 0, currency = null) {
    const params = new URLSearchParams({
      walletId,
      walletType,
      page: page.toString()
    });

    if (walletType === 'INTERNAL' && currency) {
      params.append('walletCurrency', currency);
    }

    const response = await fetch(
      `https://dev.api.baanx.com/v1/wallet/history?${params}`,
      {
        headers: {
          'x-client-key': 'YOUR_CLIENT_KEY',
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        }
      }
    );

    return await response.json();
  }

  const history = await getWalletHistory(
    '098aeb90-e7f7-4f81-bc2e-4963330122c5',
    'CREDIT',
    0
  );

  console.log(`Found ${history.length} transactions`);
  ```

  ```typescript TypeScript theme={null}
  interface Transaction {
    name: string;
    amount: string;
    currency: string;
    sign: 'debit' | 'credit';
    date: string;
  }

  type WalletType = 'CREDIT' | 'REWARD' | 'INTERNAL';

  async function getWalletHistory(
    walletId: string,
    walletType: WalletType,
    page: number = 0,
    currency?: string
  ): Promise<Transaction[]> {
    const params = new URLSearchParams({
      walletId,
      walletType,
      page: page.toString()
    });

    if (walletType === 'INTERNAL' && currency) {
      params.append('walletCurrency', currency);
    }

    const response = await fetch(
      `https://dev.api.baanx.com/v1/wallet/history?${params}`,
      {
        headers: {
          'x-client-key': 'YOUR_CLIENT_KEY',
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        }
      }
    );

    return await response.json();
  }
  ```
</CodeGroup>

## Pagination Example

```javascript Complete Pagination Implementation theme={null}
async function getAllTransactions(walletId, walletType) {
  let allTransactions = [];
  let page = 0;
  let hasMore = true;

  while (hasMore) {
    const transactions = await getWalletHistory(walletId, walletType, page);

    allTransactions = allTransactions.concat(transactions);

    hasMore = transactions.length === 10;
    page++;
  }

  return allTransactions;
}

const allTxs = await getAllTransactions(
  '098aeb90-e7f7-4f81-bc2e-4963330122c5',
  'CREDIT'
);

console.log(`Total transactions: ${allTxs.length}`);
```

## Integration Patterns

### Transaction Display with Formatting

```javascript theme={null}
function formatTransaction(tx) {
  const date = new Date(tx.date);
  const amount = parseFloat(tx.amount);
  const sign = tx.sign === 'debit' ? '-' : '+';

  return {
    date: date.toLocaleDateString(),
    time: date.toLocaleTimeString(),
    description: tx.name,
    amount: `${sign}$${amount.toFixed(2)}`,
    currency: tx.currency.toUpperCase(),
    type: tx.sign
  };
}

const history = await getWalletHistory(walletId, walletType);
const formatted = history.map(formatTransaction);
```

### Filter Transactions by Type

```javascript theme={null}
const history = await getWalletHistory(walletId, 'CREDIT');

const withdrawals = history.filter(tx =>
  tx.sign === 'debit' && tx.name.includes('withdrawal')
);

const deposits = history.filter(tx => tx.sign === 'credit');

const purchases = history.filter(tx =>
  tx.sign === 'debit' && tx.name.includes('purchase')
);
```

### Calculate Period Summary

```javascript theme={null}
function calculateSummary(transactions, startDate, endDate) {
  const start = new Date(startDate);
  const end = new Date(endDate);

  const filtered = transactions.filter(tx => {
    const txDate = new Date(tx.date);
    return txDate >= start && txDate <= end;
  });

  const totalDebits = filtered
    .filter(tx => tx.sign === 'debit')
    .reduce((sum, tx) => sum + parseFloat(tx.amount), 0);

  const totalCredits = filtered
    .filter(tx => tx.sign === 'credit')
    .reduce((sum, tx) => sum + parseFloat(tx.amount), 0);

  return {
    period: `${startDate} to ${endDate}`,
    transactionCount: filtered.length,
    totalIn: totalCredits,
    totalOut: totalDebits,
    net: totalCredits - totalDebits
  };
}
```

## Important Notes

<Note>
  **Page Size**: Each page returns up to 10 transactions. If a page has fewer than 10 transactions, you've reached the end of the history.
</Note>

<Tip>
  **Zero-Indexed Pagination**: Page numbers start at 0. First page is `page=0`, second page is `page=1`, etc.
</Tip>

<Warning>
  **Internal Wallet Currency**: When querying history for `INTERNAL` wallet type, you must provide the `walletCurrency` parameter. Omitting it will result in an error.
</Warning>

## Edge Cases

### Empty History

A wallet with no transactions returns an empty array:

```json theme={null}
[]
```

### Invalid Page Numbers

Invalid or out-of-range page numbers default to page 0:

```javascript theme={null}
/wallet/history?walletId=xxx&walletType=CREDIT&page=-1
/wallet/history?walletId=xxx&walletType=CREDIT&page=abc
```

### Transaction Ordering

Transactions are always ordered by date descending (newest first). To get oldest first, reverse the array:

```javascript theme={null}
const history = await getWalletHistory(walletId, walletType);
const oldestFirst = history.reverse();
```

### Large History Sets

For wallets with thousands of transactions:

* Implement efficient pagination with loading indicators
* Cache historical data client-side
* Consider date range filters for performance
* Lazy-load transactions as user scrolls

## Related Endpoints

* [Get Credit Wallet](/api-reference/wallet/credit) - Get credit wallet details and ID
* [Get Reward Wallet](/api-reference/wallet/reward) - Get reward wallet details and ID
* [Get Internal Wallets](/api-reference/wallet/internal) - Get internal wallet details and ID