[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79807":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},79807,"sphere-sdk","unicity-sphere\u002Fsphere-sdk","unicity-sphere","The SDK for autonomous economic agents. Give an agent an identity, a wallet, and the ability to find, negotiate with, and settle with other agents - peer-to-peer, with perfect privacy and ultra-fast finality","https:\u002F\u002Funicity.ai",null,"TypeScript",5446,99,32,85,0,1,854,3,74.5,"MIT License",false,"main",true,[26,27,28,29],"ai-agents","artificial-intelligence","blockchain","commerce","2026-06-12 04:01:25","# Sphere SDK\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@unicitylabs\u002Fsphere-sdk.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@unicitylabs\u002Fsphere-sdk)\n[![license: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)](.\u002FLICENSE)\n[![node](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D18-brightgreen.svg)](https:\u002F\u002Fnodejs.org)\n\nThe SDK for **autonomous economic agents**. Give an agent an identity, a wallet, and the ability to find, negotiate with, and settle with other agents — peer-to-peer, with perfect privacy and ultra-fast finality.\n\nAn agent using Sphere can hold value, discover a counterparty, message them, trade with them atomically, and invoice and settle - all over peer-to-peer rails where assets are self-contained bearer objects that move directly between parties, carrying their own proof of validity. No broadcast, no mempool, no gas auction.\nIt runs the same way in a browser, in Node.js, and on the command line. \n\n\n---\n\n\n## Install\n\n```bash\nnpm install @unicitylabs\u002Fsphere-sdk\n# Node.js also needs a WebSocket library:\nnpm install @unicitylabs\u002Fsphere-sdk ws\n```\n\n## Why it's built this way\nOn Unicity, assets aren't rows in a global database that validators take turns updating. They're self-contained cryptographic objects — bearer instruments — that carry their own history and validity proofs and move directly between two parties.\n\nThat property is what makes agent-to-agent commerce practical. An autonomous agent can't wait on block space or pay a gas auction for every micro-interaction, and it can't depend on a trusted indexer to know whether it got paid — the proof of the transfer is the payment. Sphere is the client-side toolkit that turns that substrate into the things an agent actually needs: identity, discovery, messaging, trade, and settlement.\n\n## What you can build with it\n\n| Capability | Module | What it gives your agent |\n| --- | --- | --- |\n| **Identity** | `identity` | A cryptographic identity (`@nametag` + secp256k1 keypair)  — HD multi-address, one nametag per address |\n| **Payments** | `payments` | Send and receive bearer tokens  |\n| **Payment requests** | `payments` | Request money from a counterparty and track the response asynchronously |\n| **Invoicing & settlement** | `accounting` | Issue invoices, take payment, and process returns — the bill-and-collect half of commerce |\n| **Discovery** | `market` | Post an intent to transact and search for matching counterparties — how agents *find* each other |\n| **Atomic swaps** | `swap` | Trade peer-to-peer with signed swap manifests and nametag bindings — settle a two-sided deal without a trusted middleman |\n| **Direct messaging** | `communications` | P2P direct messages and broadcasts over Nostr (NIP-04 encryption) |\n| **Group chat** | `groupChat` | NIP-29 relay-based group messaging with roles and moderation |\n| **Token backup** | token sync | Decentralized sync to IPFS\u002FIPNS, browser and Node.js |\n| **dApp ↔ wallet** | Connect | `ConnectClient` \u002F `ConnectHost` for browser-extension integration |\n\n\n\n\n\n## Quick start\n\n```typescript\nimport { Sphere } from '@unicitylabs\u002Fsphere-sdk';\nimport { createBrowserProviders } from '@unicitylabs\u002Fsphere-sdk\u002Fimpl\u002Fbrowser';\n\u002F\u002F Node.js: import { createNodeProviders } from '@unicitylabs\u002Fsphere-sdk\u002Fimpl\u002Fnodejs';\n\n\u002F\u002F 1. Create a wallet (testnet is for experimenting)\nconst { sphere, created, generatedMnemonic } = await Sphere.init({\n  ...createBrowserProviders({ network: 'testnet' }),\n  autoGenerate: true,   \u002F\u002F make a new wallet if one doesn't exist yet\n  nametag: 'alice',     \u002F\u002F claim the Unicity ID @alice (receiving via @alice also needs an on-chain mint — see docs\u002FUNICITY-ID.md)\n});\n\n\u002F\u002F 2. First run? Show the user their recovery phrase to back up.\nif (created && generatedMnemonic) {\n  console.log('Save this recovery phrase:', generatedMnemonic);\n}\n\n\u002F\u002F 3. Who am I?\nconsole.log('My handle: @' + sphere.identity?.nametag);\n\n\u002F\u002F 4. Send 1,000,000 base units to @bob (= 1 UCT when the token has 6 decimals)\nawait sphere.payments.send({\n  recipient: '@bob',\n  coinId: 'UCT',       \u002F\u002F which token to send\n  amount: '1000000',   \u002F\u002F amount in the token's smallest unit, written as a string\n});\n```\n\nThat is a real transfer between two users — verified cryptographically, with no backend of your own required.\n\n> **Getting test tokens.** On testnet you must claim a Unicity ID first, then request from the faucet. See the [Node.js](docs\u002FQUICKSTART-NODEJS.md) and [Browser](docs\u002FQUICKSTART-BROWSER.md) quick‑start guides.\n\n## Core concepts\n\nYou only need four ideas to use the Sphere SDK.\n\n- **Token** — a unit of digital value (like `UCT`). A user's wallet can hold many tokens of different kinds.\n- **Wallet** — created from a 12‑word *recovery phrase*. The phrase is the only thing a user needs to back up; lose it and the wallet is gone.\n- **Unicity ID** — a human‑friendly handle (like `@alice`) that people use to pay or message you. Each wallet can claim one. (In the SDK's API this is the `nametag`.)\n- **Network** — `testnet` for building and experimenting, `mainnet` for real value. Pick one when you create the wallet; everything else is configured for you.\n\nThat's enough to send and receive. Everything below is built on top of these.\n\n## Common tasks\n\n**Send tokens**\n```typescript\nawait sphere.payments.send({ recipient: '@bob', coinId: 'UCT', amount: '1000000' });\n```\n\n**Check balances and holdings**\n```typescript\nconst assets  = await sphere.payments.getAssets();      \u002F\u002F grouped by token, with prices if enabled\nconst tokens  = sphere.payments.getTokens();            \u002F\u002F individual tokens\nconst balance = sphere.payments.getBalance();           \u002F\u002F Asset[] breakdown (synchronous)\nconst usd     = await sphere.payments.getFiatBalance(); \u002F\u002F total in USD, or null if prices are off\n```\n\n**Receive tokens**\n```typescript\nawait sphere.payments.receive();                     \u002F\u002F pull anything sent to you\n\nsphere.on('transfer:incoming', (t) => {\n  console.log(`Got ${t.tokens.length} token(s) from ${t.senderNametag ?? t.senderPubkey}`);\n});\n```\n\n**Request a payment from someone**\n```typescript\nconst req = await sphere.payments.sendPaymentRequest('@bob', {\n  amount: '1000000', coinId: 'UCT', message: 'Invoice #1234',\n});\nconst res = await sphere.payments.waitForPaymentResponse(req.requestId!, 120000);\n```\n\n**Send a direct message**\n```typescript\nawait sphere.communications.sendDM('@alice', 'Hello!');\nsphere.communications.onDirectMessage((m) => console.log(m.senderNametag, m.content));\n```\n\n**Send the ALPHA coin** (Unicity's base‑chain coin)\n```typescript\nconst r = await sphere.payments.l1!.send({ to: 'alpha1...', amount: '100000' \u002F* in satoshis *\u002F });\n```\n\n## Going further\n\nThe root README stays short on purpose. Deeper guides live alongside it:\n\n| You want to… | Read |\n|---|---|\n| Get running in the browser | [docs\u002FQUICKSTART-BROWSER.md](docs\u002FQUICKSTART-BROWSER.md) |\n| Get running in Node.js | [docs\u002FQUICKSTART-NODEJS.md](docs\u002FQUICKSTART-NODEJS.md) |\n| Use Unicity IDs (register, recover, troubleshoot) | [docs\u002FUNICITY-ID.md](docs\u002FUNICITY-ID.md) |\n| Request payments from others | [docs\u002FPAYMENT-REQUESTS.md](docs\u002FPAYMENT-REQUESTS.md) |\n| Send encrypted direct messages | [docs\u002FDIRECT-MESSAGES.md](docs\u002FDIRECT-MESSAGES.md) |\n| Run group chat | [docs\u002FGROUP-CHAT.md](docs\u002FGROUP-CHAT.md) |\n| Send the ALPHA coin | [docs\u002FL1-ALPHA.md](docs\u002FL1-ALPHA.md) |\n| Use multiple addresses per wallet | [docs\u002FMULTI-ADDRESS.md](docs\u002FMULTI-ADDRESS.md) |\n| Configure providers, networks, prices, relays | [docs\u002FPROVIDERS-AND-CONFIG.md](docs\u002FPROVIDERS-AND-CONFIG.md) |\n| Import\u002Fexport wallets and recover legacy files | [docs\u002FWALLET-IMPORT-EXPORT.md](docs\u002FWALLET-IMPORT-EXPORT.md) |\n| Derive keys \u002F sign messages directly (low‑level) | [docs\u002FIDENTITY-CRYPTO.md](docs\u002FIDENTITY-CRYPTO.md) |\n| Let a dApp connect to a wallet | [docs\u002FCONNECT.md](docs\u002FCONNECT.md) |\n| Invoicing and token swaps | [docs\u002FAPI.md](docs\u002FAPI.md) |\n| Full API reference | [docs\u002FAPI.md](docs\u002FAPI.md) |\n| Understand how it actually works under the hood | [ARCHITECTURE.md](ARCHITECTURE.md) |\n| Back up tokens to IPFS | [docs\u002FIPFS-STORAGE.md](docs\u002FIPFS-STORAGE.md) |\n\nThere is also a command‑line tool in a separate package, [`@unicity-sphere\u002Fcli`](https:\u002F\u002Fgithub.com\u002Funicity-sphere\u002Fsphere-cli).\n\n## Glossary\n\n- **Recovery phrase (mnemonic)** — 12 words that *are* the wallet. Back them up; never share them.\n- **Token** — a unit of digital value held in a wallet (e.g. `UCT`).\n- **Unicity ID** — a human‑readable handle for a wallet (e.g. `@alice`). Lowercase letters\u002Fdigits with `-` or `_`, 3–20 characters. Called `nametag` in the SDK's API.\n- **Wallet address** — the machine‑readable address behind a Unicity ID. People rarely type it; they use the handle (e.g. `@alice`).\n- **ALPHA coin** — the coin of Unicity's base blockchain. Sent through `sphere.payments.l1`.\n- **Smallest unit** — token amounts are integers in the token's smallest denomination, passed as strings (so `\"1000000\"`, not `1.0`).\n- **Provider** — a pluggable backend (storage, messaging, etc.). `createBrowserProviders()` \u002F `createNodeProviders()` set these up for you.\n- **Network** — `testnet` (free, for building) or `mainnet` (real value).\n\n## Platforms\n\n| Platform | Storage | Notes |\n|---|---|---|\n| Browser | IndexedDB | Native WebSocket; may need `Buffer`\u002F`process` polyfills — see [bundling notes](docs\u002FPROVIDERS-AND-CONFIG.md#browser-bundling) |\n| Node.js | Files | Requires the `ws` package |\n\n## License\n\nMIT\n","Sphere SDK 是一个为自主经济代理设计的软件开发工具包，赋予代理身份、钱包以及与其他代理进行发现、协商和结算的能力。其核心功能包括通过点对点网络实现完美隐私与超快速交易确认，支持身份认证、支付请求、发票处理、发现匹配对手方、原子交换等功能。技术上基于TypeScript构建，可在浏览器、Node.js及命令行环境中运行一致。适用于需要在去中心化环境下进行高效、安全价值交换的应用场景，如区块链商业应用、人工智能代理等。",2,"2026-06-11 03:58:17","top_topic"]