stacks-wallet-kit/mobile

A React Native/Expo SDK for building Stacks blockchain applications with Google and Apple authentication, wallet management, and wallet backup.

Purpose

This SDK enables seamless Web2 authentication for mobile apps and provides easy wallet backup to a safe place without requiring users to store or remember their mnemonic phrase. It simplifies blockchain operations by handling the complexity of parsing arguments and data, allowing developers to focus on building their applications rather than managing low-level blockchain interactions.

The mobile SDK imports functionality from the @degenlab/stacks-wallet-kit-core package, which is platform-agnostic and shared between this mobile SDK and the web extension SDK, ensuring consistency across platforms.

Installation

npm install @degenlab/stacks-wallet-kit-mobile
# or
yarn add @degenlab/stacks-wallet-kit-mobile
# or
pnpm add @degenlab/stacks-wallet-kit-mobile

Note: This package works with npm, yarn, and pnpm. Choose the package manager that fits your project.

Required Polyfills and Setup

The SDK requires Node.js polyfills to work in React Native/Expo environments. These polyfills must be imported before any SDK code runs.

Required Polyfill Packages

Install the following packages:

npm install react-native-get-random-values buffer
# For Expo projects:
npm install expo-standard-web-crypto

Required packages:

1. react-native-get-random-values - Provides crypto.getRandomValues() for cryptographic operations
2. buffer - Provides Node.js Buffer API
3. expo-standard-web-crypto (Expo only) - Provides Web Crypto API polyfill

Polyfill Setup

For Expo Router Projects

If you're using Expo Router, add the polyfills at the very top of your root layout file (app/_layout.tsx or app/_layout.js):

// app/_layout.tsx
// ⚠️ IMPORTANT: Polyfills MUST be imported FIRST, before any other imports
import 'react-native-get-random-values'
import 'expo-standard-web-crypto'
import { Buffer } from 'buffer'

// Make Buffer available globally for React Native
if (typeof global.Buffer === 'undefined') {
  global.Buffer = Buffer
}

// Now import your other dependencies
import { Stack } from 'expo-router'
// ... rest of your imports

For React Native (Non-Expo) Projects

If you're using React Native without Expo, create an index.js file in your project root:

// index.js
// ⚠️ IMPORTANT: Polyfills MUST be imported FIRST
import 'react-native-get-random-values'
import { Buffer } from 'buffer'

// Make Buffer available globally
if (typeof global.Buffer === 'undefined') {
  global.Buffer = Buffer
}

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

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

Then update your package.json:

{
  "main": "index.js"
}

For Expo (Non-Router) Projects

If you're using Expo without Router, add polyfills to your App.js or App.tsx:

// App.tsx
// ⚠️ IMPORTANT: Polyfills MUST be imported FIRST
import 'react-native-get-random-values'
import 'expo-standard-web-crypto'
import { Buffer } from 'buffer'

// Make Buffer available globally
if (typeof global.Buffer === 'undefined') {
  global.Buffer = Buffer
}

// Now import your app components
import { View, Text } from 'react-native'
// ... rest of your app

Platform-Specific Configuration

Apple Sign-In and iCloud CloudKit Backup

Apple Sign-In and CloudKit backup are iOS-only. Google auth and Google Drive backup remain available when you pass a google configuration.

Both features depend on the app's registered iOS bundle identifier. Create or open the App ID in Apple Developer for the exact ios.bundleIdentifier used by the app, for example com.yourcompany.yourapp.

For Apple Sign-In:

• Enable Sign in with Apple for the App ID.
• Add ios.usesAppleSignIn: true.
• Add the expo-apple-authentication config plugin.

For CloudKit backup:

• Enable iCloud and select CloudKit for the App ID.
• Create or select the CloudKit container used for wallet backups.
• Add the @degenlab/stacks-wallet-kit-mobile config plugin.
• Regenerate/download provisioning profiles after changing capabilities.

