Skip to main content

​
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:
ModeAuthUse case
PublicNoneDashboards, explorers, analytics. Query any non-private wallet
Master KeyIdentity keyQuery private wallets you own without full wallet initialization
Custom SignerIdentity key via signerPartners (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

​
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.

​
API Reference

See the full method reference at Wallet Viewer API.