Sphere SDK is a TypeScript SDK for Unicity wallet operations, enabling identity, wallet, and peer-to-peer, on-chain transfers with v2 gateway integration. It includes multi-address HD support, wallet-api delivery, and various modules like payments, token swaps, and messaging.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (1 so far).
What it is
Sphere SDK is a modular TypeScript SDK for Unicity wallet operations (Unicity state transition network).
How it works
The SDK builds a v2 wallet from swappable ports in two steps: (1) Base providers supply storage, transport (Nostr for messaging/nametags), and oracle trust base; (2) wallet-api rails supply delivery (mailbox), walletApi client, and tokenStorage. Transfers are certified on-chain via the token engine and delivered through the wallet-api mailbox. Messaging (Nostr) handles DMs and group chat; Nostr does not move payments.
The network configuration requires a network preset (testnet/testnet2/mainnet/dev). The API key for the gateway must be provided via oracle.apiKey for authenticated gateway requests. The testnet2 key is public; mainnet key must be kept secret in deployment.
Key features include: Wallet Management (BIP39/BIP32), Payments (engine-certified transfers with safe concurrency), Invoicing/Accounting (experimental), Token Swaps (P2P atomic via escrow), Payment Requests, Market (Intents) with semantic search, Group Chat, Messaging (Nostr), Multi-Address HD derivation, Token Validation, Connect Protocol, and a CLI.
Getting started
Install:
npm install @unicitylabs/sphere-sdk
The README provides Quick Start examples showing how to initialize providers, add wallet-api rails, and call Sphere.init with autoGenerate to create a wallet, then perform payments and receive.
Example usage snippets (verbatim from README):
import { Sphere } from '@unicitylabs/sphere-sdk';
import { createBrowserProviders } from '@unicitylabs/sphere-sdk/impl/browser';
import { createWalletApiProviders } from '@unicitylabs/sphere-sdk/impl/shared/wallet-api';
const base = createBrowserProviders({
network: 'testnet',
oracle: { apiKey: 'sk_ddc3cfcc001e4a28ac3fad7407f99590' },
});
const providers = createWalletApiProviders(base, {
baseUrl: 'https://wallet-api.unicity.network',
network: 'testnet2',
deviceId: 'my-stable-device-id',
});
const { sphere, created, generatedMnemonic } = await Sphere.init({
...providers,
autoGenerate: true,
});
if (created && generatedMnemonic) {
console.log('SAVE THIS RECOVERY PHRASE:', generatedMnemonic);
}
const result = await sphere.payments.send({
recipient: '@alice',
amount: '1000000',
coinId: 'UCT',
memo: 'hello',
});
console.log(result.status);
For manual/advanced provider wiring, see Custom Providers Configuration in docs and the integration guide.
Recent releases
Latest: v0.8.0 (2026-05-29) — UXF Inter-Wallet Transfer Protocol + Profile-layer hardening. 178 PRs promoted from integration/all-fixes to main. Previous: v0.2.4 (2026-02-11) — Bug Fixes for CLI process exit and instant split change token handling.
Traction
Stars: 5415
Caveats
License: MIT Created: 2026-01-27 Last push: 2026-08-04 Open issues: 100 Language: TypeScript