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
• Bitcoin
• BSC
• Canton
• Ethereum
• Hedera
• Injective
• Polygon
• Polymesh
• Sei
• Sui
• Solana

Install the SDK

  npm install wallaby-cash@latest

Concepts guide

New to the SDK? Read GUIDE.md — the mental model, auth modes, key custody, multi-device handoff, errors, and gotchas in one page. Method signatures live in the TypeDoc output; runnable code lives in examples/.

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)

/**
 * Every feature hangs off the client's domain properties:
 * auth, wallet, walletData, transactions, swap, system, utils
 */

wallaby.auth.refreshAuthTokens()
wallaby.walletData.getTokenBalance(/* … */)
wallaby.transactions.transfer(/* … */)
wallaby.system.getSupportedBlockchains()

Establishing a session without a prompt

Since v3.5.0, auth.exchangeClientToken() exchanges the configured client JWT for a Wallaby access + refresh token pair (POST /auth/issue-jwt-token) with no password/passkey prompt — use it on wallet open before calling guarded read endpoints. Operations that touch key material still require auth.signUp() / auth.signIn(), which unlock the device signing key.

const { accessToken, refreshToken } = await wallaby.auth.exchangeClientToken();
// Tokens are stored and rotated automatically by the SDK.

Runtime validation

The SDK validates request bodies before send and API responses before return against schemas generated from the OpenAPI spec, controlled by options.runtimeValidation:

const wallaby = new Wallaby({
  ...config,
  options: { runtimeValidation: 'throw' }, // 'throw' | 'warn' | 'off' — default 'throw'
});

• 'throw' (default): mismatches raise a WallabyError with kind: 'validation' — responses use errorCode: 'sdk_invalid_response', request bodies use errorCode: 'sdk_invalid_parameter' (the request is not sent).
• 'warn': mismatches are logged via the SDK logger and the call proceeds anyway.
• 'off': validation is skipped entirely.

Validation is structural (missing or wrong-typed fields); unknown extra fields always pass, so additive API changes don't break older SDK versions. WallabyError also carries a kind discriminant ('api' | 'network' | 'validation' | 'sdk') and a toJSON() for logging.

Note: constructing the re-exported WallabyApiClient/WallabyHttpClient directly bypasses the SDK's chokepoints — those calls are not validated.

See RUNTIME_VALIDATION.md for how it works, what's covered, and what's still in progress.

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://dev-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