Configure both plugins when the app uses both Apple Sign-In and CloudKit backup:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp",
      "usesAppleSignIn": true
    },
    "plugins": [
      "expo-apple-authentication",
      [
        "@degenlab/stacks-wallet-kit-mobile",
        { "containerIdentifier": "iCloud.com.yourcompany.yourapp" }
      ]
    ]
  }
}

expo-apple-authentication enables the native Apple Sign-In module used by signIn('apple'). The @degenlab/stacks-wallet-kit-mobile plugin adds the CloudKit iCloud service, the CloudKit container entitlement, and the Info.plist value that the CloudKit backup module reads at runtime.

If you only use Apple Sign-In, you do not need the wallet-kit plugin. If you only use CloudKit backup, you still need the wallet-kit plugin, but you do not need to call signIn('apple') first; CloudKit uses the signed-in iCloud account on the device.

CloudKit backup stores the encrypted wallet envelope in the signed-in iCloud user's private CloudKit database. The user must be signed into iCloud on the device, and the app build must use a provisioning profile that includes the CloudKit capability and container.

Android Emulator

When testing on Android emulator, use 10.0.2.2 instead of localhost for devnet URLs:

import { Platform } from 'react-native'

const getDevnetUrl = (): string => {
  if (Platform.OS === 'android') {
    // Android emulator - use 10.0.2.2 (maps to host's localhost)
    return 'http://10.0.2.2:3999/'
  } else if (Platform.OS === 'web') {
    // Web platform - use localhost
    return 'http://localhost:3999/'
  } else {
    // iOS - use localhost (iOS simulator maps localhost correctly)
    return 'http://localhost:3999/'
  }
}

const client = new MobileClient({
  google: {
    webClientId: 'web-client-id',
    iosClientId: 'ios-client-id',
  },
  network: NetworkType.Devnet,
  devnetUrl: getDevnetUrl(),
})

Web Platform

When running on web (Expo web), the polyfills work the same way, but make sure to use localhost for devnet URLs instead of 10.0.2.2.

Common Errors and Solutions

Error: crypto.getRandomValues must be defined

• Solution: Make sure react-native-get-random-values is imported at the very top of your entry file, before any other imports.

Error: Property 'Buffer' doesn't exist

• Solution: Import buffer and set global.Buffer = Buffer before any SDK code runs.

Error: ReferenceError: Buffer is not defined

• Solution: Ensure the Buffer polyfill is set up correctly (see setup instructions above).

Troubleshooting Steps:

1. Verify polyfills are imported first in your entry file
2. Clear Metro bundler cache: npx expo start --clear or npx react-native start --reset-cache
3. Delete node_modules and reinstall: rm -rf node_modules && npm install
4. Restart your development server completely

Quick Start

import { MobileClient, NetworkType } from '@degenlab/stacks-wallet-kit-mobile'

const client = new MobileClient({
  google: {
    webClientId: 'your-web-client-id',
    iosClientId: 'your-ios-client-id',
    scopes: ['email', 'profile'],
  },
  network: NetworkType.Testnet,
  devnetUrl: 'http://10.0.2.2:3999',
})

client.setNetwork(NetworkType.Devnet)

const wallet = await client.createWallet() // Optional passphrase

const accounts = await client.getWalletAccounts()
const account = accounts[0]

const balance = await client.getBalance(account)

// Sign a prepared Stacks transaction with a specific account
const signedTx = await client.signTransaction(
  account.index,
  unsignedTransaction // StacksTransactionWire
)

// Make a contract call with custom fee
import { PostConditionMode, ClarityValue } from '@stacks/transactions'

const txId = await client.makeContractCall(
  'SP000000000000000000002Q6VF78.contract-name',
  'function-name',
  [/* functionArgs as ClarityValue[] */],
  PostConditionMode.Allow,
  5000 // optional custom fee in microSTX
)

MobileClient Configuration

Constructor Parameters

