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

# Transaction History — Node.js

> Paginate a wallet's transaction history, filter by date, and stamp external transaction hashes into Chipi's records.

Transactions executed through the SDK (`transfer`, `purchaseSku`, `executeTransactionWithSession`, etc.) are automatically recorded against the wallet. This page covers reading that history and recording transactions executed outside the SDK.

## List transactions

`getTransactionList` returns a paginated history of transactions for a wallet. `walletAddress` is required; everything else is optional.

```ts theme={null}
const result = await sdk.getTransactionList({
  walletAddress: "0x...",
  page: 1,
  limit: 20,
});

console.log(result.total);                  // total transactions for this wallet
console.log(result.totalPages);
console.log(result.data[0].transactionHash);
```

The response shape is `PaginatedResponse<Transaction>`:

```ts theme={null}
{
  data: Transaction[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}
```

## Filter by date

`year`, `month`, and `day` narrow the list to a specific calendar window. Useful for monthly reports or per-day audits.

```ts theme={null}
const now = new Date();

// All transactions in the current month
const thisMonth = await sdk.getTransactionList({
  walletAddress: userWallet.publicKey,
  year: now.getFullYear(),
  month: now.getMonth() + 1, // 1-12, JS Date months are 0-indexed
  page: 1,
  limit: 100,
});

// All transactions on a specific day
const oneDay = await sdk.getTransactionList({
  walletAddress: userWallet.publicKey,
  year: 2026,
  month: 5,
  day: 7,
});
```

You can also filter by the called function with `calledFunction` (e.g., `"transfer"`, `"approve"`).

## Record an external transaction

`recordSendTransaction` stamps a transaction that was **executed outside** the SDK into Chipi's records. Use it when a wallet sent a transfer through some other path (a wallet UI, another service) and you want it to show up in `getTransactionList` and the dashboard.

```ts theme={null}
import { Chain, ChainToken } from "@chipi-stack/backend";

const result = await sdk.recordSendTransaction({
  params: {
    transactionHash: "0x...",                        // the on-chain tx hash
    expectedSender: senderPublicKey,
    expectedRecipient: recipientPublicKey,
    expectedToken: ChainToken.USDC,
    expectedAmount: "1.5",                           // human-formatted decimal string
    chain: Chain.STARKNET,
  },
});
```

`expectedAmount` is a **decimal string in human units** (e.g., `"1.5"` for 1.5 USDC), not raw token units — different from `getTokenBalance.balance` which returns raw units.

The endpoint validates the on-chain `Transfer` event matches your `expected*` fields. If the tx hash isn't yet confirmed, or the actual transfer doesn't match what you claimed, the call rejects.

## Putting it together

A monthly statement endpoint for a user's gasless wallet:

```ts theme={null}
import { ChipiServerSDK } from "@chipi-stack/backend";

async function monthlyStatement(
  sdk: ChipiServerSDK,
  walletAddress: string,
  year: number,
  month: number,
) {
  const all: Awaited<ReturnType<typeof sdk.getTransactionList>>["data"] = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const r = await sdk.getTransactionList({
      walletAddress,
      year,
      month,
      page,
      limit: 100,
    });
    all.push(...r.data);
    totalPages = r.totalPages;
    page++;
  }

  return { walletAddress, year, month, count: all.length, transactions: all };
}
```

> ✅ Verified against the live API on **2026-05-11**.