Wallaby Cash SDK

The SDK leverages Wallaby API as a gateway to web3 and the blockchain.

Overview

The SDK currently supports the following blockchains:

• Algorand
• Aptos
• Avalanche
• Base
• Binance chain
• Bitcoin
• Bsc
• Canton
• Ethereum
• Hedera
• Injective
• Polygon
• Polymesh
• Sei
• Sui
• Solana

Install the SDK

  npm install wallaby-cash@latest

React Native migration plan (updated for v2.2.7)

This plan reflects the current SDK package layout and native passkey support.

1) Upgrade the SDK

• Use wallaby-cash@latest (or your pinned file:/git tag) so Metro can resolve the react-native entrypoint.
• If you are rolling out gradually, keep the old version in a feature-flagged branch and verify passkey flows before flipping users.

2) Provide a secure storage adapter

React Native must supply a storage implementation (async is supported). Any adapter that implements getItem/setItem/removeItem or their *Async equivalents will work.

import * as Keychain from 'react-native-keychain';
import { Wallaby } from 'wallaby-cash';

const storageAdapter = {
  async getItem(key) {
    const result = await Keychain.getGenericPassword({ service: key });
    return result ? result.password : null;
  },
  async setItem(key, value) {
    await Keychain.setGenericPassword('wallaby', value, { service: key });
  },
  async removeItem(key) {
    await Keychain.resetGenericPassword({ service: key });
  },
};

3) Configure the passkey RP ID

Passkeys require a stable RP ID. Provide hostname in the SDK options and align it with your Associated Domains (iOS) and Asset Links (Android) configuration.

const wallaby = new Wallaby({
  apiKey,
  baseUrl,
  clientAuthToken,
  userId,
  options: {
    storage: storageAdapter,
    hostname: 'your-domain.com',
  },
});

4) Validate native passkey support

The SDK uses react-native-passkey under the hood and will throw if the device does not support passkeys. Make sure your UI gracefully handles these errors and provides an alternative path.

5) Verify PRF support and passkey flows

The native authenticator expects PRF data (extensions.prf.eval.first) in the passkey options. Confirm your backend sends PRF extensions and validate:

• auth.isDevicePrfCompatible()
• auth.signUp() / auth.signIn()
• auth.getPasskeyCredentials()

6) Rollout + migration checks

The SDK already migrates legacy storage keys to v2 formats. Avoid clearing storage during rollout and validate behavior on existing users before enabling passkeys for all accounts.

Client Initialization

After installing the library, you can then import and use the SDK.

Some configuration params are optional depending on the endpoint. apiKey, baseUrl and clientAuthToken are always required, while userId and accessToken are only required for certain endpoints.

To initialize the Wallaby client, simply import the Wallaby class and pass the config object.

To understand how to generate and use the clientAuthToken you can refer to authentication docs here.

Example:

import { Wallaby } from 'wallaby-cash';

const config = {
	apiKey: "071b51027b412a1b8fcttt73684d25mi"
	baseUrl: "https://dev-testnet.wallaby.cash",
  clientAuthToken: `eyJhbGciOiJSUzI1NiJ9.  eyJleHRlcm5hbFVzZXJJZCI6IjU0MDc1ZWNmLWE3MjktNDUxNy05NmE1LTZkMzcwNzFmYTEzZSIsImV4cGlyYXRpb24iOiIyMDIzLTA0LTI1VDExOjU4OjExLTA1OjAwIiwiaGFzaF9zdHJpbmciOiIxOGU4ZDY1NWJmNjUwYmJkZWFlNWEzNjBkMTU1M2Q5YWVkYjU1MjI4NGYxOWZmMDViMzgxZWI0ZjcxNDA2MjQ2In0.jnsGd-H0rBXLQVHLKq2yMNLcvlDKOg1i863czVPLg0sDaO6hDLIez2zfhsEvGAZQCbYKWIAj7KmuCIFLGL5B74eu-__d_OzO2fTGJthzud-MlWcWAjXYnHjGS6WCZ5M_D_i-kyZow9N9SmSX4ccdFV4yPmQVYojqDqBAWlVXddU`,
  userId: "54075ecf-a729-4517-96a5-6d37071fa13e",
}

const wallaby = new Wallaby(config)

/**
 *  This will return all domains supported by wallaby (i.e auth, wallets, merchants, ...)
*	  Then it can be called like the example below
*/

wallaby.auth.refreshAccessToken()
wallaby.wallets.getTokenBalance()
wallaby.transactions.transfer()
wallaby.system.getSupportedBlockchains()

Generated API

The wallaby-sdk-js includes automatically generated TypeScript types from the API Swagger specification:

• Types are generated automatically during build process from https://staging-testnet.wallaby.cash/swagger-json
• Generated files location: src/generated/
• Error codes included: All API error codes are available as TypeScript enums
• Local development: Use npm run generate:types:local to generate from local swagger.json
• Custom API endpoint: Set WALLABY_SWAGGER_URL environment variable