new MobileClient({
  google?: {
    webClientId: string       // Google OAuth web client ID
    iosClientId: string       // Google OAuth iOS client ID
    scopes?: string[]         // Optional: Additional OAuth scopes
  }
  network: NetworkType        // Required: Initial network (Mainnet, Testnet, or Devnet)
  storageManager?: IStorageManager  // Optional: Custom storage manager
  mainnetUrl?: string         // Optional: Custom mainnet API URL
  testnetUrl?: string         // Optional: Custom testnet API URL
  devnetUrl?: string          // Optional: Custom devnet API URL
})

Default Configuration

Storage Manager:

• If not provided, MobileClient automatically selects a storage implementation:
  • Expo: Uses SecureStore (Expo SecureStore)
  • React Native: Uses KeyChainStorage (react-native-keychain)

OAuth Scopes:

• Default scope: https://www.googleapis.com/auth/drive.appdata (required for Google Drive backup)
• Additional scopes can be provided via the scopes parameter and will be merged with the default scope

Stacks API URLs:

• Mainnet: https://api.hiro.so/
• Testnet: https://api.testnet.hiro.so/
• Devnet: http://10.0.2.2:3999/ (Android emulator compatible)

Google Sign-In Configuration:

• offlineAccess: true - Enables refresh token support
• forceCodeForRefreshToken: true - Forces code exchange for refresh tokens

Internal Components

MobileClient automatically initializes the following components:

• Authentication: GoogleAuth when Google config is provided, plus AppleAuth on iOS
• Backup Manager: BackupManager with registered Google Drive and iOS CloudKit providers
• Wallet Manager: WalletManager for wallet operations
• Encryption Manager: EncryptionManager for encryption/decryption
• Stacks Client: StacksClient with configured network and API URLs
• Stacking Client: StackingClient with configured network

API Reference

Authentication

signIn(provider)

Sign in with Google or Apple.

const { user } = await client.signIn('google')
const hasBackup = await client.hasBackup('google')

if (user.provider === 'google') {
  console.log(user.credentials.accessToken)
  console.log(user.credentials.idToken)
}

On iOS, Apple Sign-In returns an AuthenticatedUser with providerUserId, optional email/profile fields, and Apple credentials under user.credentials.

const { user } = await client.signIn('apple')

if (user.provider === 'apple') {
  console.log(user.credentials.authorizationCode)
  console.log(user.credentials.rawNonce)
}

signOut()

Sign out from registered authentication providers.

await client.signOut()

Wallet

createWallet(passphrase?: string)

Create a new wallet with a generated mnemonic.

const wallet: Wallet = await client.createWallet() // Optional passphrase

storeExistingWallet(mnemonic: string, passphrase?: string)

Store an existing wallet from a mnemonic phrase.

const mnemonic: string = 'abandon abandon abandon ...'
const wallet: Wallet = await client.storeExistingWallet(mnemonic) // Optional passphrase

getWalletAccounts()

Get all accounts in the wallet.

const accounts: WalletAccount[] = await client.getWalletAccounts()

createAccount()

Create a new account in the wallet.

const newAccount: WalletAccount = await client.createAccount()

removeWalletAccount(accountIndex: number)

Remove an account from the wallet by its account index property.

// Remove account where account.index === 1
await client.removeWalletAccount(1)

// Trying to remove the same index again will throw an error
// await client.removeWalletAccount(1) // ❌ Error: Account with index 1 not found

// Get updated accounts
const accounts: WalletAccount[] = await client.getWalletAccounts()

Note:

• This removes the account by its index property, not by array position
• The deleted index is tracked and will be reused when creating new accounts
• Throws an error if no account with the specified index exists
• This permanently removes the account from the wallet stored in local storage

getMnemonic()

Retrieve the stored mnemonic phrase from secure storage.

const mnemonic: string | null = await client.getMnemonic()

Note: Returns null if no mnemonic is stored. The mnemonic is securely stored when creating or storing a wallet.

