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

# Optional indexing

> Opt into hosted history, discovery, and prices, or use your own backend.

## Opt in explicitly

Indexing is **off by default**. Enable it for history, discovery, and prices. Chain operations and Lightning encryption/attestations work independently.

```ts theme={null}
// Default: on-chain features, no indexer requests.
const ctoken = new CTokenClient({ network: "baseSepolia", publicClient, walletClient });

// Opt in to Inco's hosted Base Sepolia service.
const withHistory = new CTokenClient({
  network: "baseSepolia", publicClient, walletClient, indexer: true,
});

// Opt in to your compatible service. The URL is a base prefix, not a route.
const custom = new CTokenClient({
  network: "baseSepolia", publicClient, walletClient,
  indexer: { url: "https://your-indexer.example/api", timeoutMs: 15_000 },
});
```

```tsx theme={null}
<CTokenProvider network="baseSepolia" publicClient={publicClient} indexer>
  <ConfidentialWallet />
</CTokenProvider>

<CTokenProvider network="baseSepolia" publicClient={publicClient}
  indexer={{ url: "https://your-indexer.example/api" }}>
  <ConfidentialWallet />
</CTokenProvider>
```

`false`/omitted: off. `true`/`{}`: hosted service for the selected network. `{ url }`: your compatible service.

When off, widgets hide history/discovery and retain configured tokens and chain balances. History/assets hooks do not auto-fetch; direct calls and manual refetches raise `INDEXER_NOT_CONFIGURED`. Custom UI can check `Boolean(useCToken().context.indexerUrl)`.

## Three HTTP-backed methods

| SDK call | HTTP request | Defaults |
| - | - | - |
| `history({ address?, page?, limit?, signal? })` | GET `/wallets/:address/transactions` | Current owner, page 1, limit 10; integer limit 1–100. |
| `assets({ address?, signal? })` | GET `/wallets/:address/assets` | Current owner; unpaginated. |
| `prices(tokens?, { signal }?)` | GET `/prices?tokens=...` | Empty/omitted tokens means the indexer's available priced set; at most 200 input addresses. |

An explicit address allows history/assets without a wallet. Missing prices remain absent, never zero.

```ts theme={null}
const controller = new AbortController();
const page = await ctoken.history({
  address: owner, page: 2, limit: 20, signal: controller.signal,
});
const prices = await ctoken.prices([USDC], { signal: controller.signal });
const usd = prices.prices[USDC.toLowerCase()]?.usd;
// controller.abort() cancels outstanding requests using this signal.
```

## Asset

| Field | Type | Meaning |
| - | - | - |
| `address` | string address | cToken contract. |
| `base_erc20` | string address | Underlying token. |
| `name`, `symbol` | string | Indexed wrapper metadata. |
| `decimals` | number | Token precision. |
| `balance_handle` | 32-byte hex or null | Encrypted balance handle; not a plaintext balance. |
| `handle_block` | string or null | Block associated with handle update. |
| `last_activity_block` | string | Most recent indexed activity. |

Indexed holdings do not prove a spendable balance. Read and decrypt chain state for exact amounts.

## Tx and TxPage

```ts theme={null}
type TxPage = {
  items: Tx[];
  total: number;
  page: number;
  pages: number;
  limit: number;
};

type Tx = {
  type: "transfer" | "flow";
  token: string;             // cToken
  symbol: string;
  decimals: number;
  kind: string;
  from_addr: string | null;
  to_addr: string | null;
  handle: string | null;
  amount: string | null;     // integer base units, public flow only
  block_number: string;
  block_time?: string;      // Unix seconds; raw API null becomes undefined
  log_index?: number;
  tx_hash: string;
};
```

Transfers expose handles with null amounts; flows expose base-unit amount strings. History excludes zero-address confidential mint/burn legs and public `burn` rows, ordered by descending block/log index.

## Prices

```ts theme={null}
type Prices = {
  chainId: number;
  ttl: number;               // seconds
  count: number;
  prices: Record<string, {
    usd: number;
    confidence: number | null;
    source: string;
    updated_at: number;     // Unix seconds
    stale: boolean;
  }>;
};
```

Display the `stale` flag. Missing quotes are unknown. Keys are lowercase underlying addresses; testnet assets may use mainnet price references.

<Card title="Build a compatible indexer" icon="server" href="/ctoken/custom-indexer">Implement the three SDK routes with the exact schemas and pagination rules.</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.