@dakota-xyz/ts-sdk 3.0.0 → 3.4.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 +235 -36
- package/dist/governance/index.d.mts +315 -0
- package/dist/governance/index.d.ts +315 -0
- package/dist/governance/index.js +379 -0
- package/dist/governance/index.js.map +1 -0
- package/dist/governance/index.mjs +365 -0
- package/dist/governance/index.mjs.map +1 -0
- package/dist/index.d.mts +7274 -2928
- package/dist/index.d.ts +7274 -2928
- package/dist/index.js +1068 -149
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1048 -148
- package/dist/index.mjs.map +1 -1
- package/dist/webhook/index.d.mts +179 -3
- package/dist/webhook/index.d.ts +179 -3
- package/dist/webhook/index.js +8 -0
- package/dist/webhook/index.js.map +1 -1
- package/dist/webhook/index.mjs +8 -0
- package/dist/webhook/index.mjs.map +1 -1
- package/package.json +15 -3
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
|
|
|
@@ -229,10 +233,96 @@ await client.mandates.approve(mandate.id!, {
|
|
|
229
233
|
```typescript
|
|
230
234
|
// Deterministic report: balances, upcoming payments, mandate headroom, risks.
|
|
231
235
|
const report = await client.insights.get(customerId);
|
|
236
|
+
|
|
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' });
|
|
232
240
|
```
|
|
233
241
|
|
|
234
242
|
The full agentic surface is reachable via `client.paymentAgents`, `client.mandates`, `client.instructions`, `client.scheduledPayments`, and `client.insights`.
|
|
235
243
|
|
|
244
|
+
## Signer-group governance (ES256 and passkeys)
|
|
245
|
+
|
|
246
|
+
When a client has governance enforcement on, or a signer group has
|
|
247
|
+
governance settings, adding or removing members and changing who governs the
|
|
248
|
+
group need signatures from the group's governing members. Each signature
|
|
249
|
+
covers a canonical "intent" that includes the group's current `version` and
|
|
250
|
+
the request's idempotency key, so the SDK builds it for you.
|
|
251
|
+
|
|
252
|
+
**On a server, with ES256 keys:**
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
import { ES256Signer, StaleSignerGroupVersionError } from '@dakota-xyz/ts-sdk';
|
|
256
|
+
|
|
257
|
+
const admin = ES256Signer.fromPrivateKey(process.env.ADMIN_KEY_PEM!); // or your KMS behind GovernanceSigner
|
|
258
|
+
const group = await client.signerGroups.addSignerSigned(groupId, newMemberPublicKey, [admin]);
|
|
259
|
+
await client.signerGroups.removeSignersSigned(groupId, [oldMemberPublicKey], [admin]);
|
|
260
|
+
await client.signerGroups.updateGovernanceSigned(groupId, { governance_threshold: 2 }, [admin]);
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Pass as many signers as the group's `effective_governance_threshold` needs.
|
|
264
|
+
The helper reads the group's `version`, generates a lowercase UUID idempotency
|
|
265
|
+
key, signs, and sends the same key as `X-Idempotency-Key`. Pass
|
|
266
|
+
`{ staleRetries: n }` (0 to 5) to the add and remove helpers to re-read and
|
|
267
|
+
re-sign after a concurrent change; each retry asks every signer again. The
|
|
268
|
+
governance update refuses it, since re-signing a whole-state change after
|
|
269
|
+
someone else's would undo theirs.
|
|
270
|
+
|
|
271
|
+
**With passkeys, signed in the user's browser or app:** the API key stays on
|
|
272
|
+
your server, so the change is prepared there, signed in the browser, and sent
|
|
273
|
+
from the server.
|
|
274
|
+
|
|
275
|
+
```typescript
|
|
276
|
+
// server: build the change and keep it (it is plain JSON)
|
|
277
|
+
const change = await client.signerGroups.prepareAddSigner(groupId, newMemberPublicKey);
|
|
278
|
+
session.pendingChange = change;
|
|
279
|
+
return { challenge: change.canonical };
|
|
280
|
+
|
|
281
|
+
// browser: the browser-safe entry point has no Node dependencies
|
|
282
|
+
import { buildChallenge, packAssertion } from '@dakota-xyz/ts-sdk/governance';
|
|
283
|
+
const credential = await navigator.credentials.get({
|
|
284
|
+
publicKey: { challenge: buildChallenge(challenge), rpId: 'app.example.com', userVerification: 'required' },
|
|
285
|
+
});
|
|
286
|
+
const signature = packAssertion(credential as PublicKeyCredential);
|
|
287
|
+
|
|
288
|
+
// server: check it, then send it
|
|
289
|
+
import { assertionChallengeMatches } from '@dakota-xyz/ts-sdk';
|
|
290
|
+
if (!assertionChallengeMatches(signature, session.pendingChange)) throw new Error('wrong change');
|
|
291
|
+
const group = await client.signerGroups.submitSignedChange(session.pendingChange, [signature]);
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
The challenge is the canonical intent itself, not a hash of it. Passkey and
|
|
295
|
+
ES256 signatures can be combined toward one quorum. In a browser with a
|
|
296
|
+
WebCrypto key, use `webCryptoES256Signer(cryptoKey)`.
|
|
297
|
+
|
|
298
|
+
**When governance refuses**, the error says why (each is an `APIError`):
|
|
299
|
+
|
|
300
|
+
| Error | Meaning | What to do |
|
|
301
|
+
|---|---|---|
|
|
302
|
+
| `EndorsementRequiredError` (400) | The change was sent unsigned | Use the signed helpers |
|
|
303
|
+
| `InsufficientEndorsementsError` (403) | Too few governing signatures (`have`, `need`) | Prepare again (a new idempotency key) and collect every signature again |
|
|
304
|
+
| `StaleSignerGroupVersionError` (409) | The group changed after signing | Prepare and sign again (or pass `staleRetries`) |
|
|
305
|
+
| `BelowThresholdError` (422) | The removal would leave the group too small | Add members first, or remove fewer |
|
|
306
|
+
| `InvalidGoverningGroupError` (409) | The governing group is gone or invalid | Fix the group's governance |
|
|
307
|
+
|
|
308
|
+
The idempotency key is part of what is signed, and the platform remembers the
|
|
309
|
+
outcome per key. So a governance refusal (stale version, too few or bad
|
|
310
|
+
signatures) is final for that intent: prepare and sign again. Resending the
|
|
311
|
+
same key with more signatures is refused as a different request.
|
|
312
|
+
|
|
313
|
+
If a submit may fail without any response (a timeout or a dropped
|
|
314
|
+
connection), use the `prepare*` + `submitSignedChange` pair and keep the
|
|
315
|
+
prepared change and its signatures: after such a failure, resubmit exactly
|
|
316
|
+
those with `submitSignedChange`. The `*Signed` helpers do not return what
|
|
317
|
+
they signed, so there is nothing to resubmit, and calling one again prepares
|
|
318
|
+
a new intent (under a new key, unless you pass `idempotencyKey`).
|
|
319
|
+
|
|
320
|
+
To build intents yourself (for example a governed crypto destination), use
|
|
321
|
+
`addSignersToGroupIntent`, `removeSignersFromGroupIntent`,
|
|
322
|
+
`updateSignerGroupGovernanceIntent` and `createCryptoDestinationIntent`. See
|
|
323
|
+
`examples/governance-es256.ts` and `examples/governance-passkey.ts` for
|
|
324
|
+
complete runs against sandbox.
|
|
325
|
+
|
|
236
326
|
## Handling Webhooks
|
|
237
327
|
|
|
238
328
|
Dakota sends webhooks for all status changes. Set up a handler:
|
|
@@ -544,6 +634,7 @@ Manage customer entities representing businesses and organizations.
|
|
|
544
634
|
| `customers.delete(id)` | Soft-delete a customer (blocked if it has accounts) |
|
|
545
635
|
| `customers.getCapabilities(id)` | Capabilities + outstanding requirements to unlock each |
|
|
546
636
|
| `customers.reEngage(id)` | Mint a fresh application link for an approved customer |
|
|
637
|
+
| `customers.withdrawApplication(id, applicationId, data?)` | Withdraw an undecided onboarding application (final) |
|
|
547
638
|
| `customers.bulkImportFromSumsubTokens(data)` | Import from Sumsub share tokens (synchronous) |
|
|
548
639
|
| `customers.importPersonaTokens(data)` | Import from Persona Connect share tokens (async job) |
|
|
549
640
|
| `customers.listPersonaImportJobs(params?)` | List Persona import jobs, newest first |
|
|
@@ -568,6 +659,20 @@ console.log(page.status_counts?.info_requested ?? 0);
|
|
|
568
659
|
comma-separated form, and `sort_by` / `sort_dir` / `created_at_from` /
|
|
569
660
|
`created_at_to` are also accepted.
|
|
570
661
|
|
|
662
|
+
When a customer will not or cannot continue onboarding — after a request for
|
|
663
|
+
information they chose not to answer, say — withdraw the application rather
|
|
664
|
+
than leaving it open:
|
|
665
|
+
|
|
666
|
+
```typescript
|
|
667
|
+
await client.customers.withdrawApplication(customerId, applicationId, {
|
|
668
|
+
reason: 'Customer opted not to proceed',
|
|
669
|
+
});
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
Withdrawal is **final**: the customer's `status` becomes `withdrawn`, and
|
|
673
|
+
onboarding them again needs a new application. An application that already has
|
|
674
|
+
a decision answers **409**. The platform emits `customer.application.withdrawn`.
|
|
675
|
+
|
|
571
676
|
### Recipients
|
|
572
677
|
|
|
573
678
|
Manage recipient entities for payouts and transfers.
|
|
@@ -597,7 +702,17 @@ Manage on-ramp, off-ramp, and swap accounts.
|
|
|
597
702
|
| `accounts.create(data)` | Create account (onramp/offramp/swap) |
|
|
598
703
|
| `accounts.list(params?)` | List accounts |
|
|
599
704
|
| `accounts.get(id)` | Get account by ID |
|
|
600
|
-
| `accounts.update(id, data)` | Update account |
|
|
705
|
+
| `accounts.update(id, data)` | Update account (developer fee only) |
|
|
706
|
+
|
|
707
|
+
A developer fee is either `developer_fee_bps` or `developer_fee_fixed`. The
|
|
708
|
+
platform returns a 400 if a request carries both keys, even with
|
|
709
|
+
`developer_fee_bps: 0`, so leave out the one you are not using. On update,
|
|
710
|
+
setting one replaces the other. `developer_fee_fixed` is a decimal **string**
|
|
711
|
+
such as `'10.00'`, in units of the asset deposited (at most 2 decimals,
|
|
712
|
+
greater than 0). Fixed-fee accounts return `developer_fee_fixed` and
|
|
713
|
+
`minimum_deposit` (the fee plus 0.01); both are omitted otherwise. Some
|
|
714
|
+
routes do not support a fixed fee, and the platform answers those with a 400
|
|
715
|
+
that asks for `developer_fee_bps` instead.
|
|
601
716
|
|
|
602
717
|
### Transactions
|
|
603
718
|
|
|
@@ -695,11 +810,19 @@ Manage multi-party authorization.
|
|
|
695
810
|
| `signerGroups.create(data)` | Create signer group |
|
|
696
811
|
| `signerGroups.list(params?)` | List signer groups |
|
|
697
812
|
| `signerGroups.get(id, params?)` | Get signer group by ID (`{ include_removed: true }` adds `removed_members`) |
|
|
698
|
-
| `signerGroups.addSigner(groupId, data)` | Add signer to group |
|
|
699
|
-
| `signerGroups.removeSigner(groupId, signerId)` | Remove signer (by KSUID `signer_id`, not public key) |
|
|
813
|
+
| `signerGroups.addSigner(groupId, data)` | Add signer to group (unsigned; a governed group refuses it) |
|
|
814
|
+
| `signerGroups.removeSigner(groupId, signerId)` | Remove signer (by KSUID `signer_id`, not public key; unsigned) |
|
|
815
|
+
| `signerGroups.addSignerSigned(groupId, memberKey, signers, opts?)` | Add a member with governance signatures, in one call |
|
|
816
|
+
| `signerGroups.removeSignersSigned(groupId, memberKeys, signers, opts?)` | Remove members with governance signatures, in one call |
|
|
817
|
+
| `signerGroups.updateGovernanceSigned(groupId, settings, signers, opts?)` | Replace the group's governance settings, signed |
|
|
818
|
+
| `signerGroups.prepareAddSigner` / `prepareRemoveSigners` / `prepareGovernanceUpdate` | Build a change to sign elsewhere (passkey in a browser) |
|
|
819
|
+
| `signerGroups.submitSignedChange(change, signatures)` | Send a prepared change with its signatures |
|
|
820
|
+
| `signerGroups.removeSigners(groupId, body)` / `updateGovernance(groupId, body)` | Low level: send a body you signed yourself |
|
|
700
821
|
| `signerGroups.attachToWallet(walletId, groupId)` | Attach to wallet |
|
|
701
822
|
| `signerGroups.detachFromWallet(walletId, groupId)` | Detach from wallet |
|
|
702
823
|
|
|
824
|
+
See [Signer-group governance](#signer-group-governance-es256-and-passkeys) for signing.
|
|
825
|
+
|
|
703
826
|
### Signers
|
|
704
827
|
|
|
705
828
|
Manage individual signers.
|
|
@@ -716,8 +839,9 @@ Manage API key credentials.
|
|
|
716
839
|
|
|
717
840
|
| Method | Description |
|
|
718
841
|
|--------|-------------|
|
|
719
|
-
| `apiKeys.create(data)` | Create API key (
|
|
720
|
-
| `apiKeys.list(params?)` | List API keys |
|
|
842
|
+
| `apiKeys.create(data)` | Create API key with an optional name and scope (key shown once) |
|
|
843
|
+
| `apiKeys.list(params?)` | List API keys, with name, scope and last-used time |
|
|
844
|
+
| `apiKeys.update(id, data)` | Change the name, the scope, or both |
|
|
721
845
|
| `apiKeys.delete(id)` | Delete API key |
|
|
722
846
|
|
|
723
847
|
### Users
|
|
@@ -798,6 +922,8 @@ session, so there is no id to pass.
|
|
|
798
922
|
|--------|-------------|
|
|
799
923
|
| `rdMarketingFee.listMonths()` | The months with a statement, newest first |
|
|
800
924
|
| `rdMarketingFee.getStatement(month)` | One month, one row per calendar day |
|
|
925
|
+
| `rdMarketingFee.getPayoutDestination()` | The wallet the fee is paid to (404 = none yet) |
|
|
926
|
+
| `rdMarketingFee.setPayoutDestination(data)` | Register or replace it — an EVM address on Base |
|
|
801
927
|
|
|
802
928
|
```typescript
|
|
803
929
|
const months = await client.rdMarketingFee.listMonths();
|
|
@@ -814,18 +940,44 @@ A client with no contract gets a **404**; an empty month list means the
|
|
|
814
940
|
contract is real but starts later. The running month is included, with its fee
|
|
815
941
|
figures absent rather than zero.
|
|
816
942
|
|
|
943
|
+
Each statement carries both rates: `y_bps_annual` is the contract rate as the
|
|
944
|
+
Order Form quotes it, and `y_bps_monthly` is what THIS month was charged at
|
|
945
|
+
(annual × days in month / 365, to 2 decimal places), so a client can check the
|
|
946
|
+
month against the rate they signed.
|
|
947
|
+
|
|
948
|
+
The fee is paid to a wallet you register separately from your developer-fee
|
|
949
|
+
destination — RD exists only on Base, so only the address is a parameter:
|
|
950
|
+
|
|
951
|
+
```typescript
|
|
952
|
+
const dest = await client.rdMarketingFee.setPayoutDestination({
|
|
953
|
+
address: '0x1234567890123456789012345678901234567890',
|
|
954
|
+
});
|
|
955
|
+
console.log(dest.chain); // always 'eip155:8453'
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
`getPayoutDestination()` answers **404** while nothing is registered — the
|
|
959
|
+
ordinary state for a new client, not an error — and **403** when the client is
|
|
960
|
+
not in the programme. A change emits `rd_payout_destination.updated`.
|
|
961
|
+
|
|
817
962
|
### Sandbox
|
|
818
963
|
|
|
819
964
|
Test simulations (sandbox environment only).
|
|
820
965
|
|
|
821
966
|
| Method | Description |
|
|
822
967
|
|--------|-------------|
|
|
823
|
-
| `sandbox.simulateInbound(data)` | Simulate
|
|
968
|
+
| `sandbox.simulateInbound(data)` | Simulate a deposit, an outbound settlement/return, or a reversal |
|
|
824
969
|
| `sandbox.simulateOnboarding(data)` | Simulate KYB completion |
|
|
825
970
|
| `sandbox.getSimulation(id)` | Get simulation by ID |
|
|
826
971
|
| `sandbox.advanceSimulation(id)` | Advance simulation state |
|
|
827
972
|
| `sandbox.listScenarios(params?)` | List available scenarios |
|
|
828
973
|
|
|
974
|
+
`simulateInbound` covers every fiat rail — `ach_*`, `fedwire_*`, `swift_*`,
|
|
975
|
+
`fednow_inbound` — plus `crypto_inbound`. Inbound types take the receiving
|
|
976
|
+
`account_id`; outbound and reversal types take the funding offramp `account_id`
|
|
977
|
+
AND the `one_off_transaction_id`. A SWIFT deposit is chosen by the ACCOUNT, not
|
|
978
|
+
the type: `swift_inbound` and `fedwire_inbound` both book as SWIFT against a
|
|
979
|
+
SWIFT onramp account and as Fedwire against a domestic one.
|
|
980
|
+
|
|
829
981
|
### Fee Payout Destination
|
|
830
982
|
|
|
831
983
|
Where Dakota pays your accrued developer fees. Exactly one per organization,
|
|
@@ -846,9 +998,9 @@ await client.feePayoutDestination.set({
|
|
|
846
998
|
});
|
|
847
999
|
```
|
|
848
1000
|
|
|
849
|
-
### Payment Agents (
|
|
1001
|
+
### Payment Agents (Beta)
|
|
850
1002
|
|
|
851
|
-
Hosted signing agents that draft payments (`x-
|
|
1003
|
+
Hosted signing agents that draft payments (`x-beta`, flag-gated).
|
|
852
1004
|
|
|
853
1005
|
| Method | Description |
|
|
854
1006
|
|--------|-------------|
|
|
@@ -858,7 +1010,7 @@ Hosted signing agents that draft payments (`x-alpha`, flag-gated).
|
|
|
858
1010
|
| `paymentAgents.createProposals(id, data)` | One-shot proposals turn (see `newAgentConversation`) |
|
|
859
1011
|
| `paymentAgents.getProposalsProgress(id)` | Live progress of an in-flight drafting turn (advisory) |
|
|
860
1012
|
|
|
861
|
-
### Agentic Policy (
|
|
1013
|
+
### Agentic Policy (Beta)
|
|
862
1014
|
|
|
863
1015
|
How your product speaks, and what the agent may propose for it. Register it
|
|
864
1016
|
once and every drafting turn narrates in your nouns instead of the platform's.
|
|
@@ -885,20 +1037,41 @@ Your developer fee is separate, and belongs in **both** places:
|
|
|
885
1037
|
```typescript
|
|
886
1038
|
// The drafting turn — this is what lets the agent MENTION the fee.
|
|
887
1039
|
const conv = client.newAgentConversation(agentId, {
|
|
888
|
-
|
|
1040
|
+
developerFeeDefaults: {
|
|
1041
|
+
swap: { developer_fee_bps: 50 },
|
|
1042
|
+
offramp: { developer_fee_bps: 25 },
|
|
1043
|
+
},
|
|
889
1044
|
});
|
|
890
1045
|
|
|
891
1046
|
// The accept — this is what CHARGES it.
|
|
892
1047
|
await client.instructions.create({
|
|
893
1048
|
payment_agent_id: agentId,
|
|
894
1049
|
proposals: turn.proposals,
|
|
895
|
-
|
|
1050
|
+
developer_fee_defaults: {
|
|
1051
|
+
swap: { developer_fee_bps: 50 },
|
|
1052
|
+
offramp: { developer_fee_bps: 25 },
|
|
1053
|
+
},
|
|
896
1054
|
});
|
|
897
1055
|
```
|
|
898
1056
|
|
|
899
1057
|
Declare it only on the accept and the customer approves a summary that never
|
|
900
1058
|
disclosed a fee, then gets charged it.
|
|
901
1059
|
|
|
1060
|
+
Each payout type takes a percentage (`developer_fee_bps`) **or** a flat amount
|
|
1061
|
+
per payment (`developer_fee_fixed`), never both. The fixed fee is a decimal
|
|
1062
|
+
string in units of the asset deposited, and it is added on top of the payment,
|
|
1063
|
+
so the payee receives exactly the amount named: a 100.00 USDC payment with
|
|
1064
|
+
`{ developer_fee_fixed: '10.00' }` leaves the wallet as 110.00 USDC, and the
|
|
1065
|
+
spending limit applies to that 110.00. The `create_auto_account` action takes
|
|
1066
|
+
either one too, as an override of the defaults.
|
|
1067
|
+
|
|
1068
|
+
```typescript
|
|
1069
|
+
const defaults: DeveloperFeeDefaults = {
|
|
1070
|
+
swap: { developer_fee_fixed: '10.00' }, // 10.00 USDC on a USDC payment
|
|
1071
|
+
offramp: { developer_fee_bps: 25 },
|
|
1072
|
+
};
|
|
1073
|
+
```
|
|
1074
|
+
|
|
902
1075
|
Registering is the **only** way to set a policy. It belongs to the client, not
|
|
903
1076
|
to a request, so a drafting turn and the accept that follows it cannot be
|
|
904
1077
|
judged by different rules. The per-conversation `clientPolicy` option is gone:
|
|
@@ -906,7 +1079,7 @@ the platform stopped reading `client_policy` from request bodies, and
|
|
|
906
1079
|
one sent there is ignored — the agent quietly goes back to saying "destination"
|
|
907
1080
|
and "mandate" with nothing reporting the fallback.
|
|
908
1081
|
|
|
909
|
-
### Mandates (
|
|
1082
|
+
### Mandates (Beta)
|
|
910
1083
|
|
|
911
1084
|
The §8 authorizations that arm scheduled payments.
|
|
912
1085
|
|
|
@@ -921,7 +1094,7 @@ The §8 authorizations that arm scheduled payments.
|
|
|
921
1094
|
| `mandates.listVersions(id)` | Append-only version history, oldest first |
|
|
922
1095
|
| `mandates.getBudget(id)` | Remaining budget: spent, earmarked, left (advisory) |
|
|
923
1096
|
|
|
924
|
-
### Instructions (
|
|
1097
|
+
### Instructions (Beta)
|
|
925
1098
|
|
|
926
1099
|
Accept and inspect actuated proposals.
|
|
927
1100
|
|
|
@@ -930,7 +1103,7 @@ Accept and inspect actuated proposals.
|
|
|
930
1103
|
| `instructions.create(data)` | Accept proposals — actuate into persisted instructions |
|
|
931
1104
|
| `instructions.get(id)` | Get an instruction + its downstream artifacts |
|
|
932
1105
|
|
|
933
|
-
### Scheduled Payments (
|
|
1106
|
+
### Scheduled Payments (Beta)
|
|
934
1107
|
|
|
935
1108
|
Schedule rows created from instructions (or directly).
|
|
936
1109
|
|
|
@@ -941,38 +1114,64 @@ Schedule rows created from instructions (or directly).
|
|
|
941
1114
|
| `scheduledPayments.get(id)` | Get scheduled payment by ID |
|
|
942
1115
|
| `scheduledPayments.cancel(id)` | Cancel an open scheduled payment |
|
|
943
1116
|
|
|
944
|
-
### Insights (
|
|
1117
|
+
### Insights (Beta)
|
|
945
1118
|
|
|
946
1119
|
Read-only advisory reporting over a customer's agentic activity.
|
|
947
1120
|
|
|
948
1121
|
| Method | Description |
|
|
949
1122
|
|--------|-------------|
|
|
950
|
-
| `insights.get(customerId)` | Deterministic account insight report |
|
|
1123
|
+
| `insights.get(customerId)` | Deterministic account insight report for one customer |
|
|
1124
|
+
| `insights.getClientReport(params?)` | The same over the whole book: KPIs, daily series, per-customer roll-up |
|
|
1125
|
+
|
|
1126
|
+
`getClientReport` filters (`customer_id`, `wallet_id`, `kind`, `severity`,
|
|
1127
|
+
`responsibility`, `window_days`) are all optional and only narrow the report;
|
|
1128
|
+
the multi-value ones are comma-separated strings. Items gain `customer_id`
|
|
1129
|
+
(omitted on cross-customer aggregates) and `responsibility` — a grouping label
|
|
1130
|
+
for routing, not ownership. `kind` stays an OPEN set; two kinds are emitted
|
|
1131
|
+
only at this scope today, `volume_anomaly` and `recipient_dormant`. The report
|
|
1132
|
+
scans at most 100 customers per request and says so through
|
|
1133
|
+
`snapshot.customers.scanned < total`.
|
|
951
1134
|
|
|
952
1135
|
---
|
|
953
1136
|
|
|
954
1137
|
## Webhook Event Types
|
|
955
1138
|
|
|
1139
|
+
Every value the platform's `EventType` enum lists — and therefore every value
|
|
1140
|
+
a webhook target can subscribe to — is a member of `WebhookEventType`; a test
|
|
1141
|
+
keeps the two in step on every spec sync. Names not in this table (for
|
|
1142
|
+
example `transaction.completed` or `application.approved`) are never emitted:
|
|
1143
|
+
a transaction's outcome arrives as an `*.updated` event with the new status,
|
|
1144
|
+
and an application decision arrives as `customer.kyb_status.updated`.
|
|
1145
|
+
|
|
956
1146
|
| Event Type | Description |
|
|
957
1147
|
|------------|-------------|
|
|
958
|
-
| `
|
|
959
|
-
| `
|
|
960
|
-
| `customer.
|
|
961
|
-
| `
|
|
962
|
-
| `
|
|
963
|
-
| `
|
|
964
|
-
| `
|
|
965
|
-
| `
|
|
966
|
-
| `
|
|
967
|
-
| `
|
|
968
|
-
| `
|
|
969
|
-
| `transaction.
|
|
970
|
-
| `transaction.
|
|
971
|
-
| `
|
|
972
|
-
| `
|
|
973
|
-
| `
|
|
974
|
-
| `
|
|
975
|
-
| `
|
|
1148
|
+
| `user.created` / `user.updated` / `user.deleted` | Dashboard user lifecycle |
|
|
1149
|
+
| `api_key.created` / `api_key.deleted` | API key lifecycle |
|
|
1150
|
+
| `customer.created` / `customer.updated` | Customer record lifecycle |
|
|
1151
|
+
| `customer.kyb_link.created` / `customer.kyb_link.updated` | Onboarding link issued or changed |
|
|
1152
|
+
| `customer.kyb_status.created` / `customer.kyb_status.updated` | KYB status set or changed (an application decision arrives here) |
|
|
1153
|
+
| `customer.kyb_application.submitted` | The customer submitted their onboarding application |
|
|
1154
|
+
| `customer.capability_status.updated` | A rail's standing changed; payload lists what still gates it |
|
|
1155
|
+
| `customer.rfi.requested` | A reviewer needs more information; payload lists what is owed (never the link) |
|
|
1156
|
+
| `customer.rfi.responded` | The information arrived; the application is back in review |
|
|
1157
|
+
| `customer.application.withdrawn` | The onboarding application was withdrawn (terminal) |
|
|
1158
|
+
| `auto_account.created` / `auto_account.updated` / `auto_account.deleted` | On-ramp / off-ramp account lifecycle |
|
|
1159
|
+
| `transaction.auto.created` / `transaction.auto.updated` | Auto (account-driven) transaction created or changed status |
|
|
1160
|
+
| `transaction.one_off.created` / `transaction.one_off.updated` | One-off transaction created or changed status |
|
|
1161
|
+
| `recipient.created` / `recipient.updated` / `recipient.deleted` | Recipient lifecycle |
|
|
1162
|
+
| `destination.created` / `destination.deleted` | Destination lifecycle |
|
|
1163
|
+
| `target.created` / `target.updated` / `target.deleted` | Webhook target lifecycle |
|
|
1164
|
+
| `exception.created` / `exception.cleared` | A compliance or operational exception raised or cleared |
|
|
1165
|
+
| `wallet.created` / `wallet.updated` | Wallet lifecycle |
|
|
1166
|
+
| `wallet.signer_group.created` / `wallet.signer_group.updated` | Signer group attached to a wallet, or changed |
|
|
1167
|
+
| `wallet.policy.created` / `wallet.policy.updated` | Wallet policy attached, or changed |
|
|
1168
|
+
| `wallet.transaction.created` / `wallet.transaction.updated` | Wallet transaction created or changed status |
|
|
1169
|
+
| `wallet.deposit` | A deposit landed in a wallet |
|
|
1170
|
+
| `rd_payout_destination.updated` | The RD marketing-fee wallet was set or replaced |
|
|
1171
|
+
| `fee_payout_destination.updated` / `fee_payout_destination.deleted` | Developer-fee payout destination set, replaced, or removed |
|
|
1172
|
+
| `scheduled_payment.failed` | A scheduled payment reached the failed terminal state |
|
|
1173
|
+
| `deposit.held` | A deposit Dakota could not process was held (can repeat per `deposit_id`) |
|
|
1174
|
+
| `deposit.returned` | A held deposit's funds are back with the sender |
|
|
976
1175
|
|
|
977
1176
|
---
|
|
978
1177
|
|