React Native SDK

React Native SDK for iOS and Android wallet apps. Requires Xcode/iOS Simulator or Android Studio.

Requirements: React >=18.2.0, React Native >=0.71.0, iOS >=12.0

Example App

Complete React Native example with wallet, transfers, and Lightning

Getting Started

To get started, follow the steps below.

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

Add Required Polyfills

Install the required polyfills for React Native compatibility.

npm install react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding

yarn add react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding

pnpm add react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding

Import Polyfills at App Entry

Critical: Import polyfills at the very top of your index.js file, BEFORE importing your app or any other modules. The crypto module will fail to load if this order is wrong.

index.js

// These MUST be the first imports in your app entry point
import 'react-native-get-random-values';
import '@azure/core-asynciterator-polyfill';
import { Buffer } from 'buffer';
global.Buffer = Buffer;

// Now import your app
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

Install Native Modules (iOS)

For iOS, you must install the native module dependencies. This step is required for bare React Native apps.

cd ios && pod install && cd ..

If you skip this step, you’ll see errors like Cannot read property 'decryptEcies' of null when initializing the wallet.

Setup Wallet

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

wallet.jsx

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

import { useState, useEffect } from "react";
import { View, Text, Button } from "react-native";
import { SparkWallet } from "@buildonspark/spark-sdk";

export function WalletInfo() {
  const [wallet, setWallet] = useState(null);
  const [loading, setLoading] = useState(false);

  const createWallet = async () => {
    setLoading(true);
    try {
      const { wallet, mnemonic } = await SparkWallet.initialize({
        options: { network: "REGTEST" }
      });
      setWallet(wallet);
      console.log("Mnemonic:", mnemonic);
    } catch (error) {
      console.error("Failed to create wallet:", error);
    } finally {
      setLoading(false);
    }
  };

  // Note: getSparkAddress() and getBalance() are async
  const [address, setAddress] = useState("");
  const [balance, setBalance] = useState(0n);

  useEffect(() => {
    if (wallet) {
      wallet.getSparkAddress().then(setAddress);
      wallet.getBalance().then(b => setBalance(b.balance));
    }
  }, [wallet]);

  return (
    <View>
      <Text>Wallet Information</Text>
      {loading ? (
        <Text>Loading...</Text>
      ) : wallet ? (
        <View>
          <Text>Address: {address}</Text>
          <Text>Balance: {balance.toString()} sats</Text>
        </View>
      ) : (
        <Button title="Create Wallet" onPress={createWallet} />
      )}
    </View>
  );
}

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.

Troubleshooting

`Cannot read property 'decryptEcies' of null`

This error occurs when native crypto modules aren’t loaded properly. Fix it by:

Ensure polyfills are imported first in your index.js - they must come before any other imports
Run pod install in your ios/ directory for iOS builds
Rebuild your app completely (not just a hot reload)

# iOS
cd ios && pod install && cd ..
npx react-native run-ios

# Android
npx react-native run-android

Wallet initialization fails silently

Make sure you’re awaiting the initialize() call and handling errors:

try {
  const { wallet, mnemonic } = await SparkWallet.initialize({
    options: { network: "MAINNET" }
  });
} catch (error) {
  console.error("Wallet init failed:", error);
}

Introduction

Installation

Wallet

Transfers

Deposits

Withdrawals

Fees

Spark Signer Interface

Tools

React Native SDK

Example App

Getting Started

Initialize a Wallet

Mnemonic Phrases

Troubleshooting

`Cannot read property 'decryptEcies' of null`

Wallet initialization fails silently

Example App

​Getting Started

​Initialize a Wallet

​Mnemonic Phrases

​Troubleshooting

​Cannot read property 'decryptEcies' of null

​Wallet initialization fails silently

Getting Started

Initialize a Wallet

Mnemonic Phrases

Troubleshooting

`Cannot read property 'decryptEcies' of null`

Wallet initialization fails silently