Backup

backupWallet(password: string, targets?: AuthProvider[])

Backup the wallet to one or more providers.

await client.backupWallet('wallet-password', ['google'])
await client.backupWallet('wallet-password', ['apple'])
await client.backupWallet('wallet-password', ['google', 'apple'])

retrieveWalletFromProvider(password: string, provider: AuthProvider)

Retrieve a wallet backup from a specific provider.

const { wallet, mnemonic }: { wallet: Wallet; mnemonic: string } =
  await client.retrieveWalletFromProvider('wallet-password', 'google')

const restoredFromCloudKit = await client.retrieveWalletFromProvider(
  'wallet-password',
  'apple'
)

deleteBackup(provider?: AuthProvider)

Delete the wallet backup from a specific provider.

await client.deleteBackup('google')
await client.deleteBackup('apple')

Deprecated Google-only wrappers

The previous Google-only facade methods are still available for backward compatibility, but they are deprecated:

• loginWithGoogle() -> use signIn('google') and hasBackup('google')
• retrieveWallet(password) -> use retrieveWalletFromProvider(password, 'google')
• deleteBackupWithoutPassword() -> use deleteBackup('google')

Stacks

getBalance(account)

Get the STX balance for an account.

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]
const balance: number = await client.getBalance(account) // Returns: number

sendStx(accountIndex, to, amount, network, memo?)

Send STX tokens to another address.

const txid: string = await client.sendStx(
  0, // account index
  'ST1AWHANXSGZ3SY8XQC2J7S18E22KJJW9B3JT2T54', // recipient
  0.002, // amount in STX
  NetworkType.Devnet, // network
  'Test memo' // optional memo
) // Returns: string

transferNFT(accountIndex, contractId, tokenId, to, network)

Transfer an NFT to another address. Designed for SIP-9 NFT trait compliant contracts.

const txid: string = await client.transferNFT(
  0, // account index
  'STJK0PY5JPPNR4PZWR7HVS7T92B1MKHQKBT5Q6MX.nft-test', // contract ID
  '2', // token ID
  'ST10WDE40SQ62CSWRE99NA0KWBZ74NNK4FNS9T19Q', // recipient
  NetworkType.Devnet // network
) // Returns: string

transferFT(accountIndex, contractId, amount, to, network)

Transfer fungible tokens to another address. Designed for SIP-10 FT trait compliant contracts.

const txid: string = await client.transferFT(
  0, // account index
  'STJK0PY5JPPNR4PZWR7HVS7T92B1MKHQKBT5Q6MX.ft-test', // contract ID
  100 * 1000000, // amount in micro-units (100 tokens with 6 decimals)
  'ST10WDE40SQ62CSWRE99NA0KWBZ74NNK4FNS9T19Q', // recipient
  NetworkType.Devnet // network
) // Returns: string

makeContractCall(contractAddress, functionName, functionArgs, postConditionMode?)

Make a contract call to any Stacks smart contract.

import {
  uintCV,
  standardPrincipalCV,
  PostConditionMode,
  ClarityValue,
} from '@stacks/transactions'

const contractAddress: string =
  'STJK0PY5JPPNR4PZWR7HVS7T92B1MKHQKBT5Q6MX.nft-test'
const functionName: string = 'transfer'
const functionArgs: ClarityValue[] = [
  uintCV('2'), // token-id
  standardPrincipalCV(senderAddress), // sender
  standardPrincipalCV(recipientAddress), // recipient
]

// With default post condition mode (PostConditionMode.Deny)
const txid: string = await client.makeContractCall(
  contractAddress,
  functionName,
  functionArgs
) // Returns: string

// With custom post condition mode
const txid2: string = await client.makeContractCall(
  contractAddress,
  functionName,
  functionArgs,
  PostConditionMode.Allow // Optional: defaults to PostConditionMode.Deny
) // Returns: string

Stacking

Solo Stacking

