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.

1. Install SDK

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

   npm

   npm install @buildonspark/spark-sdk
   
2. 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;
   };
   
3. 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