Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spark.money/llms.txt

Use this file to discover all available pages before exploring further.

TypeScript SDK for issuing and managing tokens on Spark. 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 Issuer SDK packages using your package manager of choice.
npm install @buildonspark/issuer-sdk
2

Setup Issuer

Create an issuer instance that will be used to interact with the Spark network.
issuer.ts
  import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

  const { wallet, mnemonic } = await IssuerSparkWallet.initialize({
    mnemonicOrSeed: "optional-mnemonic-or-seed",
    accountNumber: 0, // optional
    options: {
      network: "REGTEST",
    },
  });
  console.log("Wallet initialized successfully:", mnemonic);
3

Start Building

You’re ready to start building.
app.ts
import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

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

    console.log("Issuer wallet created!");
    console.log("Address:", await wallet.getSparkAddress());

    // Create a token
    const { tokenIdentifier, transactionHash } = await wallet.createToken({
      tokenName: "My Token",
      tokenTicker: "MTK",
      decimals: 8,
      maxSupply: BigInt(21000000_00000000), // 21M tokens (with 8 decimals)
      isFreezable: false,
      returnIdentifierForCreate: true,
    });

    console.log("Token created:", tokenIdentifier);
    console.log("Announcement tx:", transactionHash);

    // Mint tokens to yourself
    const mintTxId = await wallet.mintTokens({
      tokenIdentifier,
      tokenAmount: BigInt(1000_00000000), // 1000 tokens (with 8 decimals)
    });
    console.log("Tokens minted:", mintTxId);
  } 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 Issuer Operations

​
Initialize an Issuer Wallet

An issuer 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. 
import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

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

console.log("Issuer wallet initialized:", 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 issuer wallet.

​
TypeScript Features

​
Type Safety

The Spark Issuer TypeScript SDK provides full type safety for all issuer operations: 
import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

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

// All methods are fully typed
const address: string = await wallet.getSparkAddress();
const tokensMetadata = await wallet.getIssuerTokensMetadata();
const tokenIdentifiers = await wallet.getIssuerTokenIdentifiers();

​
Interface Definitions

Key interfaces used by the Issuer SDK: 
// Token creation parameters
interface CreateTokenParams {
  tokenName: string;
  tokenTicker: string;
  decimals: number;
  isFreezable: boolean;
  maxSupply?: bigint; // defaults to 0n (unlimited)
  extraMetadata?: Uint8Array;
  returnIdentifierForCreate?: boolean;
}

// Token metadata returned by getIssuerTokensMetadata()
interface IssuerTokenMetadata {
  rawTokenIdentifier: Uint8Array;
  tokenPublicKey: string;
  tokenName: string;
  tokenTicker: string;
  decimals: number;
  maxSupply: bigint;
  isFreezable: boolean;
  extraMetadata?: Uint8Array;
  bech32mTokenIdentifier: Bech32mTokenIdentifier;
}

// Token distribution stats
interface TokenDistribution {
  totalCirculatingSupply: bigint;
  totalIssued: bigint;
  totalBurned: bigint;
  numHoldingAddress: number;
  numConfirmedTransactions: bigint;
}

​
Error Handling

The SDK provides typed error classes for better error handling: 
import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";
import { SparkError, SparkValidationError } from "@buildonspark/spark-sdk";

const { wallet } = await IssuerSparkWallet.initialize({
  options: { network: "REGTEST" },
});

try {
  await wallet.createToken({
    tokenName: "My Token",
    tokenTicker: "MTK",
    decimals: 8,
    maxSupply: BigInt(21000000_00000000),
    isFreezable: false
  });
} catch (error) {
  if (error instanceof SparkValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof SparkError) {
    console.error('SDK error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}