valta-sdk 2.1.0 → 2.1.1

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 (2) hide show
  1. package/README.md +176 -98
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,158 +1,236 @@
1
- # Valta SDK
1
+ # valta-sdk
2
2
 
3
- Official TypeScript SDK for [Valta](https://valta.co) - Programmable AI Agent Spending Controls.
4
-
5
- ## Installation
3
+ Official JavaScript/TypeScript SDK for [Valta](https://valta.co) — AI agent financial infrastructure.
6
4
 
5
+ Give your AI agents their own wallets, spending policies, kill switches, and audit logs.
7
6
  ```bash
8
7
  npm install valta-sdk
9
8
  ```
10
9
 
11
- ## Quick Start
10
+ ---
12
11
 
12
+ ## Quick Start
13
13
  ```typescript
14
- import { Valta } from "valta-sdk";
14
+ import Valta from 'valta-sdk';
15
15
 
16
- const valta = new Valta({
17
- apiKey: "sk_valta_...", // Your API key from valta.co/dashboard/api-keys
16
+ const valta = new Valta('vk_live_your_api_key');
17
+
18
+ // Create an agent
19
+ const agent = await valta.agents.create({
20
+ name: 'My Trading Agent',
21
+ type: 'trading',
18
22
  });
19
23
 
20
- // Request agent spending permission
21
- const result = await valta.requestSpend({
22
- agentId: "research-agent",
23
- amount: 20,
24
- category: "api_calls",
25
- description: "Purchase dataset access",
24
+ // Assign a spend policy
25
+ await valta.policies.create({
26
+ agentId: agent.id,
27
+ name: 'Daily limit',
28
+ maxSpendPerDay: 500,
29
+ currency: 'USDC',
26
30
  });
27
31
 
28
- if (result.approved) {
29
- console.log("Approved! TX:", result.tx_id);
30
- } else if (result.requires_approval) {
31
- console.log("Pending human approval:", result.request_id);
32
- } else {
33
- console.log("Denied:", result.reason);
34
- }
35
- ```
32
+ // Check wallet balance
33
+ const wallet = await valta.wallets.get(agent.id);
34
+ console.log(wallet.balance); // { usdc: '245.00' }
36
35
 
37
- ## Features
36
+ // Freeze agent instantly
37
+ await valta.agents.freeze(agent.id);
38
38
 
39
- - **Spending Controls** - Request permission before agents spend money
40
- - **Spending Policies** - Set per-transaction, daily, and monthly limits
41
- - **Human Approval Mode** - Require manual approval above thresholds
42
- - **Kill Switch** - Instantly freeze agent spending
43
- - **Agent Tools** - Configure and execute agent tools
44
- - **Agent Chains** - Create agent-to-agent workflows
45
- - **Balance Queries** - Check wallet balance programmatically
39
+ // Pull immutable audit log
40
+ const logs = await valta.audit.list({ agentId: agent.id });
41
+ ```
46
42
 
47
- ## API Reference
43
+ ---
48
44
 
49
- ### Initialize
45
+ ## Get an API Key
50
46
 
51
- ```typescript
52
- const valta = new Valta({
53
- apiKey: "sk_valta_...",
54
- baseUrl: "https://valta.co", // optional, defaults to production
55
- });
47
+ **Option 1 — Dashboard:**
48
+ 1. Go to [valta.co/dashboard](https://valta.co/dashboard)
49
+ 2. Navigate to API Keys
50
+ 3. Click Generate Key
51
+
52
+ **Option 2 — CLI (no dashboard needed):**
53
+ ```bash
54
+ npx valta-sdk login
56
55
  ```
57
56
 
58
- ### Spending
57
+ ---
59
58
 
60
- ```typescript
61
- // Request a spend action
62
- const result = await valta.requestSpend({
63
- agentId: "my-agent",
64
- amount: 10,
65
- category: "api_calls",
66
- description: "Call external API",
67
- });
59
+ ## CLI
60
+
61
+ The SDK ships with a terminal CLI. Use Valta entirely without a browser.
62
+ ```bash
63
+ # Authenticate
64
+ valta login
65
+
66
+ # List your agents
67
+ valta agents list
68
68
 
69
- // Check balance
70
- const { balance, currency } = await valta.getBalance();
69
+ # Freeze an agent
70
+ valta agents freeze ag_abc123
71
+
72
+ # Log out
73
+ valta logout
71
74
  ```
72
75
 
73
- ### Policies
76
+ ---
74
77
 
78
+ ## Agents
75
79
  ```typescript
76
- // Create a spending policy
77
- const policy = await valta.createPolicy({
78
- agentId: "research-agent",
79
- name: "Research Budget",
80
- dailyLimit: 100,
81
- monthlyLimit: 1000,
82
- maxPerTransaction: 50,
83
- requireApprovalAbove: 25,
84
- allowedCategories: ["api_calls", "datasets"],
80
+ // List all agents
81
+ const { agents } = await valta.agents.list();
82
+
83
+ // Get one agent
84
+ const agent = await valta.agents.get('ag_abc123');
85
+
86
+ // Create an agent
87
+ const agent = await valta.agents.create({
88
+ name: 'Portfolio Watcher',
89
+ type: 'analytics',
85
90
  });
86
91
 
87
- // List all policies
88
- const policies = await valta.listPolicies();
92
+ // Freeze an agent (stops all spending)
93
+ await valta.agents.freeze('ag_abc123');
94
+
95
+ // Unfreeze
96
+ await valta.agents.unfreeze('ag_abc123');
97
+
98
+ // Delete
99
+ await valta.agents.delete('ag_abc123');
89
100
  ```
90
101
 
91
- ### Approvals
102
+ ---
92
103
 
104
+ ## Wallets
93
105
  ```typescript
94
- // Get pending approvals
95
- const pending = await valta.getPendingApprovals();
96
-
97
- // Approve or reject
98
- await valta.approveRequest(requestId);
99
- await valta.rejectRequest(requestId, "Too expensive");
106
+ // Get wallet balance
107
+ const wallet = await valta.wallets.get('ag_abc123');
108
+ // { usdc: '500.00', usdcPending: '0.00' }
109
+
110
+ // Transfer funds between agents
111
+ await valta.wallets.transfer('ag_abc123', {
112
+ toAgentId: 'ag_def456',
113
+ amount: '100.00',
114
+ currency: 'USDC',
115
+ note: 'Fund allocation',
116
+ });
100
117
  ```
101
118
 
102
- ### Kill Switch
119
+ ---
103
120
 
121
+ ## Policies
104
122
  ```typescript
105
- // Freeze an agent immediately
106
- await valta.freezeAgent("rogue-agent", "Suspicious activity detected");
123
+ // Create a spend policy
124
+ await valta.policies.create({
125
+ agentId: 'ag_abc123',
126
+ name: 'Conservative limit',
127
+ maxSpendPerDay: 200,
128
+ maxSpendPerTransaction: 50,
129
+ currency: 'USDC',
130
+ });
107
131
 
108
- // Unfreeze when resolved
109
- await valta.unfreezeAgent("rogue-agent");
132
+ // List policies for an agent
133
+ const policies = await valta.policies.list('ag_abc123');
134
+
135
+ // Update a policy
136
+ await valta.policies.update('pol_xyz', {
137
+ maxSpendPerDay: 500,
138
+ });
110
139
  ```
111
140
 
112
- ### Agent Tools
141
+ ---
113
142
 
143
+ ## Audit Logs
114
144
  ```typescript
115
- // Get tools configured for an agent
116
- const tools = await valta.getAgentTools("my-agent");
117
-
118
- // Toggle a tool on/off
119
- await valta.toggleTool(toolId, false);
145
+ // Get full audit trail for an agent
146
+ const { logs } = await valta.audit.list({
147
+ agentId: 'ag_abc123',
148
+ limit: 50,
149
+ });
120
150
 
121
- // Execute a tool
122
- const result = await valta.executeTool("my-agent", toolId, { query: "data" });
151
+ // Each log entry is immutable and hash-chained
152
+ console.log(logs[0]);
153
+ // {
154
+ // id: 'log_001',
155
+ // action: 'transfer',
156
+ // amount: '100.00',
157
+ // hash: '0xabc...',
158
+ // previousHash: '0xdef...',
159
+ // createdAt: '2026-03-21T...'
160
+ // }
123
161
  ```
124
162
 
125
- ### Agent Chains
163
+ ---
126
164
 
165
+ ## API Keys
127
166
  ```typescript
128
- // Create an agent chain (agent-to-agent workflow)
129
- const chain = await valta.createChain({
130
- name: "Research Pipeline",
131
- steps: [
132
- { order: 1, agent_id: "research", agent_name: "Research Agent", action: "gather_data", input_from: "user" },
133
- { order: 2, agent_id: "analysis", agent_name: "Analysis Agent", action: "analyze", input_from: "previous" },
134
- { order: 3, agent_id: "report", agent_name: "Report Agent", action: "generate_report", input_from: "previous" },
135
- ],
136
- });
167
+ // List your API keys
168
+ const keys = await valta.keys.list();
169
+
170
+ // Create a new key
171
+ const { key } = await valta.keys.create('production');
172
+ console.log(key); // shown once — save it now
137
173
 
138
- // Execute a chain
139
- await valta.executeChain(chain.chain_id);
174
+ // Revoke a key
175
+ await valta.keys.revoke('key_abc123');
140
176
  ```
141
177
 
178
+ ---
179
+
142
180
  ## Error Handling
143
181
 
182
+ The SDK throws typed errors so you always know what went wrong.
144
183
  ```typescript
145
- import { ValtaError } from "valta-sdk";
184
+ import Valta, { AuthError, TierError, RateLimitError } from 'valta-sdk';
146
185
 
147
186
  try {
148
- await valta.requestSpend({ agentId: "agent", amount: 1000 });
149
- } catch (error) {
150
- if (error instanceof ValtaError) {
151
- console.error(`Valta error (${error.status}):`, error.message);
187
+ await valta.agents.create({ name: 'Agent', type: 'trading' });
188
+ } catch (err) {
189
+ if (err instanceof TierError) {
190
+ console.log(`Upgrade required: ${err.requiredTier}`);
191
+ console.log(`Upgrade at: ${err.upgradeUrl}`);
192
+ } else if (err instanceof AuthError) {
193
+ console.log('Invalid API key');
194
+ } else if (err instanceof RateLimitError) {
195
+ console.log('Slow down — rate limit hit');
152
196
  }
153
197
  }
154
198
  ```
155
199
 
200
+ | Error | Status | When |
201
+ |---|---|---|
202
+ | `AuthError` | 401 | Invalid or missing API key |
203
+ | `TierError` | 403 | Feature requires a higher tier |
204
+ | `RateLimitError` | 429 | Too many requests |
205
+ | `NotFoundError` | 404 | Agent/resource not found |
206
+ | `ValtaError` | 5xx | Server error |
207
+
208
+ ---
209
+
210
+ ## Tier Limits
211
+
212
+ | Feature | Free | Builder | Startup | Enterprise |
213
+ |---|---|---|---|---|
214
+ | Agent wallets | 1 | 10 | Unlimited | Unlimited |
215
+ | Policies | 1 | Unlimited | Unlimited | Unlimited |
216
+ | API calls/day | 100 | 1,000 | Unlimited | Unlimited |
217
+ | Audit export | ✗ | ✗ | ✓ | ✓ |
218
+ | Team members | 1 | 1 | 5 | Unlimited |
219
+
220
+ ---
221
+
222
+ ## TypeScript
223
+
224
+ The SDK is written in TypeScript. All types are included — no `@types` package needed.
225
+ ```typescript
226
+ import Valta, { Agent, Policy, WalletBalance } from 'valta-sdk';
227
+
228
+ const agent: Agent = await valta.agents.get('ag_abc123');
229
+ const wallet: WalletBalance = await valta.wallets.get(agent.id);
230
+ ```
231
+
232
+ ---
233
+
156
234
  ## License
157
235
 
158
- MIT
236
+ MIT — built by [Valta](https://valta.co)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "valta-sdk",
3
- "version": "2.1.0",
3
+ "version": "2.1.1",
4
4
  "description": "Official SDK for Valta — AI agent financial infrastructure",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",