@dakota-xyz/ts-sdk 2.2.1 → 3.2.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 +274 -42
- package/dist/index.d.mts +6652 -1542
- package/dist/index.d.ts +6652 -1542
- package/dist/index.js +568 -77
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +568 -77
- package/dist/index.mjs.map +1 -1
- package/dist/webhook/index.d.mts +176 -1
- package/dist/webhook/index.d.ts +176 -1
- package/dist/webhook/index.js +7 -0
- package/dist/webhook/index.js.map +1 -1
- package/dist/webhook/index.mjs +7 -0
- package/dist/webhook/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -169,9 +169,13 @@ console.log(`Send ${tx.send_amount} USDC to: ${tx.crypto_address}`);
|
|
|
169
169
|
console.log(`Status: ${tx.status}`);
|
|
170
170
|
```
|
|
171
171
|
|
|
172
|
-
|
|
172
|
+
A one-off also takes `developer_fee_fixed` (a decimal string in units of the
|
|
173
|
+
asset deposited). The depositor must then send the destination amount plus
|
|
174
|
+
the fee, and a deposit that does not cover it is not converted.
|
|
173
175
|
|
|
174
|
-
|
|
176
|
+
## Agentic Payments (Beta)
|
|
177
|
+
|
|
178
|
+
> ⚠️ **Beta.** The hosted payment-agent surface is `x-beta` 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
179
|
|
|
176
180
|
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
181
|
|
|
@@ -230,11 +234,9 @@ await client.mandates.approve(mandate.id!, {
|
|
|
230
234
|
// Deterministic report: balances, upcoming payments, mandate headroom, risks.
|
|
231
235
|
const report = await client.insights.get(customerId);
|
|
232
236
|
|
|
233
|
-
//
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
});
|
|
237
|
-
console.log(answer.reply);
|
|
237
|
+
// The same, over your WHOLE book: portfolio KPIs with trend deltas, daily
|
|
238
|
+
// series for charts, and a per-customer roll-up sorted worst-first.
|
|
239
|
+
const portfolio = await client.insights.getClientReport({ severity: 'critical,warn' });
|
|
238
240
|
```
|
|
239
241
|
|
|
240
242
|
The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
|
|
@@ -301,7 +303,10 @@ const firstCustomer = await client.customers.list().first();
|
|
|
301
303
|
// With filters
|
|
302
304
|
const activeCustomers = client.customers.list({ kyb_status: 'active' });
|
|
303
305
|
|
|
304
|
-
// Iterate transactions with filters
|
|
306
|
+
// Iterate transactions with filters. The SDK always names the transaction
|
|
307
|
+
// family on the wire, so this is that customer's ONE-OFF transactions — a
|
|
308
|
+
// raw GET /transactions?customer_id=... would infer the auto_account family
|
|
309
|
+
// and return those instead.
|
|
305
310
|
const completedTxs = client.transactions.list({
|
|
306
311
|
customer_id: customerId,
|
|
307
312
|
status: 'completed',
|
|
@@ -324,6 +329,18 @@ try {
|
|
|
324
329
|
if (error.retryable) {
|
|
325
330
|
// Safe to retry (429, 503, etc.)
|
|
326
331
|
}
|
|
332
|
+
|
|
333
|
+
// Showing the error to a PERSON? `message` names request fields and
|
|
334
|
+
// actions so a machine caller can self-correct. `userMessage` says the
|
|
335
|
+
// same thing without API vocabulary, when the problem carries one.
|
|
336
|
+
showToCustomer(error.userMessage ?? error.message);
|
|
337
|
+
|
|
338
|
+
// Some problems carry a link that CLEARS them — today `terms-not-accepted`
|
|
339
|
+
// points at the hosted flow where the agreement can be signed. It is
|
|
340
|
+
// token-gated and usable as-is.
|
|
341
|
+
if (error.resolutionUrl) {
|
|
342
|
+
offerLink(error.resolutionUrl);
|
|
343
|
+
}
|
|
327
344
|
}
|
|
328
345
|
|
|
329
346
|
if (error instanceof TransportError) {
|
|
@@ -408,7 +425,6 @@ agentic endpoints that call a model default to **180s** instead:
|
|
|
408
425
|
|---|---|
|
|
409
426
|
| Everything else | 15s |
|
|
410
427
|
| `paymentAgents.createProposals` / `AgentConversation.send` | 180s |
|
|
411
|
-
| `insights.chat` | 180s |
|
|
412
428
|
|
|
413
429
|
A drafting turn is a sequence of model calls — read the payees, check
|
|
414
430
|
balances, draft, revise — so "pay these nine vendors every Friday"
|
|
@@ -531,15 +547,50 @@ Manage customer entities representing businesses and organizations.
|
|
|
531
547
|
|--------|-------------|
|
|
532
548
|
| `customers.create(data)` | Create a customer (triggers KYB) |
|
|
533
549
|
| `customers.list(params?)` | List all customers (paginated) |
|
|
550
|
+
| `customers.listPage(params?)` | One page + `status_counts` for a status header |
|
|
534
551
|
| `customers.get(id)` | Get customer by ID |
|
|
535
552
|
| `customers.delete(id)` | Soft-delete a customer (blocked if it has accounts) |
|
|
536
553
|
| `customers.getCapabilities(id)` | Capabilities + outstanding requirements to unlock each |
|
|
537
554
|
| `customers.reEngage(id)` | Mint a fresh application link for an approved customer |
|
|
555
|
+
| `customers.withdrawApplication(id, applicationId, data?)` | Withdraw an undecided onboarding application (final) |
|
|
538
556
|
| `customers.bulkImportFromSumsubTokens(data)` | Import from Sumsub share tokens (synchronous) |
|
|
539
557
|
| `customers.importPersonaTokens(data)` | Import from Persona Connect share tokens (async job) |
|
|
540
558
|
| `customers.listPersonaImportJobs(params?)` | List Persona import jobs, newest first |
|
|
541
559
|
| `customers.getPersonaImportJob(jobId, params?)` | Job status + per-token results |
|
|
542
560
|
|
|
561
|
+
`Customer.status` is the single client-facing status — one value collapsing the
|
|
562
|
+
frozen state, the application decision, and the application lifecycle. Filter on
|
|
563
|
+
it with `status`, which takes a **comma-separated string**, not an array:
|
|
564
|
+
|
|
565
|
+
```typescript
|
|
566
|
+
const needsAttention = client.customers.list({ status: 'info_requested,frozen' });
|
|
567
|
+
|
|
568
|
+
// `list()` iterates rows and drops the envelope, so the per-status counts a
|
|
569
|
+
// dashboard header renders come from `listPage()` instead. They are computed
|
|
570
|
+
// ignoring the `status` selection, so every chip keeps its count while one of
|
|
571
|
+
// them is the active filter.
|
|
572
|
+
const page = await client.customers.listPage({ limit: 25 });
|
|
573
|
+
console.log(page.status_counts?.info_requested ?? 0);
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
`kyb_statuses`, `kyc_statuses` and `application_statuses` take the same
|
|
577
|
+
comma-separated form, and `sort_by` / `sort_dir` / `created_at_from` /
|
|
578
|
+
`created_at_to` are also accepted.
|
|
579
|
+
|
|
580
|
+
When a customer will not or cannot continue onboarding — after a request for
|
|
581
|
+
information they chose not to answer, say — withdraw the application rather
|
|
582
|
+
than leaving it open:
|
|
583
|
+
|
|
584
|
+
```typescript
|
|
585
|
+
await client.customers.withdrawApplication(customerId, applicationId, {
|
|
586
|
+
reason: 'Customer opted not to proceed',
|
|
587
|
+
});
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
Withdrawal is **final**: the customer's `status` becomes `withdrawn`, and
|
|
591
|
+
onboarding them again needs a new application. An application that already has
|
|
592
|
+
a decision answers **409**. The platform emits `customer.application.withdrawn`.
|
|
593
|
+
|
|
543
594
|
### Recipients
|
|
544
595
|
|
|
545
596
|
Manage recipient entities for payouts and transfers.
|
|
@@ -569,7 +620,17 @@ Manage on-ramp, off-ramp, and swap accounts.
|
|
|
569
620
|
| `accounts.create(data)` | Create account (onramp/offramp/swap) |
|
|
570
621
|
| `accounts.list(params?)` | List accounts |
|
|
571
622
|
| `accounts.get(id)` | Get account by ID |
|
|
572
|
-
| `accounts.update(id, data)` | Update account |
|
|
623
|
+
| `accounts.update(id, data)` | Update account (developer fee only) |
|
|
624
|
+
|
|
625
|
+
A developer fee is either `developer_fee_bps` or `developer_fee_fixed`. The
|
|
626
|
+
platform returns a 400 if a request carries both keys, even with
|
|
627
|
+
`developer_fee_bps: 0`, so leave out the one you are not using. On update,
|
|
628
|
+
setting one replaces the other. `developer_fee_fixed` is a decimal **string**
|
|
629
|
+
such as `'10.00'`, in units of the asset deposited (at most 2 decimals,
|
|
630
|
+
greater than 0). Fixed-fee accounts return `developer_fee_fixed` and
|
|
631
|
+
`minimum_deposit` (the fee plus 0.01); both are omitted otherwise. Some
|
|
632
|
+
routes do not support a fixed fee, and the platform answers those with a 400
|
|
633
|
+
that asks for `developer_fee_bps` instead.
|
|
573
634
|
|
|
574
635
|
### Transactions
|
|
575
636
|
|
|
@@ -578,10 +639,25 @@ Create and manage one-off transactions.
|
|
|
578
639
|
| Method | Description |
|
|
579
640
|
|--------|-------------|
|
|
580
641
|
| `transactions.create(data)` | Create one-off transaction |
|
|
581
|
-
| `transactions.list(params?)` | List transactions |
|
|
642
|
+
| `transactions.list(params?)` | List transactions (see the family table below) |
|
|
582
643
|
| `transactions.get(id)` | Get transaction by ID |
|
|
583
644
|
| `transactions.cancel(id)` | Cancel pending transaction |
|
|
584
645
|
|
|
646
|
+
`GET /transactions` serves three resource families from one path, and the
|
|
647
|
+
family decides the row shape. `list()` names the family on the wire and types
|
|
648
|
+
its rows to match:
|
|
649
|
+
|
|
650
|
+
| `transaction_type` | Yields | Notes |
|
|
651
|
+
|--------------------|--------|-------|
|
|
652
|
+
| omitted or `'one_off'` | `OneOffTransaction` | The default |
|
|
653
|
+
| `'wallet'` | `WalletTransaction` | Required for the `wallet_id` / `direction` filters |
|
|
654
|
+
| `'auto_account'` | `AutoTransaction` | Requires `customer_id` |
|
|
655
|
+
|
|
656
|
+
Left to the server the family is **inferred** from the other filters, and
|
|
657
|
+
`customer_id` on its own infers `auto_account` — so name it, or let the SDK
|
|
658
|
+
name `one_off` for you. If a response reports a family other than the one
|
|
659
|
+
requested, the iterator throws rather than yielding rows of the wrong shape.
|
|
660
|
+
|
|
585
661
|
### Auto Transactions
|
|
586
662
|
|
|
587
663
|
View automated transaction configurations.
|
|
@@ -713,18 +789,104 @@ Query platform capabilities.
|
|
|
713
789
|
| `info.getCountries()` | Get supported countries |
|
|
714
790
|
| `info.getNetworks()` | Get supported networks |
|
|
715
791
|
|
|
792
|
+
### Legal Documents
|
|
793
|
+
|
|
794
|
+
The published terms a customer accepts during onboarding. **Unauthenticated** —
|
|
795
|
+
integrators need these before a customer relationship exists, so both calls are
|
|
796
|
+
safe from a signup page.
|
|
797
|
+
|
|
798
|
+
| Method | Description |
|
|
799
|
+
|--------|-------------|
|
|
800
|
+
| `legal.list()` | The in-force revision of every document, WITHOUT the text |
|
|
801
|
+
| `legal.get(key, version?)` | One document's text — the in-force revision, or a specific one |
|
|
802
|
+
|
|
803
|
+
```typescript
|
|
804
|
+
const tos = await client.legal.get('dakota_tos');
|
|
805
|
+
render(tos.content);
|
|
806
|
+
|
|
807
|
+
// Record what the customer actually saw, not whichever revision was current
|
|
808
|
+
// when the request landed.
|
|
809
|
+
await client.applications.submitAttestation(applicationId, {
|
|
810
|
+
attestation_type: 'terms_of_service',
|
|
811
|
+
legal_document_version: tos.version,
|
|
812
|
+
// ...
|
|
813
|
+
});
|
|
814
|
+
```
|
|
815
|
+
|
|
816
|
+
A revision is immutable, so a fetched `(key, version)` can be cached forever.
|
|
817
|
+
`legal.list()` is not: it names whichever revision is in force *now*.
|
|
818
|
+
|
|
819
|
+
To render an acceptance page, `applications.getLegalAcceptance(applicationId)`
|
|
820
|
+
returns just what that page needs — the agreements still owed and the people
|
|
821
|
+
permitted to accept them — instead of the full KYB record `applications.get()`
|
|
822
|
+
would return. The link that reaches it is emailed, so its token is scoped to
|
|
823
|
+
this call and the attestation submission.
|
|
824
|
+
|
|
825
|
+
### RD Marketing Fee
|
|
826
|
+
|
|
827
|
+
Reserve-management statements for the calling client. The client comes from the
|
|
828
|
+
session, so there is no id to pass.
|
|
829
|
+
|
|
830
|
+
| Method | Description |
|
|
831
|
+
|--------|-------------|
|
|
832
|
+
| `rdMarketingFee.listMonths()` | The months with a statement, newest first |
|
|
833
|
+
| `rdMarketingFee.getStatement(month)` | One month, one row per calendar day |
|
|
834
|
+
| `rdMarketingFee.getPayoutDestination()` | The wallet the fee is paid to (404 = none yet) |
|
|
835
|
+
| `rdMarketingFee.setPayoutDestination(data)` | Register or replace it — an EVM address on Base |
|
|
836
|
+
|
|
837
|
+
```typescript
|
|
838
|
+
const months = await client.rdMarketingFee.listMonths();
|
|
839
|
+
const statement = await client.rdMarketingFee.getStatement(months[0]);
|
|
840
|
+
|
|
841
|
+
for (const day of statement.daily) {
|
|
842
|
+
// Absent is not zero: absent means the day is not derived yet, '0' means
|
|
843
|
+
// the client genuinely held no RD. Do not render them alike.
|
|
844
|
+
console.log(day.date, day.balance_minor ?? 'not yet derived');
|
|
845
|
+
}
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
A client with no contract gets a **404**; an empty month list means the
|
|
849
|
+
contract is real but starts later. The running month is included, with its fee
|
|
850
|
+
figures absent rather than zero.
|
|
851
|
+
|
|
852
|
+
Each statement carries both rates: `y_bps_annual` is the contract rate as the
|
|
853
|
+
Order Form quotes it, and `y_bps_monthly` is what THIS month was charged at
|
|
854
|
+
(annual × days in month / 365, to 2 decimal places), so a client can check the
|
|
855
|
+
month against the rate they signed.
|
|
856
|
+
|
|
857
|
+
The fee is paid to a wallet you register separately from your developer-fee
|
|
858
|
+
destination — RD exists only on Base, so only the address is a parameter:
|
|
859
|
+
|
|
860
|
+
```typescript
|
|
861
|
+
const dest = await client.rdMarketingFee.setPayoutDestination({
|
|
862
|
+
address: '0x1234567890123456789012345678901234567890',
|
|
863
|
+
});
|
|
864
|
+
console.log(dest.chain); // always 'eip155:8453'
|
|
865
|
+
```
|
|
866
|
+
|
|
867
|
+
`getPayoutDestination()` answers **404** while nothing is registered — the
|
|
868
|
+
ordinary state for a new client, not an error — and **403** when the client is
|
|
869
|
+
not in the programme. A change emits `rd_payout_destination.updated`.
|
|
870
|
+
|
|
716
871
|
### Sandbox
|
|
717
872
|
|
|
718
873
|
Test simulations (sandbox environment only).
|
|
719
874
|
|
|
720
875
|
| Method | Description |
|
|
721
876
|
|--------|-------------|
|
|
722
|
-
| `sandbox.simulateInbound(data)` | Simulate
|
|
877
|
+
| `sandbox.simulateInbound(data)` | Simulate a deposit, an outbound settlement/return, or a reversal |
|
|
723
878
|
| `sandbox.simulateOnboarding(data)` | Simulate KYB completion |
|
|
724
879
|
| `sandbox.getSimulation(id)` | Get simulation by ID |
|
|
725
880
|
| `sandbox.advanceSimulation(id)` | Advance simulation state |
|
|
726
881
|
| `sandbox.listScenarios(params?)` | List available scenarios |
|
|
727
882
|
|
|
883
|
+
`simulateInbound` covers every fiat rail — `ach_*`, `fedwire_*`, `swift_*`,
|
|
884
|
+
`fednow_inbound` — plus `crypto_inbound`. Inbound types take the receiving
|
|
885
|
+
`account_id`; outbound and reversal types take the funding offramp `account_id`
|
|
886
|
+
AND the `one_off_transaction_id`. A SWIFT deposit is chosen by the ACCOUNT, not
|
|
887
|
+
the type: `swift_inbound` and `fedwire_inbound` both book as SWIFT against a
|
|
888
|
+
SWIFT onramp account and as Fedwire against a domestic one.
|
|
889
|
+
|
|
728
890
|
### Fee Payout Destination
|
|
729
891
|
|
|
730
892
|
Where Dakota pays your accrued developer fees. Exactly one per organization,
|
|
@@ -745,9 +907,9 @@ await client.feePayoutDestination.set({
|
|
|
745
907
|
});
|
|
746
908
|
```
|
|
747
909
|
|
|
748
|
-
### Payment Agents (
|
|
910
|
+
### Payment Agents (Beta)
|
|
749
911
|
|
|
750
|
-
Hosted signing agents that draft payments (`x-
|
|
912
|
+
Hosted signing agents that draft payments (`x-beta`, flag-gated).
|
|
751
913
|
|
|
752
914
|
| Method | Description |
|
|
753
915
|
|--------|-------------|
|
|
@@ -757,7 +919,7 @@ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
|
|
|
757
919
|
| `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
|
|
758
920
|
| `paymentAgents.getProposalsProgress(id)` | Live progress of an in-flight drafting turn (advisory) |
|
|
759
921
|
|
|
760
|
-
### Agentic Policy (
|
|
922
|
+
### Agentic Policy (Beta)
|
|
761
923
|
|
|
762
924
|
How your product speaks, and what the agent may propose for it. Register it
|
|
763
925
|
once and every drafting turn narrates in your nouns instead of the platform's.
|
|
@@ -777,11 +939,56 @@ await client.agenticPolicy.set({
|
|
|
777
939
|
```
|
|
778
940
|
|
|
779
941
|
It is a **full replace, not a merge** — an omitted field means you no longer
|
|
780
|
-
want it.
|
|
781
|
-
development override: forgetting it fails *silently*, and the agent quietly
|
|
782
|
-
goes back to saying "destination" and "mandate".
|
|
942
|
+
want it.
|
|
783
943
|
|
|
784
|
-
|
|
944
|
+
Your developer fee is separate, and belongs in **both** places:
|
|
945
|
+
|
|
946
|
+
```typescript
|
|
947
|
+
// The drafting turn — this is what lets the agent MENTION the fee.
|
|
948
|
+
const conv = client.newAgentConversation(agentId, {
|
|
949
|
+
developerFeeDefaults: {
|
|
950
|
+
swap: { developer_fee_bps: 50 },
|
|
951
|
+
offramp: { developer_fee_bps: 25 },
|
|
952
|
+
},
|
|
953
|
+
});
|
|
954
|
+
|
|
955
|
+
// The accept — this is what CHARGES it.
|
|
956
|
+
await client.instructions.create({
|
|
957
|
+
payment_agent_id: agentId,
|
|
958
|
+
proposals: turn.proposals,
|
|
959
|
+
developer_fee_defaults: {
|
|
960
|
+
swap: { developer_fee_bps: 50 },
|
|
961
|
+
offramp: { developer_fee_bps: 25 },
|
|
962
|
+
},
|
|
963
|
+
});
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
Declare it only on the accept and the customer approves a summary that never
|
|
967
|
+
disclosed a fee, then gets charged it.
|
|
968
|
+
|
|
969
|
+
Each payout type takes a percentage (`developer_fee_bps`) **or** a flat amount
|
|
970
|
+
per payment (`developer_fee_fixed`), never both. The fixed fee is a decimal
|
|
971
|
+
string in units of the asset deposited, and it is added on top of the payment,
|
|
972
|
+
so the payee receives exactly the amount named: a 100.00 USDC payment with
|
|
973
|
+
`{ developer_fee_fixed: '10.00' }` leaves the wallet as 110.00 USDC, and the
|
|
974
|
+
spending limit applies to that 110.00. The `create_auto_account` action takes
|
|
975
|
+
either one too, as an override of the defaults.
|
|
976
|
+
|
|
977
|
+
```typescript
|
|
978
|
+
const defaults: DeveloperFeeDefaults = {
|
|
979
|
+
swap: { developer_fee_fixed: '10.00' }, // 10.00 USDC on a USDC payment
|
|
980
|
+
offramp: { developer_fee_bps: 25 },
|
|
981
|
+
};
|
|
982
|
+
```
|
|
983
|
+
|
|
984
|
+
Registering is the **only** way to set a policy. It belongs to the client, not
|
|
985
|
+
to a request, so a drafting turn and the accept that follows it cannot be
|
|
986
|
+
judged by different rules. The per-conversation `clientPolicy` option is gone:
|
|
987
|
+
the platform stopped reading `client_policy` from request bodies, and
|
|
988
|
+
one sent there is ignored — the agent quietly goes back to saying "destination"
|
|
989
|
+
and "mandate" with nothing reporting the fallback.
|
|
990
|
+
|
|
991
|
+
### Mandates (Beta)
|
|
785
992
|
|
|
786
993
|
The §8 authorizations that arm scheduled payments.
|
|
787
994
|
|
|
@@ -796,7 +1003,7 @@ The §8 authorizations that arm scheduled payments.
|
|
|
796
1003
|
| `mandates.listVersions(id)` | Append-only version history, oldest first |
|
|
797
1004
|
| `mandates.getBudget(id)` | Remaining budget: spent, earmarked, left (advisory) |
|
|
798
1005
|
|
|
799
|
-
### Instructions (
|
|
1006
|
+
### Instructions (Beta)
|
|
800
1007
|
|
|
801
1008
|
Accept and inspect actuated proposals.
|
|
802
1009
|
|
|
@@ -805,7 +1012,7 @@ Accept and inspect actuated proposals.
|
|
|
805
1012
|
| `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
|
|
806
1013
|
| `instructions.get(id)` | Get an instruction + its downstream artifacts |
|
|
807
1014
|
|
|
808
|
-
### Scheduled Payments (
|
|
1015
|
+
### Scheduled Payments (Beta)
|
|
809
1016
|
|
|
810
1017
|
Schedule rows created from instructions (or directly).
|
|
811
1018
|
|
|
@@ -816,39 +1023,64 @@ Schedule rows created from instructions (or directly).
|
|
|
816
1023
|
| `scheduledPayments.get(id)` | Get scheduled payment by ID |
|
|
817
1024
|
| `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
|
|
818
1025
|
|
|
819
|
-
### Insights (
|
|
1026
|
+
### Insights (Beta)
|
|
820
1027
|
|
|
821
1028
|
Read-only advisory reporting over a customer's agentic activity.
|
|
822
1029
|
|
|
823
1030
|
| Method | Description |
|
|
824
1031
|
|--------|-------------|
|
|
825
|
-
| `insights.get(customerId)` | Deterministic account insight report |
|
|
826
|
-
| `insights.
|
|
1032
|
+
| `insights.get(customerId)` | Deterministic account insight report for one customer |
|
|
1033
|
+
| `insights.getClientReport(params?)` | The same over the whole book: KPIs, daily series, per-customer roll-up |
|
|
1034
|
+
|
|
1035
|
+
`getClientReport` filters (`customer_id`, `wallet_id`, `kind`, `severity`,
|
|
1036
|
+
`responsibility`, `window_days`) are all optional and only narrow the report;
|
|
1037
|
+
the multi-value ones are comma-separated strings. Items gain `customer_id`
|
|
1038
|
+
(omitted on cross-customer aggregates) and `responsibility` — a grouping label
|
|
1039
|
+
for routing, not ownership. `kind` stays an OPEN set; two kinds are emitted
|
|
1040
|
+
only at this scope today, `volume_anomaly` and `recipient_dormant`. The report
|
|
1041
|
+
scans at most 100 customers per request and says so through
|
|
1042
|
+
`snapshot.customers.scanned < total`.
|
|
827
1043
|
|
|
828
1044
|
---
|
|
829
1045
|
|
|
830
1046
|
## Webhook Event Types
|
|
831
1047
|
|
|
1048
|
+
Every value the platform's `EventType` enum lists — and therefore every value
|
|
1049
|
+
a webhook target can subscribe to — is a member of `WebhookEventType`; a test
|
|
1050
|
+
keeps the two in step on every spec sync. Names not in this table (for
|
|
1051
|
+
example `transaction.completed` or `application.approved`) are never emitted:
|
|
1052
|
+
a transaction's outcome arrives as an `*.updated` event with the new status,
|
|
1053
|
+
and an application decision arrives as `customer.kyb_status.updated`.
|
|
1054
|
+
|
|
832
1055
|
| Event Type | Description |
|
|
833
1056
|
|------------|-------------|
|
|
834
|
-
| `
|
|
835
|
-
| `
|
|
836
|
-
| `customer.
|
|
837
|
-
| `
|
|
838
|
-
| `
|
|
839
|
-
| `
|
|
840
|
-
| `
|
|
841
|
-
| `
|
|
842
|
-
| `
|
|
843
|
-
| `
|
|
844
|
-
| `
|
|
845
|
-
| `transaction.
|
|
846
|
-
| `transaction.
|
|
847
|
-
| `
|
|
848
|
-
| `
|
|
849
|
-
| `
|
|
850
|
-
| `
|
|
851
|
-
| `
|
|
1057
|
+
| `user.created` / `user.updated` / `user.deleted` | Dashboard user lifecycle |
|
|
1058
|
+
| `api_key.created` / `api_key.deleted` | API key lifecycle |
|
|
1059
|
+
| `customer.created` / `customer.updated` | Customer record lifecycle |
|
|
1060
|
+
| `customer.kyb_link.created` / `customer.kyb_link.updated` | Onboarding link issued or changed |
|
|
1061
|
+
| `customer.kyb_status.created` / `customer.kyb_status.updated` | KYB status set or changed (an application decision arrives here) |
|
|
1062
|
+
| `customer.kyb_application.submitted` | The customer submitted their onboarding application |
|
|
1063
|
+
| `customer.capability_status.updated` | A rail's standing changed; payload lists what still gates it |
|
|
1064
|
+
| `customer.rfi.requested` | A reviewer needs more information; payload lists what is owed (never the link) |
|
|
1065
|
+
| `customer.rfi.responded` | The information arrived; the application is back in review |
|
|
1066
|
+
| `customer.application.withdrawn` | The onboarding application was withdrawn (terminal) |
|
|
1067
|
+
| `auto_account.created` / `auto_account.updated` / `auto_account.deleted` | On-ramp / off-ramp account lifecycle |
|
|
1068
|
+
| `transaction.auto.created` / `transaction.auto.updated` | Auto (account-driven) transaction created or changed status |
|
|
1069
|
+
| `transaction.one_off.created` / `transaction.one_off.updated` | One-off transaction created or changed status |
|
|
1070
|
+
| `recipient.created` / `recipient.updated` / `recipient.deleted` | Recipient lifecycle |
|
|
1071
|
+
| `destination.created` / `destination.deleted` | Destination lifecycle |
|
|
1072
|
+
| `target.created` / `target.updated` / `target.deleted` | Webhook target lifecycle |
|
|
1073
|
+
| `exception.created` / `exception.cleared` | A compliance or operational exception raised or cleared |
|
|
1074
|
+
| `wallet.created` / `wallet.updated` | Wallet lifecycle |
|
|
1075
|
+
| `wallet.signer_group.created` / `wallet.signer_group.updated` | Signer group attached to a wallet, or changed |
|
|
1076
|
+
| `wallet.policy.created` / `wallet.policy.updated` | Wallet policy attached, or changed |
|
|
1077
|
+
| `wallet.transaction.created` / `wallet.transaction.updated` | Wallet transaction created or changed status |
|
|
1078
|
+
| `wallet.deposit` | A deposit landed in a wallet |
|
|
1079
|
+
| `rd_payout_destination.updated` | The RD marketing-fee wallet was set or replaced |
|
|
1080
|
+
| `fee_payout_destination.updated` / `fee_payout_destination.deleted` | Developer-fee payout destination set, replaced, or removed |
|
|
1081
|
+
| `scheduled_payment.failed` | A scheduled payment reached the failed terminal state |
|
|
1082
|
+
| `deposit.held` | A deposit Dakota could not process was held (can repeat per `deposit_id`) |
|
|
1083
|
+
| `deposit.returned` | A held deposit's funds are back with the sender |
|
|
852
1084
|
|
|
853
1085
|
---
|
|
854
1086
|
|