Skip to main content
The Spark Issuer SDK provides TypeScript support for building token issuance applications on Node.js and web browsers. This guide covers installation and basic setup. Before getting started, ensure you have Node.js (v16 or later) installed and a TypeScript development environment set up.

​
Getting Started

To get started, follow the steps below.
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: "optional-number",
    options: {
      network: "REGTEST",
    },
  });
  console.log("Wallet initialized successfully:", mnemonic);
3

Start Building

That’s it—you can now start using the Spark Issuer TypeScript SDK.
app.ts
import { SparkIssuer } from "@buildonspark/spark-sdk";

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

    console.log("Issuer created successfully!");
    console.log("Issuer address:", issuer.getAddress());

    // Example: Create a token
    const token = await issuer.createToken({
      name: "My Token",
      symbol: "MTK",
      decimals: 8,
      totalSupply: "1000000"
    });

    console.log("Token created:", token.tokenId);

    // Example: Mint tokens
    const mintResult = await issuer.mintToken({
      tokenId: token.tokenId,
      amount: "1000",
      recipient: "recipient-address"
    });

    console.log("Tokens minted:", mintResult.txid);
  } 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

An issuer 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 issuer instance
const issuer = await SparkIssuer.initialize({
  mnemonicOrSeed: "optional-mnemonic-or-seed",
  accountNumber: "optional-number",
  options: {
    network: "REGTEST" // or "MAINNET"
  }
});

console.log("Issuer initialized successfully");

​
Mnemonic Phrases

A mnemonic is a human-readable encoding of your issuer’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.

​
TypeScript Features

​
Type Safety

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

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

// All methods are fully typed
const address: string = issuer.getAddress();
const tokens: TokenInfo[] = await issuer.getTokens();

​
Interface Definitions

All issuer methods return properly typed interfaces: 
interface CreateTokenRequest {
  name: string;
  symbol: string;
  decimals: number;
  totalSupply: string;
  description?: string;
}

interface TokenInfo {
  tokenId: string;
  name: string;
  symbol: string;
  decimals: number;
  totalSupply: string;
  mintedSupply: string;
  issuer: string;
}

interface MintTokenRequest {
  tokenId: string;
  amount: string;
  recipient: string;
}

interface TransferTokenRequest {
  tokenId: string;
  amount: string;
  recipient: string;
}

​
Error Handling

The SDK provides typed error classes for better error handling: 
import { SparkIssuer, IssuerError } from "@buildonspark/spark-sdk";

try {
  const token = await issuer.createToken(tokenData);
} catch (error) {
  if (error instanceof IssuerError) {
    console.error('Issuer error:', error.message);
    console.error('Error code:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Advanced TypeScript Features

​
Generic Types

Use generic types for flexible token operations: 
interface TokenOperation<T> {
  tokenId: string;
  data: T;
}

const mintOperation: TokenOperation<MintTokenRequest> = {
  tokenId: "token-123",
  data: {
    amount: "1000",
    recipient: "recipient-address"
  }
};

​
Type Guards

Implement type guards for runtime type checking: 
function isTokenInfo(obj: any): obj is TokenInfo {
  return obj && 
    typeof obj.tokenId === 'string' &&
    typeof obj.name === 'string' &&
    typeof obj.symbol === 'string' &&
    typeof obj.decimals === 'number';
}

const tokens = await issuer.getTokens();
const validTokens = tokens.filter(isTokenInfo);

​
Custom Types

Define custom types for your application: 
type TokenStatus = 'active' | 'paused' | 'burned';

interface CustomTokenInfo extends TokenInfo {
  status: TokenStatus;
  createdAt: Date;
  lastMinted?: Date;
}

// Use in your application
const customToken: CustomTokenInfo = {
  ...tokenInfo,
  status: 'active',
  createdAt: new Date()
};

​
Best Practices

  • Use TypeScript strict mode for better type safety
  • Leverage IDE autocomplete for API methods and properties
  • Define custom interfaces for your application data
  • Use type guards for runtime type checking
  • Implement proper error handling with typed error classes
  • Use generic types for reusable components

​
Next Steps