> For the complete documentation index, see [llms.txt](https://emeditweb.gitbook.io/pulsar-stellar-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emeditweb.gitbook.io/pulsar-stellar-sdk/guides.md).

# Guides

## Tracking Balances with Transfer Events

This guide demonstrates how to compute a running balance by tracking `transfer` events for a specific user using the Indexer path.

Because Soroban emits events even for contract calls that revert, a naïve sum of transfer amounts would be incorrect. This guide highlights checking `inSuccessfulContractCall` to only tally transfers that actually settled. It also uses the `asTransferEvent()` helper to ergonomically access the event data.

### Example: Computing a Running Balance

```typescript
import { PulsarClient, asTransferEvent } from '@pulsar-stellar/sdk';

async function calculateRunningBalance(
  contractId: string,
  userAddress: string
): Promise<bigint> {
  const client = new PulsarClient({
    // <!-- VERIFY --> Replace with actual hosted indexer URL once available
    indexerUrl: 'https://indexer.example.com',
  });

  let balance = 0n;

  // We filter specifically for the 'transfer' event using the `name` query parameter.
  // The eventStream handles pagination under the hood.
  const stream = client.eventStream(contractId, { name: 'transfer' });

  for await (const decodedEvent of stream) {
    // 1. MUST verify the contract call actually succeeded.
    // Reverted calls can still emit events!
    if (!decodedEvent.inSuccessfulContractCall) {
      continue;
    }

    // 2. Map the wire-faithful event to the expected Transfer shape
    const transfer = asTransferEvent(decodedEvent);
    if (!transfer) {
      continue;
    }

    const { from, to, amount } = transfer.data;

    // 3. Apply the transfer amount to the user's running balance
    if (to === userAddress) {
      balance += amount;
    } 
    if (from === userAddress) {
      balance -= amount;
    }
  }

  return balance;
}

// Usage:
// calculateRunningBalance('CDNW...', 'GCQU...').then(console.log);
```

### Key Takeaways

1. **`inSuccessfulContractCall`**: Always check this flag when deriving state from events.
2. **`asTransferEvent`**: The SDK's bridge helpers ensure you're safely reading the wire format (e.g., pulling the `from` and `to` from the event topics and the `amount` from the data) into a strongly typed, easy-to-use TypeScript object.
3. **`BigInt`**: Wide integers like `amount` (which is an `i128` in Rust) are mapped to `bigint` in TypeScript by the bridge helper, preventing precision loss.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://emeditweb.gitbook.io/pulsar-stellar-sdk/guides.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.