@spritz-finance/api-client 0.18.1 → 0.19.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
@@ -66,6 +66,8 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
66
66
  - [Reauthorization](#reauthorization)
67
67
  - [User Data](#user-data)
68
68
  - [Identity Verification](#identity-verification)
69
+ - [Regional Compliance](#regional-compliance)
70
+ - [Accepting Terms](#accepting-terms)
69
71
  - [Accounts](#accounts)
70
72
  - [Bank Accounts](#bank-accounts)
71
73
  - [Debit Cards](#debit-cards)
@@ -83,16 +85,19 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
83
85
  - [Retrieving Payments](#retrieving-payments)
84
86
  - [Payment Limits](#payment-limits)
85
87
  - [Refunding a Payment](#refunding-a-payment)
88
+ - [Off-ramp Quotes](#off-ramp-quotes)
86
89
  - [On-ramp](#on-ramp)
87
90
  - [Prerequisites](#prerequisites)
88
91
  - [Checking User Access](#checking-user-access)
89
92
  - [Activation Steps](#activation-steps)
90
93
  - [Virtual Accounts](#virtual-accounts)
94
+ - [Auto-ramp Accounts](#auto-ramp-accounts)
91
95
  - [Supported Tokens](#supported-tokens)
92
96
  - [ACH Onramp (Direct Debit)](#ach-onramp-direct-debit)
93
97
  - [Checking Eligibility](#checking-eligibility)
94
98
  - [Sandbox](#sandbox)
95
99
  - [Bypassing KYC](#bypassing-kyc)
100
+ - [Simulating an Auto-ramp Deposit](#simulating-an-auto-ramp-deposit)
96
101
  - [Webhooks](#webhooks)
97
102
  - [Events](#events)
98
103
  - [Setup](#setup)
@@ -106,12 +111,15 @@ Spritz uses two levels of authentication:
106
111
  - **Integration key** — identifies your application. Provided by Spritz.
107
112
  - **User API key** — scoped to a single user. Returned when you create a user.
108
113
 
114
+ Credentials issued by the Spritz Developer Console also include an **integrator secret**. Pass it on your backend to sign REST requests with HMAC. Never ship it to a browser or mobile app.
115
+
109
116
  ```typescript
110
117
  import { SpritzApiClient, Environment } from '@spritz-finance/api-client'
111
118
 
112
119
  const client = SpritzApiClient.initialize({
113
120
  environment: Environment.Sandbox,
114
121
  integrationKey: 'YOUR_INTEGRATION_KEY_HERE',
122
+ integratorSecret: process.env.SPRITZ_INTEGRATOR_SECRET, // backend only
115
123
  apiKey: 'YOUR_USER_API_KEY_HERE', // omit if no user exists yet
116
124
  })
117
125
  ```
@@ -141,6 +149,8 @@ const user = await client.user.create({
141
149
 
142
150
  Creating a user with an email that already exists will throw an error.
143
151
 
152
+ With an integrator secret configured, `user.create()` calls `POST /v1/integrator/users` on the REST API, and an existing email throws a `ConflictError` (409). Without a secret it uses the legacy route, which does not accept Developer Console credentials.
153
+
144
154
  ### Reauthorization
145
155
 
146
156
  If you need to recover a user's API key (e.g., the user already has a Spritz account, or you've lost access), use the OTP reauthorization flow:
@@ -270,6 +280,62 @@ if (userData.verificationMetadata?.failureReason === 'duplicate_identity') {
270
280
  }
271
281
  ```
272
282
 
283
+ ### Regional Compliance
284
+
285
+ Some regions require additional fields before their capabilities unlock. In the EEA these are place of birth, nationalities and account purpose.
286
+
287
+ #### Checking Requirements
288
+
289
+ `compliance.getRequirements()` returns the additional fields the user's region requires (`GET /v1/users/me/compliance/requirements`), typed as `ComplianceRequirements`:
290
+
291
+ ```typescript
292
+ const { required, region, complete, deadline, fields } = await client.compliance.getRequirements()
293
+
294
+ // required: false outside a regulated region, with an empty `fields` array
295
+ // region: e.g. 'EEA', or null when nothing is required
296
+ // deadline: e.g. '2026-06-15', or null
297
+ // fields: [{ field: 'placeOfBirth', status: 'complete' | 'missing' }, ...]
298
+ ```
299
+
300
+ While `complete` is `false`, the region's capabilities on `user.getMe()` carry a `regional_compliance` requirement.
301
+
302
+ #### Submitting Fields
303
+
304
+ `compliance.submit()` sends the fields (`POST /v1/users/me/compliance`). All required fields must be supplied together; a partial submission is rejected with field-level errors on `error.problem.errors` and nothing is stored.
305
+
306
+ ```typescript
307
+ const { complianceFieldsComplete, bridgeCustomerUpdated } = await client.compliance.submit({
308
+ placeOfBirth: { country: 'DEU', city: 'Berlin' },
309
+ nationalities: ['DEU'],
310
+ accountPurpose: 'personal_or_living_expenses',
311
+ })
312
+ ```
313
+
314
+ | Field | Type | Description |
315
+ | ---------------------- | ------------------- | --------------------------------------------------------------------- |
316
+ | `placeOfBirth.country` | `string` | Country of birth, ISO 3166-1 alpha-3 (e.g. `DEU`) |
317
+ | `placeOfBirth.city` | `string` (optional) | City of birth. Recommended now, required by EU law from 2027 |
318
+ | `nationalities` | `string[]` | Every nationality the user holds, ISO 3166-1 alpha-3 |
319
+ | `accountPurpose` | enum | What the account is for. See `SubmitComplianceRequest` for the values |
320
+ | `accountPurposeOther` | `string` | Required when `accountPurpose` is `'other'`, not accepted otherwise |
321
+
322
+ `bridgeCustomerUpdated` is `false` when the user has not accepted the provider's terms yet. The fields are stored and sent when the provider customer is created, so this is not a failure.
323
+
324
+ ### Accepting Terms
325
+
326
+ While terms are outstanding, the user's capabilities on `user.getMe()` carry a `terms_acceptance` requirement whose `actionUrl` is the provider's hosted flow. That flow produces a signed agreement id; pass it to `terms.accept()` (`POST /v1/users/me/terms`):
327
+
328
+ ```typescript
329
+ const { termsAccepted } = await client.terms.accept({
330
+ agreementId, // from the hosted terms flow
331
+ sessionId, // optional fraud-session id from the provider's client SDK
332
+ })
333
+ ```
334
+
335
+ `agreementId` is opaque: the platform resolves which provider it belongs to. This is the REST replacement for the legacy GraphQL `onramp.acceptTermsOfService()`.
336
+
337
+ > **Retries:** this endpoint does not accept an idempotency key. If a request times out, call `user.getMe()` and check whether the `terms_acceptance` requirement is still outstanding before submitting again.
338
+
273
339
  ## Accounts
274
340
 
275
341
  Spritz supports four account types: **Bank Account**, **Debit Card**, **Bill**, and **Virtual Card**. All are referred to as "accounts" within the platform and share common properties (`id`, `type`, `userId`, `country`, `currency`, `createdAt`), with additional fields specific to each type.
@@ -882,6 +948,114 @@ Only failed off-ramps settled through Modern Treasury or Checkbook are refundabl
882
948
 
883
949
  > **Retries:** the platform recommends an `Idempotency-Key` header so a retried request replays the original response rather than returning a stale "not refundable" error. The client does not currently send one, so if a refund request times out, re-fetch the off-ramp and check its `status` before issuing another.
884
950
 
951
+ ### Off-ramp Quotes
952
+
953
+ Off-ramp quotes are the REST flow for converting crypto to fiat, including to EUR destinations: create a quote, fulfil it on-chain, then follow the quote until its off-ramp is created. For new integrations use `client.offRampQuote`; the payment-request flow above is the legacy GraphQL flow.
954
+
955
+ #### Creating a Quote
956
+
957
+ ```typescript
958
+ const quote = await client.offRampQuote.create({
959
+ accountId: bankAccount.id,
960
+ amount: '100.00',
961
+ amountMode: 'input',
962
+ chain: 'base',
963
+ tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
964
+ })
965
+ ```
966
+
967
+ | Field | Type | Description |
968
+ | -------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
969
+ | `accountId` | `string` | Destination account ID |
970
+ | `amount` | `string` | Destination fiat amount in `output` mode, or USD collected in `input` mode |
971
+ | `amountMode` | `'output' \| 'input'` | Optional, defaults to `output`. **EUR destinations require `input`** |
972
+ | `chain` | enum | Chain the crypto is sent on |
973
+ | `tokenAddress` | `string` | Token contract address. Optional in the type, but **required on every chain except Bitcoin and Dash** |
974
+ | `rail` | enum (optional) | Payout rail, e.g. `sepa` |
975
+ | `memo` | `string` (optional) | Payment note, bank account payouts only |
976
+
977
+ Check `quote.fulfillment` for the next step:
978
+
979
+ - `sign_transaction`: get the transaction to sign, sign it and broadcast it.
980
+ - `send_to_address`: send exactly `sendTo.amount` of `sendTo.token` to `sendTo.address` before `sendTo.expiresAt`.
981
+
982
+ `sendTo` is typed as nullable, and checking `fulfillment` does not narrow it, so check it too:
983
+
984
+ ```typescript
985
+ if (quote.fulfillment === 'send_to_address' && quote.sendTo) {
986
+ const { address, amount, token, expiresAt } = quote.sendTo
987
+ // send exactly `amount` of `token` to `address` before `expiresAt`
988
+ }
989
+ ```
990
+
991
+ With `amountMode: 'input'`, `quote.input.amount` is the exact USD value collected and `quote.output.amount` is an estimate (`quote.output.estimated` is `true`). The settled amount is reported by the off-ramp.
992
+
993
+ > **Retries:** this endpoint does not support an idempotency key. A retry creates a second quote. A quote that is never funded ends as `expired`.
994
+
995
+ #### Retrieving a Quote
996
+
997
+ ```typescript
998
+ const quote = await client.offRampQuote.get(quoteId)
999
+
1000
+ quote.status // 'created' | 'transaction_pending' | 'confirmed' | 'completed' | 'expired' | ...
1001
+ quote.confirmation // { transactionHash, explorerUrl } once the transaction is detected, else null
1002
+ quote.offRampId // the off-ramp (fiat leg) once it is created, else null
1003
+ ```
1004
+
1005
+ #### Getting the Transaction to Sign
1006
+
1007
+ For a `sign_transaction` quote, fetch the transaction and branch on `type`.
1008
+
1009
+ EVM: build the transaction from the contract call.
1010
+
1011
+ ```typescript
1012
+ const transaction = await client.offRampQuote.getTransaction(quote.id)
1013
+
1014
+ if (transaction.type === 'evm') {
1015
+ await walletClient.sendTransaction({
1016
+ to: transaction.contractAddress,
1017
+ data: transaction.calldata,
1018
+ value: transaction.value ? BigInt(transaction.value) : undefined,
1019
+ })
1020
+ }
1021
+ ```
1022
+
1023
+ Solana: the transaction is built for `senderAddress`, so pass it. `feePayer` is optional and defaults to `senderAddress`.
1024
+
1025
+ ```typescript
1026
+ const transaction = await client.offRampQuote.getTransaction(quote.id, {
1027
+ senderAddress: wallet.publicKey.toBase58(),
1028
+ })
1029
+
1030
+ if (transaction.type === 'solana') {
1031
+ const tx = VersionedTransaction.deserialize(
1032
+ Buffer.from(transaction.transactionSerialized, 'base64')
1033
+ )
1034
+ // sign and send tx
1035
+ }
1036
+ ```
1037
+
1038
+ Sui: pass `senderAddress` too, then restore the bytes with `Transaction.from(transaction.transactionSerialized)` from `@mysten/sui/transactions`, sign and execute.
1039
+
1040
+ Without `senderAddress`, Solana and Sui quotes are rejected with a `BadRequestError` (problem code `sender_address_required`). A `send_to_address` quote (Bitcoin, Dash, Tron) has no transaction to sign and is rejected with an `UnprocessableEntityError`.
1041
+
1042
+ #### Reporting the Transaction
1043
+
1044
+ Optional. After broadcasting, report the transaction hash so tracking starts immediately instead of when the chain watcher notices it. This works for both fulfillment types: the transaction you signed, or the transfer you sent to `sendTo.address`.
1045
+
1046
+ ```typescript
1047
+ const quote = await client.offRampQuote.submit(quoteId, {
1048
+ transactionHash: '0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060',
1049
+ })
1050
+
1051
+ quote.status // 'transaction_pending'
1052
+ quote.offRampId // string | null
1053
+ ```
1054
+
1055
+ `offRampId` can still be `null` in this response: the generated type allows it, and the field is documented as set once the crypto payment confirms. Handle `null` by reading the quote again later with `offRampQuote.get()`, or by waiting for the `payment.created` webhook. `confirmed` still comes from the chain.
1056
+
1057
+ > **Retries:** reporting the same hash again is safe, including after a timeout. Reporting a different hash once one is on record throws a `BadRequestError`.
1058
+
885
1059
  ## On-ramp
886
1060
 
887
1061
  The on-ramp feature allows users to purchase crypto stablecoins via ACH or wire transfer.
@@ -992,6 +1166,93 @@ const { bankName, bankAccountNumber, bankRoutingNumber, bankAddress } =
992
1166
  const accounts = await client.virtualAccounts.list()
993
1167
  ```
994
1168
 
1169
+ ### Auto-ramp Accounts
1170
+
1171
+ An auto-ramp account is a virtual bank account in the user's name: fiat deposited into it is converted to a token and sent to a wallet address. `client.autoRampAccount` is the REST replacement for the legacy GraphQL `client.virtualAccounts` above, and the one to use for EUR (SEPA) accounts.
1172
+
1173
+ #### Listing Accounts
1174
+
1175
+ ```typescript
1176
+ const accounts = await client.autoRampAccount.list()
1177
+
1178
+ // Example response
1179
+ [
1180
+ {
1181
+ id: '507f1f77bcf86cd799439011',
1182
+ depositInstructions: {
1183
+ type: 'iban',
1184
+ bankName: 'Example Bank',
1185
+ bankAddress: '1 Example Street, Berlin',
1186
+ paymentRails: ['sepa'],
1187
+ iban: 'DE89370400440532013000',
1188
+ bic: 'COBADEFFXXX',
1189
+ },
1190
+ network: 'solana',
1191
+ address: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',
1192
+ token: 'USDC',
1193
+ currency: 'EUR',
1194
+ status: 'active',
1195
+ createdAt: '2026-01-15T10:30:00.000Z',
1196
+ },
1197
+ ]
1198
+ ```
1199
+
1200
+ Branch on `depositInstructions.type`: `us` carries `bankRoutingNumber` and `bankAccountNumber`, `iban` carries `iban` and an optional `bic`.
1201
+
1202
+ #### Getting an Account
1203
+
1204
+ ```typescript
1205
+ const account = await client.autoRampAccount.get(accountId)
1206
+ ```
1207
+
1208
+ #### Creating an Account
1209
+
1210
+ ```typescript
1211
+ const account = await client.autoRampAccount.create({
1212
+ address: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',
1213
+ network: 'solana',
1214
+ token: 'USDC',
1215
+ })
1216
+ ```
1217
+
1218
+ The address must be valid for the network, and the network and token combination must be supported for the user's region (see `GET /v1/on-ramps/supported-pairs`); otherwise the call throws a `BadRequestError` whose `problem.field` is `address` or `network`. Confirm `account.status` is `active` before showing the deposit instructions to a user.
1219
+
1220
+ > **Retries:** this endpoint does not support an idempotency key. After a timeout, call `autoRampAccount.list()` and look for the account before creating it again.
1221
+
1222
+ #### Estimating a Deposit
1223
+
1224
+ ```typescript
1225
+ const estimate = await client.autoRampAccount.estimate(accountId, '2525.00')
1226
+
1227
+ estimate.fees.total // every expected fee, in the account's currency (EUR on SEPA accounts)
1228
+ estimate.fees.maximum // upper bound on the total, when there is enough history
1229
+ estimate.output.amount // crypto expected at the destination
1230
+ estimate.output.minimum // lower bound on the amount, when there is enough history
1231
+ estimate.rate.asOf // when the rate was read
1232
+ ```
1233
+
1234
+ This is an estimate, not a quote: no rate is locked. The fee belongs to the account, so do not reuse an estimate across accounts.
1235
+
1236
+ `fees.maximum` and `output.minimum` are omitted until enough deposits have settled on the network (`fees.networkFeeSamples` says how many). Do not promise a user a ceiling or a floor when they are absent.
1237
+
1238
+ When no estimate can be produced, branch on the problem code:
1239
+
1240
+ ```typescript
1241
+ import { hasProblemCode } from '@spritz-finance/api-client'
1242
+
1243
+ try {
1244
+ await client.autoRampAccount.estimate(accountId, '2525.00')
1245
+ } catch (error) {
1246
+ if (hasProblemCode(error, 'rate_unavailable')) {
1247
+ // 503, transient: retry
1248
+ } else if (hasProblemCode(error, 'unsupported_currency_pair')) {
1249
+ // 400, permanent
1250
+ } else if (hasProblemCode(error, 'exchange_rate_provider_error')) {
1251
+ // 502, the rate provider failed
1252
+ }
1253
+ }
1254
+ ```
1255
+
995
1256
  ### Supported Tokens
996
1257
 
997
1258
  | Network | Tokens |
@@ -1047,6 +1308,8 @@ const deposit = await client.deposit.create(
1047
1308
 
1048
1309
  To move submission onto the customer's device, pass `clientNetwork: { ipAddresses: [req.ip] }` to `prepare` and forward the returned `submissionToken` to that client. The client then calls `POST /v1/deposits/direct` itself with `Authorization: Bearer ach_submit_...` as its only credential — no user API key, no integrator key, no HMAC headers — plus the `Idempotency-Key` header and a body of just `{ preparationId }`. This SDK signs every REST call with integrator HMAC, so that request should not go through it; see the [ACH Onramp Integration Guide](docs/ach-onramp-guide.md) for the full request.
1049
1310
 
1311
+ `prepare` also accepts an optional `customerContext` object (at most 8192 encoded UTF-8 bytes) carrying partner-side context for later fraud analysis. Its field mapping is agreed privately per integration; missing, unknown or invalid fields never block preparation. Never send credentials or bank data in it.
1312
+
1050
1313
  If risk checks block the create step, the API returns 409 before any ACH debit is pulled. Prepare a new quote before retrying; blocked create attempts consume the original `preparationId`.
1051
1314
 
1052
1315
  For a complete walkthrough with code examples, request/response schemas, and deposit lifecycle documentation, see the **[ACH Onramp Integration Guide](docs/ach-onramp-guide.md)**.
@@ -1165,6 +1428,26 @@ await client.sandbox.bypassKyc({ failed: true })
1165
1428
 
1166
1429
  This endpoint returns 403 in production.
1167
1430
 
1431
+ ### Simulating an Auto-ramp Deposit
1432
+
1433
+ The provider's sandbox cannot credit a virtual account, so this is the only way to make an [auto-ramp account](#auto-ramp-accounts) settle in sandbox:
1434
+
1435
+ ```typescript
1436
+ const { onRampId, depositId, status } = await client.sandbox.simulateAutoRampDeposit(accountId, {
1437
+ amount: '2525.00', // in the account's currency
1438
+ gasFee: '4.20', // optional, defaults to '0.00'
1439
+ exchangeFee: '2.53', // optional; otherwise derived from the provider's live spread
1440
+ settle: false, // optional, leaves the deposit at 'processing'
1441
+ })
1442
+
1443
+ // Advance the same on-ramp
1444
+ await client.sandbox.simulateAutoRampDeposit(accountId, { amount: '2525.00', depositId })
1445
+
1446
+ const onRamp = await client.onrampPayment.get(onRampId)
1447
+ ```
1448
+
1449
+ The on-ramp it produces is an ordinary one: it appears in `onrampPayment.list()`, fires the same `onramp.*` webhooks and carries the same fee breakdown. This endpoint returns 403 in production.
1450
+
1168
1451
  ## Webhooks
1169
1452
 
1170
1453
  ### Events