@paysponge/sdk 0.1.18 → 0.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +86 -39
  2. package/dist/version.d.ts +1 -1
  3. package/dist/version.js +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
- # SpongeWallet SDK
1
+ # Sponge SDK
2
2
 
3
- SDK for creating and managing wallets for AI agents with Claude Agent SDK integration.
3
+ Wallet and platform SDK for agent builders using Sponge.
4
4
 
5
5
  ## Installation
6
6
 
@@ -10,32 +10,69 @@ npm install @paysponge/sdk
10
10
  bun add @paysponge/sdk
11
11
  ```
12
12
 
13
- ## Quick Start
13
+ ## Documentation
14
+
15
+ Full docs: [docs.paysponge.com](https://docs.paysponge.com)
16
+
17
+ - [Welcome](https://docs.paysponge.com)
18
+ - [Platforms](https://docs.paysponge.com/quickstart-platforms)
19
+ - [AI Agents](https://docs.paysponge.com/quickstart-ai-agents)
20
+ - [Self-Registration](https://docs.paysponge.com/quickstart-self-registration)
21
+ - [CLI](https://docs.paysponge.com/cli)
22
+ - [Authentication](https://docs.paysponge.com/authentication)
23
+ - [Wallets & Transfers](https://docs.paysponge.com/wallets-and-transfers)
24
+ - [Claude Integration](https://docs.paysponge.com/claude-integration)
25
+ - [SDK Reference](https://docs.paysponge.com/sdk-reference)
26
+
27
+ ## How Sponge Works
28
+
29
+ Sponge has two SDK clients:
30
+
31
+ - `SpongeWallet`: the agent-scoped runtime client
32
+ - `SpongePlatform`: the platform control-plane client for creating and managing many agents
33
+
34
+ Use `SpongeWallet` when one agent is acting with its own wallet. Use `SpongePlatform` when your backend needs to provision agents, rotate keys, or manage a fleet.
35
+
36
+ ## Agent Keys
37
+
38
+ Agent API keys are scoped to one agent. Use them with `SpongeWallet`.
39
+
40
+ You can get an agent-scoped API key in a few ways:
41
+
42
+ - from the dashboard for an existing agent
43
+ - `npx spongewallet init` to create an agent immediately and claim it later
44
+ - `SpongeWallet.connect()` device flow if you want browser auth and cached local credentials
45
+ - `SpongePlatform.createAgent()` if your platform is provisioning agents server-side
46
+ - `POST /api/agents/register` for self-registration flows
47
+
48
+ Example:
14
49
 
15
50
  ```typescript
16
51
  import { SpongeWallet } from "@paysponge/sdk";
17
52
 
18
- // Connect (handles auth automatically via browser)
19
- const wallet = await SpongeWallet.connect();
53
+ const wallet = await SpongeWallet.connect({
54
+ apiKey: process.env.SPONGE_API_KEY,
55
+ });
20
56
 
21
- // Get addresses
22
57
  const addresses = await wallet.getAddresses();
23
- console.log(addresses.base); // 0x...
24
- console.log(addresses.solana); // 5x...
25
-
26
- // Check balances
27
- const balances = await wallet.getBalances();
28
-
29
- // Transfer tokens
30
- await wallet.transfer({
31
- chain: "base",
32
- to: "0x...",
33
- amount: "10",
34
- currency: "USDC",
35
- });
58
+ console.log(addresses.base);
59
+ console.log(await wallet.getBalances());
36
60
  ```
37
61
 
38
- ## Platforms
62
+ ## Platform Keys
63
+
64
+ Platform API keys are account-level keys with the `sponge_master_...` prefix. Create them in Dashboard -> Settings -> Master API Keys, then use them with `SpongePlatform`.
65
+
66
+ Platform keys are for control-plane actions:
67
+
68
+ - create agents
69
+ - list and update agents
70
+ - rotate agent API keys
71
+ - manage many agents from one backend
72
+
73
+ Each agent still gets its own runtime API key. Your platform backend should use the platform key to provision agents, then store the returned agent key per agent and use that key at runtime.
74
+
75
+ Example:
39
76
 
40
77
  ```typescript
41
78
  import { SpongePlatform } from "@paysponge/sdk";
@@ -52,13 +89,27 @@ const wallet = await platform.connectAgent({ apiKey });
52
89
  console.log(agent.id, await wallet.getAddresses());
