Wallet Viewer

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
Viewer Key	Owner identity or authorized viewer identity	Query a private wallet without running a full wallet
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 install @buildonspark/spark-sdk

yarn add @buildonspark/spark-sdk

pnpm add @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. Bitcoin balance and wallet-history queries return empty results when read access is denied. This does not suppress authentication or network errors.

Create with Viewer Key

Authenticates with an identity key derived from a mnemonic or seed. For a separate service identity, the wallet owner must first grant that key access with setViewerIdentityPublicKey(). Follow the grant and revoke flow. Keep the viewer mnemonic separate from the owner’s wallet mnemonic.

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

const client = await SparkReadonlyClient.createWithViewerKey(
  { network: "MAINNET" },
  viewerMnemonic,
);

// Query a wallet that authorized this viewer identity.
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

New wallets are public by default. With privacy enabled, Bitcoin balance and wallet-history queries require the owner’s identity or the single viewer identity authorized by the owner. An unrelated authenticated client has no more access than a public client. Denied reads return zero balances or empty lists, so the response cannot tell you whether the wallet is empty or access is missing. Token activity remains public. See Privacy Mode for the scope of the setting and transfer-ID lookup considerations.

Events and client boundaries

SparkReadonlyClient queries data. It does not claim transfers, optimize wallet outputs, or expose a public event-stream subscription method in SDK 0.12.1. Use polling for a viewer, SparkWallet events for an active wallet, or webhooks for request outcomes. The protected connectionManager is not a supported subscription API. Public-client credentials cannot authenticate an operator event stream; a low-level attempt can fail with UNAUTHENTICATED, including an invalid-token-encoding message. Do not use that path to test whether a user granted read access.

Transfer objects differ from the wallet API

	`SparkWallet.getTransfers()`	`SparkReadonlyClient.getTransfers()`
Result objects	`WalletTransfer`	Protobuf `Transfer`
Enums	Strings such as `"PREIMAGE_SWAP"`	Numeric values from the protobuf enums
Wallet perspective	`transferDirection`, `valueReceivedByWallet`	Derive from participants and leaves

Do not pass viewer results directly to code expecting WalletTransfer. For raw transfers, use senders[], receivers[], and the relevant leaf values. Import enum definitions from @buildonspark/spark-sdk/proto/spark instead of hard-coding numeric values. Token history also has a different result shape: the viewer returns transactions, while queryTokenTransactionsWithFilters() returns tokenTransactionsWithStatus. Both use cursors. The viewer does not expose the wallet’s queryTokenTransactionsByTxHashes() method. To determine send versus receive, inspect the transaction’s inputs and outputs relative to the wallet; appearing in its history does not establish direction.

API Reference

See the full method reference at Wallet Viewer API.

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

Wallet Viewer

Overview

Installation

Create a Public Client

Create with Viewer Key

Create with Custom Signer

Query Examples

Balances

Transfers

Deposits and UTXOs

Invoices and Token Transactions

Privacy Model

Events and client boundaries

Transfer objects differ from the wallet API

API Reference

​Overview

​Installation

​Create a Public Client

​Create with Viewer Key

​Create with Custom Signer

​Query Examples

​Balances

​Transfers

​Deposits and UTXOs

​Invoices and Token Transactions

​Privacy Model

​Events and client boundaries

​Transfer objects differ from the wallet API

​API Reference

Overview

Installation

Create a Public Client

Create with Viewer Key

Create with Custom Signer

Query Examples

Balances

Transfers

Deposits and UTXOs

Invoices and Token Transactions

Privacy Model

Events and client boundaries

Transfer objects differ from the wallet API

API Reference