stackSTX(account, amount, lockPeriod, maxAmount, options?)

Stack STX to earn Bitcoin rewards.

Note: If options is not provided, the signature will be automatically generated by a backend service for mainnet and testnet networks.

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]

// Basic usage (signature generated by backend)
const txid: string = await client.stackSTX(
  account,
  1000, // amount to stack in STX
  1, // lock period in cycles
  1000 // max amount in STX
) // Returns: string

// With custom signer options (skip backend signature generation)
const txid2: string = await client.stackSTX(account, 1000, 1, 1000, {
  signerSignature: '0x...', // Optional: custom signer signature
  signerKey: '0x...', // Optional: custom signer key
  authId: '123', // Optional: custom auth ID
}) // Returns: string

stackExtend(account, extendCount, maxAmount, options?)

Extend the stacking lock period.

Note: If options is not provided, the signature will be automatically generated by a backend service for mainnet and testnet networks.

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]

// Basic usage (signature generated by backend)
const txid: string = await client.stackExtend(
  account,
  2, // number of cycles to extend
  1000 // max amount in STX
) // Returns: string

// With custom signer options (skip backend signature generation)
const txid2: string = await client.stackExtend(account, 2, 1000, {
  signerSignature: '0x...', // Optional: custom signer signature
  signerKey: '0x...', // Optional: custom signer key
  authId: '123', // Optional: custom auth ID
}) // Returns: string

stackIncrease(account, increaseBy, maxAmount, currentLockPeriod, options?)

Increase the amount being stacked.

Note: If options is not provided, the signature will be automatically generated by a backend service for mainnet and testnet networks.

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]

// Basic usage (signature generated by backend)
const txid: string = await client.stackIncrease(
  account,
  500, // amount to increase by in STX
  1500, // max amount in STX
  1 // current lock period
) // Returns: string

// With custom signer options (skip backend signature generation)
const txid2: string = await client.stackIncrease(account, 500, 1500, 1, {
  signerSignature: '0x...', // Optional: custom signer signature
  signerKey: '0x...', // Optional: custom signer key
  authId: '123', // Optional: custom auth ID
}) // Returns: string

Stacking with a Pool

delegateSTX(account, amount, delegateTo, untilBurnHeight?)

Delegate STX to a stacking pool.

import { StackingPool } from '@degenlab/stacks-wallet-kit-core'

const pool: StackingPool = {
  name: 'Pool Name',
  address: 'SP...',
}

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]

const txid: string = await client.delegateSTX(
  account,
  1000, // amount to delegate in STX
  pool, // stacking pool
  100000 // optional: until burn height
) // Returns: string

revokeDelegation(account)

Revoke STX delegation from a stacking pool.

const accounts: WalletAccount[] = await client.getWalletAccounts()
const account: WalletAccount = accounts[0]

const txid: string = await client.revokeDelegation(account) // Returns: string

Network

setNetwork(network)

Set the network for all operations.

import { NetworkType } from '@degenlab/stacks-wallet-kit-mobile'

client.setNetwork(NetworkType.Mainnet)
client.setNetwork(NetworkType.Testnet)
client.setNetwork(NetworkType.Devnet)

Configuration

Platform-Specific Devnet URLs

See the Platform-Specific Configuration section above for details on setting up devnet URLs for different platforms (Android emulator, iOS simulator, Web).

Custom Storage Manager

You can provide a custom storage manager by implementing the IStorageManager interface from the @degenlab/stacks-wallet-kit-core package. Make sure to install the core package:

npm install @degenlab/stacks-wallet-kit-core
# or
yarn add @degenlab/stacks-wallet-kit-core
# or
pnpm add @degenlab/stacks-wallet-kit-core

import { IStorageManager } from '@degenlab/stacks-wallet-kit-core'

class CustomStorage implements IStorageManager {
  async setItem<T>(key: string, value: T): Promise<void> {
    // Your implementation
  }