53
90
  ```
54
91
 
92
+ ## Platforms
93
+
94
+ If you are building a product that manages hundreds of agents, the intended pattern is:
95
+
96
+ 1. Your backend authenticates with `SpongePlatform` using a platform key.
97
+ 2. It creates one Sponge agent per user, bot, or worker.
98
+ 3. It stores the returned agent API key with your own internal record.
99
+ 4. Each running agent connects with `SpongeWallet` using its own agent key.
100
+
101
+ That keeps provisioning and runtime separate:
102
+
103
+ - platform key: create and administer agents
104
+ - agent key: spend, swap, transfer, MCP, and tools for one agent
105
+
55
106
  ## Authentication
56
107
 
57
108
  ### Device Flow (Browser)
58
109
 
59
110
  On first run, `connect()` opens your browser for login. After approval, credentials are cached at `~/.spongewallet/credentials.json`.
60
111
 
61
- ### API Key
112
+ ### Agent API Key
62
113
 
63
114
  ```typescript
64
115
  const wallet = await SpongeWallet.connect({
@@ -72,6 +123,14 @@ Or via environment variable:
72
123
  SPONGE_API_KEY=sponge_test_xxx node my-bot.js
73
124
  ```
74
125
 
126
+ ### Platform API Key
127
+
128
+ ```typescript
129
+ const platform = await SpongePlatform.connect({
130
+ apiKey: process.env.SPONGE_MASTER_KEY,
131
+ });
132
+ ```
133
+
75
134
  ## Claude Agent SDK Integration
76
135
 
77
136
  ```typescript
@@ -94,8 +153,10 @@ for await (const msg of query({
94
153
 
95
154
  ## Supported Chains
96
155
 
97
- - **EVM**: Ethereum, Base, Monad, Sepolia, Base Sepolia, Tempo
98
- - **Solana**: Mainnet, Devnet
156
+ - Ethereum
157
+ - Base
158
+ - Tempo
159
+ - Solana
99
160
 
100
161
  ## Features
101
162
 
@@ -104,22 +165,7 @@ for await (const msg of query({
104
165
  - MCP server for Claude Agent SDK
105
166
  - Anthropic SDK tool definitions
106
167
  - Spending limits and allowlists
107
- - x402 payment protocol support
108
-
109
- ## Documentation
110
-
111
- Full docs: [docs.paysponge.com](https://docs.paysponge.com)
112
-
113
- - [Welcome](https://docs.paysponge.com)
114
- - [Self-Registration](https://docs.paysponge.com/quickstart-self-registration)
115
- - [Platforms](https://docs.paysponge.com/quickstart-platforms)
116
- - [AI Agents](https://docs.paysponge.com/quickstart-ai-agents)
117
- - [Trading & Payments](https://docs.paysponge.com/quickstart-trading)
118
- - [CLI](https://docs.paysponge.com/cli)
119
- - [Authentication](https://docs.paysponge.com/authentication)
120
- - [Wallets & Transfers](https://docs.paysponge.com/wallets-and-transfers)
121
- - [Claude Integration](https://docs.paysponge.com/claude-integration)
122
- - [SDK Reference](https://docs.paysponge.com/sdk-reference)
168
+ - x402 and MPP payment protocol support
123
169
 
124
170
  ## CLI
125
171
 
@@ -156,6 +202,7 @@ npx spongewallet logout
156
202
  | Variable | Description |
157
203
  |----------|-------------|
158
204
  | `SPONGE_API_KEY` | Agent API key (skips device flow) |
205
+ | `SPONGE_MASTER_KEY` | Platform API key for `SpongePlatform` |
159
206
  | `SPONGE_API_URL` | Custom API URL |
160
207
 
161
208
  ## License
package/dist/version.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export declare const SDK_VERSION = "0.1.18";
1
+ export declare const SDK_VERSION = "0.1.19";
2
2
  //# sourceMappingURL=version.d.ts.map
package/dist/version.js CHANGED
@@ -1,2 +1,2 @@
1
- export const SDK_VERSION = "0.1.18";
1
+ export const SDK_VERSION = "0.1.19";
2
2
  //# sourceMappingURL=version.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paysponge/sdk",
3
- "version": "0.1.18",
3
+ "version": "0.1.19",
4
4
  "type": "module",
5
5
  "description": "SDK for spinning up wallets for AI agents with Claude Agent SDK integration",
6
6
  "main": "./dist/index.js",