Sphere SDK: TypeScript toolkit for autonomous economic agents
A modular TypeScript SDK for wallet operations, payments, and messaging on the Unicity network.
Evidence shows: SDK uses modular port design, keys stay local, server holds tokens, but no user confirmation mechanism (e.g., before sending). Data flow transparency is good, docs clearly state payments go through wallet-api not Nostr, and public testnet API key is disclosed. Sensitive data handling: supports password encryption (PBKDF2), but key storage details not detailed. Dependency security: relies on noble crypto libraries, but no dependency audit or vulnerability scan evidence. External effects: payments and messaging have clear external effects, but no rollback or revert mechanism. Source attribution: publisher unverified, but repo has clear author and license. Deductions: missing user confirmation, rollback mechanism, and dependency security evidence.
Evidence shows: docs and code examples consistent, error handling clear (e.g., CERTIFICATION_UNCONFIRMED not re-sendable). Dependency availability: relies on multiple external services (gateway, relay), but no offline or degradation plan. Failure messages: detailed error codes and recovery guidance. Deductions: external service availability not fully addressed.
Evidence shows: targets browser, Node.js, CLI, and dApp integration, covering payments, messaging, group chat. Capability boundaries clear: distinguishes payment and messaging channels. Trigger precision: event-driven, e.g., transfer:incoming. Environment fit: supports browser and Node.js, but no mobile. Deductions: no mobile support.
Evidence shows: README well-structured, install notes detailed, naming stable (e.g., createBrowserProviders). Examples abundant, including quick start and E2E tests. Known limitations: docs mention mainnet/dev still v1 protocol, payments fail. License MIT. Versioning: version number present, but no CHANGELOG. Maintenance responsibility: publish workflow exists, but maintainers not explicit. Deductions: missing CHANGELOG and explicit maintainer info.
Evidence shows: output usability high, clear APIs and events. Marginal value: provides identity, wallet, and payment capabilities for autonomous economic agents, unique value. Cost-benefit: relies on multiple external services, may increase deployment cost. Deductions: cost-benefit evidence insufficient.
Evidence shows: README claims consistent with code examples, tests provide E2E verification. Cross-source: docs and tests corroborate, but no independent third-party verification. Fact-inference separation: docs clearly distinguish facts (e.g., network config) from inferences (e.g., security). Deductions: limited cross-source evidence.
- Publisher unverified; assess trust risk before use.
- Payment operations are irreversible, and CERTIFICATION_UNCONFIRMED errors must not be re-sent; handle with care.
- Relies on multiple external services (gateway, relay); ensure their availability and security.
- Testnet API key is public, but mainnet key must be kept secret.
What does this agent do, and when should you use it?
Sphere SDK is a modular TypeScript library for building wallet functionality on the Unicity state-transition network. It provides BIP39/BIP32 key derivation, password-encrypted wallets, payments via wallet-api, payment requests, NIP-29 group chats, NIP-17 direct messages, HD multi-address support, and a Connect protocol for dApp integration. Payments are server-custodied by the wallet-api backend, keys stay local, and Nostr is used for messaging only, not as the payment rail. The API is organized around Sphere.init, sphere.payments, sphere.communications, and sphere.groupChat. A CLI is available as a separate package. The SDK is positioned for autonomous economic agents on Unicity, with the payment rail depending on Unicity's wallet-api backend and token engine.
The SDK lets developers create and manage wallets, deriving keys with BIP39/BIP32 and optional PBKDF2 encryption, perform payments via sphere.payments.send, mint, receive, and requests, communicate via sphere.communications for NIP-17 DMs and sphere.groupChat for NIP-29 group chats, and manage multiple addresses (switchToAddress) and dApp connectivity (ConnectClient/ConnectHost). It handles engine-certified token transfers through the wallet-api vertical, delivering to the recipient's mailbox; it resolves identities using @nametag. The CLI (sphere) provides a shell with auto-completion. The end-to-end flow involves configuring network, storage, and wallet transport via createBrowserProviders and createWalletApiProviders, then initializing Sphere and calling send, receive, or group APIs.
- App developers who want to add on-chain identity, wallet, and payment capabilities to their agents with keys kept local.
- Agent service providers that need self-sovereign payments without local token storage, relying on the backend wallet-api for custody.
- Autonomous commerce agents on Unicity that require private, fast, engine-verified transfers.
- Agents needing combined collaboration features such as group chat (NIP-29), direct messages (NIP-17), and payment requests for ordering.
- dApp developers wanting to integrate with Unicity wallets, using the browser extension via ConnectClient/ConnectHost.
- DevOps teams using the CLI tool to operate wallets in server environments for scripting and automation.
What are this agent's strengths and limitations?
- Keys are generated and stored locally (BIP39/BIP32) and never leave the client; only tokens are custodied on the wallet-api backend.
- Server-side crash-safe payments with engine-certified tokens and resumable transferId semantics to avoid double-pays.
- Built-in group chat (NIP-29) and encrypted direct messages (NIP-17) for agent communication.
- Injectable provider architecture (StoragePort, TransportPort, OracleProvider) and swappable payment transport, allowing platform flexibility.
- Multi-address support (HD wallets) and nametag (@username) resolution for per-address identity.
- Payment settlement is deeply tied to the Unicity network and its wallet-api (platform lock-in); mainnet/dev gateways don't yet support the v2 protocol and send/mint fail.
- Requires network access and an API key for the gateway; the testnet2 key is public, but mainnet requires secret management.
- Server custody means the backend wallet must be trusted, which can be a control risk compared to local storage.
- Documentation is limited, and it's mainly tested on testnet/testnet2; mainnet launch is unverified.
- Although positioned for autonomous agents, there is no built-in LLM integration; developers need to implement agent logic themselves.
How do you install or deploy this agent?
Install the npm package: npm install @unicitylabs/sphere-sdk, and for Node.js add ws. For the CLI, install globally with npm install -g @unicity-sphere/cli.
How do you use this agent?
For browser, initialize Sphere as:
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' });
const { sphere } = await Sphere.init({ ...providers, autoGenerate: true });
Then send payments with sphere.payments.send({ recipient: '@alice', amount: '1000000', coinId: 'UCT' }) and join group chats with sphere.groupChat.connect(). For CLI, run sphere --help.