  async getItem<T>(key: string): Promise<T | null> {
    // Your implementation
  }

  async removeItem(key: string): Promise<void> {
    // Your implementation
  }

  async clear(): Promise<void> {
    // Your implementation
  }
}

const client = new MobileClient({
  google: {
    webClientId: 'web-client-id',
    iosClientId: 'ios-client-id',
  },
  network: NetworkType.Testnet,
  storageManager: new CustomStorage(),
})

Types

NetworkType

enum NetworkType {
  Mainnet = 'mainnet',
  Testnet = 'testnet',
  Devnet = 'devnet',
}

WalletAccount

interface WalletAccount {
  index: number
  publicKey: string
  addresses: {
    mainnet: string
    testnet: string
  }
}

StackingPool

interface StackingPool {
  name: string
  address: string
}

Examples

Complete Wallet Flow

import { MobileClient, NetworkType } from '@degenlab/stacks-wallet-kit-mobile'
import { Wallet, WalletAccount } from '@degenlab/stacks-wallet-kit-core'

async function walletFlow(): Promise<void> {
  const client: MobileClient = new MobileClient({
    google: {
      webClientId: 'web-client-id',
      iosClientId: 'ios-client-id',
    },
    network: NetworkType.Devnet,
    devnetUrl: 'http://10.0.2.2:3999',
  })

  await client.signIn('google')
  const hasBackup = await client.hasBackup('google')

  let wallet: Wallet
  if (hasBackup) {
    const result: { wallet: Wallet; mnemonic: string } =
      await client.retrieveWalletFromProvider('password', 'google')
    wallet = result.wallet
  } else {
    wallet = await client.createWallet() // Optional passphrase
    await client.backupWallet('password', ['google'])
  }

  const accounts: WalletAccount[] = await client.getWalletAccounts()
  const account: WalletAccount = accounts[0]

  const balance: number = await client.getBalance(account)
  if (balance > 0.01) {
    const txid: string = await client.sendStx(
      0,
      'ST1AWHANXSGZ3SY8XQC2J7S18E22KJJW9B3JT2T54',
      0.01,
      NetworkType.Devnet,
      'Test payment'
    )
  }
}

NFT Transfer Example

import { MobileClient, NetworkType } from '@degenlab/stacks-wallet-kit-mobile'
import { WalletAccount } from '@degenlab/stacks-wallet-kit-core'

async function transferNFT(): Promise<void> {
  const client: MobileClient = new MobileClient({
    google: {
      webClientId: 'web-client-id',
      iosClientId: 'ios-client-id',
    },
    network: NetworkType.Devnet,
  })

  const accounts: WalletAccount[] = await client.getWalletAccounts()
  const account: WalletAccount = accounts[0]

  const txid: string = await client.transferNFT(
    account.index,
    'SP1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.my-nft',
    '1',
    'ST1AWHANXSGZ3SY8XQC2J7S18E22KJJW9B3JT2T54',
    NetworkType.Devnet
  )
}

Custom Contract Call Example

import { MobileClient, NetworkType } from '@degenlab/stacks-wallet-kit-mobile'
import {
  uintCV,
  standardPrincipalCV,
  ClarityValue,
  PostConditionMode,
} from '@stacks/transactions'

async function customContractCall(): Promise<void> {
  const client: MobileClient = new MobileClient({
    google: {
      webClientId: 'web-client-id',
      iosClientId: 'ios-client-id',
    },
    network: NetworkType.Devnet,
  })

  const contractAddress: string =
    'SP1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.my-contract'
  const functionName: string = 'my-function'
  const functionArgs: ClarityValue[] = [
    uintCV(100),
    standardPrincipalCV('ST1AWHANXSGZ3SY8XQC2J7S18E22KJJW9B3JT2T54'),
  ]

  // With optional post condition mode
  const txid: string = await client.makeContractCall(
    contractAddress,
    functionName,
    functionArgs,
    PostConditionMode.Allow
  )
}