TypeScript SDK

TypeScript SDK for building Bitcoin wallet applications on Node.js and browsers. Requires Node.js v18+.

Getting Started

To get started, follow the steps below.

Want to skip the manual setup? Scaffold a new project instantly:

npx @buildonspark/create-spark-app my-app

Supports React (Vite), Next.js, React Native, Expo, Express, and more.

Install SDK

Install the Spark SDK packages using your package manager of choice.

npm install @buildonspark/spark-sdk

yarn add @buildonspark/spark-sdk

pnpm add @buildonspark/spark-sdk

Setup Wallet

Create a wallet instance that will be used to interact with the Spark network.

wallet.ts

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

export const initializeWallet = async () => {
  const { wallet, mnemonic } = await SparkWallet.initialize({
    mnemonicOrSeed: "optional-mnemonic-or-seed",
    accountNumber: 0, // optional
    options: {
      network: "REGTEST" // or "MAINNET"
    }
  });

  console.log("Wallet initialized successfully:", mnemonic);
  return wallet;
};

Start Building

You’re ready to start building.

app.ts

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

async function main() {
  try {
    // Initialize wallet
    const { wallet, mnemonic } = await SparkWallet.initialize({
      options: { network: "REGTEST" }
    });

    console.log("Wallet created successfully!");
    console.log("Mnemonic:", mnemonic);
    console.log("Address:", await wallet.getSparkAddress());
    
    const { balance } = await wallet.getBalance();
    console.log("Balance:", balance, "sats");

    // Example: Send Bitcoin
    const transfer = await wallet.transfer({
      receiverSparkAddress: "spark1...",
      amountSats: 1000,
    });

    console.log("Transfer completed:", transfer.id);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

TypeScript Configuration

tsconfig.json

Create a tsconfig.json file in your project root:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Package.json Scripts

Add TypeScript build scripts to your package.json:

package.json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/app.js",
    "dev": "ts-node src/app.ts",
    "watch": "tsc --watch"
  }
}

Core Wallet Operations

Initialize a Wallet

A wallet requires either a mnemonic or raw seed for initialization. The initialize() function accepts both. If no input is given, it will auto-generate a mnemonic and return it.

// Initialize a new wallet instance
const { wallet, mnemonic } = await SparkWallet.initialize({
  mnemonicOrSeed: "optional-mnemonic-or-seed",
  accountNumber: 0, // optional
  options: {
    network: "REGTEST" // or "MAINNET"
  }
});

console.log("Wallet initialized successfully:", mnemonic);

Mnemonic Phrases

A mnemonic is a human-readable encoding of your wallet’s seed. It’s a 12- or 24-word phrase from the BIP-39 wordlist, used to derive the cryptographic keys that control your wallet.

TypeScript Features

Type Safety

The Spark TypeScript SDK provides full type safety for all wallet operations:

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

// TypeScript will provide autocomplete and type checking
const { wallet } = await SparkWallet.initialize({
  options: { network: "REGTEST" }
});

// All methods are fully typed
const address: string = await wallet.getSparkAddress();
const { balance, tokenBalances } = await wallet.getBalance();
// balance: bigint (satoshis)
// tokenBalances: Map<Bech32mTokenIdentifier, { ownedBalance: bigint, availableToSendBalance: bigint, tokenMetadata }>

Interface Definitions

All wallet methods return properly typed interfaces:

interface InitResult {
  wallet: SparkWallet;
  mnemonic?: string; // undefined if raw seed was provided
}

interface BalanceResult {
  balance: bigint;
  tokenBalances: Map<string, { ownedBalance: bigint; availableToSendBalance: bigint; tokenMetadata: UserTokenMetadata }>;
}

interface WalletTransfer {
  id: string;
  senderIdentityPublicKey: string;
  receiverIdentityPublicKey: string;
  status: TransferStatus; // See TransferStatus enum below
  totalValue: number;
  expiryTime: Date | undefined;
  leaves: WalletTransferLeaf[];
  createdTime: Date | undefined;
  updatedTime: Date | undefined;
  type: TransferType; // "TRANSFER" | "COOPERATIVE_EXIT" | "PREIMAGE_SWAP" | "UTXO_SWAP"
  transferDirection: "INCOMING" | "OUTGOING";
  userRequest: UserRequestType | undefined;
  sparkInvoice: string | undefined; // Spark invoice associated with this transfer
}

// Common status values you'll encounter:
type TransferStatus =
  | "TRANSFER_STATUS_COMPLETED"
  | "TRANSFER_STATUS_EXPIRED"
  | "TRANSFER_STATUS_RETURNED"
  | "TRANSFER_STATUS_SENDER_INITIATED"
  // ... and other intermediate states

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

TypeScript SDK

Getting Started

TypeScript Configuration

tsconfig.json

Package.json Scripts

Core Wallet Operations

Initialize a Wallet

Mnemonic Phrases

TypeScript Features

Type Safety

Interface Definitions

​Getting Started

​TypeScript Configuration

​tsconfig.json

​Package.json Scripts

​Core Wallet Operations

​Initialize a Wallet

​Mnemonic Phrases

​TypeScript Features

​Type Safety

​Interface Definitions

Getting Started

TypeScript Configuration

tsconfig.json

Package.json Scripts

Core Wallet Operations

Initialize a Wallet

Mnemonic Phrases

TypeScript Features

Type Safety

Interface Definitions