@dakota-xyz/ts-sdk 1.4.0 → 2.0.0

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.
package/README.md CHANGED
@@ -169,6 +169,76 @@ console.log(`Send ${tx.send_amount} USDC to: ${tx.crypto_address}`);
169
169
  console.log(`Status: ${tx.status}`);
170
170
  ```
171
171
 
172
+ ## Agentic Payments (Alpha)
173
+
174
+ > ⚠️ **Alpha.** The hosted payment-agent surface is `x-alpha` and flag-gated on the platform (endpoints return `404` unless enabled for your key). The SDK helpers below may change — or be removed — without a major-version bump. Not recommended for production.
175
+
176
+ A **payment agent** is a named, customer-scoped signer Dakota can drive: you provision it, endorse it onto a wallet, then it drafts and — once a **mandate** is signed — fires payments, bounded by that customer-approved mandate.
177
+
178
+ ### 1. Provision an agent and endorse it onto a wallet
179
+
180
+ ```typescript
181
+ // Create a hosted payment agent (Dakota custodies its signing key).
182
+ const agent = await client.paymentAgents.create({
183
+ customer_id: customerId,
184
+ name: 'Bill Pay',
185
+ hosted: true,
186
+ });
187
+
188
+ // Grant it spend permission on a wallet by adding its signer to the wallet's
189
+ // spending group (idempotent) — the customer-endorsed attach. Pass an
190
+ // options.idempotencyKey to make the whole helper safely retryable.
191
+ await client.attachUserToWallet(walletId, agent.signer_public_key!, spendingGroupId);
192
+ ```
193
+
194
+ ### 2. Draft payments from natural language
195
+
196
+ ```typescript
197
+ const conv = client.newAgentConversation(agent.id!);
198
+ const turn = await conv.send('Pay Alice 100 USDC on base-mainnet every month until December');
199
+
200
+ if (turn.hasProposals) {
201
+ // Review turn.proposals, then accept them through the instructions flow.
202
+ console.log(`agent drafted ${turn.proposals.length} proposal(s)`);
203
+ } else {
204
+ console.log('agent needs more detail:', turn.reply);
205
+ }
206
+ ```
207
+
208
+ ### 3. Sign and approve a mandate (§8)
209
+
210
+ The caller holds the keys; the SDK never does. `P256MandateSigner` is a ready in-memory signer for sandbox/tests — implement the `MandateSigner` interface over your HSM/KMS in production.
211
+
212
+ ```typescript
213
+ import { P256MandateSigner, mandateSignPayload } from '@dakota-xyz/ts-sdk';
214
+
215
+ const signer = P256MandateSigner.generate(); // or P256MandateSigner.fromPrivateKey(yourKey)
216
+
217
+ // `mandate` comes from client.mandates.get / client.mandates.list.
218
+ const payload = mandateSignPayload(mandate, 'approve');
219
+ const signature = signer.sign(payload);
220
+
221
+ await client.mandates.approve(mandate.id!, {
222
+ approver_public_key: signer.publicKeyBase64(),
223
+ signature,
224
+ });
225
+ ```
226
+
227
+ ### 4. Account insights (read-only)
228
+
229
+ ```typescript
230
+ // Deterministic report: balances, upcoming payments, mandate headroom, risks.
231
+ const report = await client.insights.get(customerId);
232
+
233
+ // Advisory chat over the same report — stateless; never moves money.
234
+ const answer = await client.insights.chat(customerId, {
235
+ messages: [{ role: 'user', content: 'Anything I should know about my account this week?' }],
236
+ });
237
+ console.log(answer.reply);
238
+ ```
239
+
240
+ The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
241
+
172
242
  ## Handling Webhooks
173
243
 
174
244
  Dakota sends webhooks for all status changes. Set up a handler:
@@ -598,6 +668,58 @@ Test simulations (sandbox environment only).
598
668
  | `sandbox.advanceSimulation(id)` | Advance simulation state |
599
669
  | `sandbox.listScenarios(params?)` | List available scenarios |
600
670
 
671
+ ### Payment Agents (Alpha)
672
+
673
+ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
674
+
675
+ | Method | Description |
676
+ |--------|-------------|
677
+ | `paymentAgents.create(data)` | Create a payment agent (hosted or key-supplied) |
678
+ | `paymentAgents.get(id)` | Get payment agent by ID |
679
+ | `paymentAgents.revoke(id)` | Revoke the agent's key (kill switch) |
680
+ | `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
681
+
682
+ ### Mandates (Alpha)
683
+
684
+ The §8 authorizations that arm scheduled payments.
685
+
686
+ | Method | Description |
687
+ |--------|-------------|
688
+ | `mandates.create(data)` | Draft a mandate from a direct user interaction |
689
+ | `mandates.list(params?)` | List mandates (filter by customer/signer/status) |
690
+ | `mandates.get(id)` | Get mandate by ID (full wire shape for signing) |
691
+ | `mandates.approve(id, data)` | Activate with a customer signature |
692
+ | `mandates.cancel(id, data)` | Cancel a mandate |
693
+
694
+ ### Instructions (Alpha)
695
+
696
+ Accept and inspect actuated proposals.
697
+
698
+ | Method | Description |
699
+ |--------|-------------|
700
+ | `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
701
+ | `instructions.get(id)` | Get an instruction + its downstream artifacts |
702
+
703
+ ### Scheduled Payments (Alpha)
704
+
705
+ Schedule rows created from instructions (or directly).
706
+
707
+ | Method | Description |
708
+ |--------|-------------|
709
+ | `scheduledPayments.create(data)` | Create a schedule directly (signer-first) |
710
+ | `scheduledPayments.list(params?)` | List scheduled payments |
711
+ | `scheduledPayments.get(id)` | Get scheduled payment by ID |
712
+ | `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
713
+
714
+ ### Insights (Alpha)
715
+
716
+ Read-only advisory reporting over a customer's agentic activity.
717
+
718
+ | Method | Description |
719
+ |--------|-------------|
720
+ | `insights.get(customerId)` | Deterministic account insight report |
721
+ | `insights.chat(customerId, data)` | Stateless advisory chat over the report |
722
+
601
723
  ---
602
724
 
603
725
  ## Webhook Event Types