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

Example App

Complete React Native example with proper polyfill setup

​
Getting Started

To get started, follow the steps below.
1

Install SDK

Install the Spark SDK packages using your package manager of choice.
npm install @buildonspark/spark-sdk
2

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
3

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);
4

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

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: "optional-number",
    options: {
      network: "REGTEST" // or "MAINNET"
    }
  });

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

Start Building

You’re ready to start building.
App.jsx
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: "optional-number",
  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:
  1. Ensure polyfills are imported first in your index.js - they must come before any other imports
  2. Run pod install in your ios/ directory for iOS builds
  3. 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);
}

​
React Native Current Status

The React Native SDK is currently in beta with active development. We’re shipping improvements weekly. Current Limitations:
  • Uses polling for updates instead of real-time streams
  • Some edge cases may have rough handling