Wallet Viewer

Query wallet data without signing keys using the SparkReadonlyClient

Overview

The SparkReadonlyClient lets you query wallet data without creating a full SparkWallet. It exposes read-only methods for balances, transfers, deposits, invoices, and token transactions.

Three use cases:

Mode	Auth	Use case
Public	None	Dashboards, explorers, analytics. Query any non-private wallet
Master Key	Identity key	Query private wallets you own without full wallet initialization
Custom Signer	Identity key via signer	Partners (e.g., Privy) passing in a signer without a mnemonic

---

Installation

The wallet viewer ships with the standard SDK package.

npm

npm install @buildonspark/spark-sdk

---

Create a Public Client

No authentication. Queries public (non-private) wallet data.

import { SparkReadonlyClient } from "@buildonspark/spark-sdk";

const client = SparkReadonlyClient.createPublic({
  network: "MAINNET",
});

const balance = await client.getAvailableBalance("sp1...");
console.log("Balance:", balance, "sats");

Public clients can query any wallet that hasn’t enabled privacy mode. Private wallets return empty results, not errors.

---

Create with Master Key

Authenticates with an identity key derived from a mnemonic or seed. Can query private wallets the key owns.

import { SparkReadonlyClient } from "@buildonspark/spark-sdk";

const client = await SparkReadonlyClient.createWithMasterKey(
  { network: "MAINNET" },
  "your twelve word mnemonic phrase here ...",
);

// Can see private wallet data
const balance = await client.getAvailableBalance("sp1...");
const tokens = await client.getTokenBalance("sp1...");

---

Create with Custom Signer

For integrations where a partner provides a SparkSigner implementation instead of a mnemonic.

import { SparkReadonlyClient } from "@buildonspark/spark-sdk";

const client = SparkReadonlyClient.createWithSigner(
  { network: "MAINNET" },
  myCustomSigner,
);

---

Query Examples

Balances

// Bitcoin balance
const sats = await client.getAvailableBalance("sp1...");

// Token balances (all tokens)
const tokenBalances = await client.getTokenBalance("sp1...");
for (const [tokenId, info] of tokenBalances) {
  console.log(`${info.tokenMetadata.tokenTicker}: ${info.availableToSendBalance}`);
}

// Token balances (specific tokens)
const filtered = await client.getTokenBalance("sp1...", ["btkn1..."]);

Transfers

// Paginated transfer history
const { transfers, offset } = await client.getTransfers({
  sparkAddress: "sp1...",
  limit: 25,
  offset: 0,
});

// Transfers from last 24 hours
const recent = await client.getTransfers({
  sparkAddress: "sp1...",
  createdAfter: new Date(Date.now() - 86_400_000),
});

// Specific transfers by ID
const specific = await client.getTransfersByIds(["transfer-id-1", "transfer-id-2"]);

// Pending inbound transfers
const pending = await client.getPendingTransfers("sp1...");

Deposits and UTXOs

// Unused deposit addresses
const { depositAddresses } = await client.getUnusedDepositAddresses({
  sparkAddress: "sp1...",
});

// Static deposit addresses
const staticAddrs = await client.getStaticDepositAddresses("sp1...");

// UTXOs for a specific deposit address
const { utxos } = await client.getUtxosForDepositAddress({
  depositAddress: "bc1...",
});

Invoices and Token Transactions

// Invoice statuses
const { invoiceStatuses } = await client.getSparkInvoices({
  invoices: ["spark1..."],
});

// Token transactions with cursor pagination
const page = await client.getTokenTransactions({
  sparkAddresses: ["sp1..."],
  pageSize: 25,
});

if (page.pageResponse?.nextCursor) {
  const next = await client.getTokenTransactions({
    sparkAddresses: ["sp1..."],
    cursor: page.pageResponse.nextCursor,
    direction: "NEXT",
  });
}

---

Privacy Model

The wallet viewer respects privacy mode:

• Privacy off (default): Both public and authenticated clients see all data.
• Privacy on: Public clients get empty results. Authenticated clients (master key / signer) see everything.

The distinction is server-side. When a wallet has privacy enabled, unauthenticated requests return zero balances and empty arrays, not errors.

If you need visibility into private wallets without full wallet initialization, use createWithMasterKey(). For event-driven notifications (push notifications, payment alerts) without needing read access, see webhooks.

---

API Reference

See the full method reference at Wallet Viewer API.