@atumlabs/payment-gateway-client 3.0.0 → 3.0.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.
package/dist/index.d.ts CHANGED
@@ -1,4 +1,6 @@
1
1
  import { AxiosRequestConfig, AxiosResponse } from 'axios';
2
+ import { d as AuthorizePaymentData, e as AuthorizePaymentResponse, G as GetDefaultsData, f as GetDefaultsResponse, H as HealthCheckResponse, S as SubmitPaymentData, g as SubmitPaymentResponse, h as GetPaymentStatusData, i as GetPaymentStatusResponse2, R as ResolvePaymentData, j as ResolvePaymentResponse2, k as GetPaymentTimelineData, l as GetPaymentTimelineResponse, m as PreparePaymentData, n as PreparePaymentResponse2, C as CreateQuoteRequestData, o as CreateQuoteRequestResponse, p as GetQuoteRequestStatusData, q as GetQuoteRequestStatusResponse, r as AwardQuoteData, s as AwardQuoteResponse, t as SignedMessage, E as ErrorResponse, P as PaymentRequest, u as CreateQuoteRequest } from './sender-auth-verify-C-Q-zvAO.js';
3
+ export { $ as $OpenApiTs, A as AuthTerms, w as AuthorizationResult, x as AwardAccepted, y as AwardRequest, z as AwardResponse, B as AwardedPayment, D as AwardedQuote, F as BidAward, I as ChainDefaultsByChain, J as ChainDefaultsWire, K as DataIntegrityProof, L as DeclineReason, M as DeclineSummaryEntry, N as FulfillmentConfirmation, O as GetDefaultsResult, Q as GetPaymentStatusResponse, T as OwnedAsset, a as ParsedPermit, U as PaymentBlockchainContext, W as PaymentFailure, X as PaymentResponse, Y as PaymentStatus, Z as PaymentSummary, _ as PaymentTimelineResponse, a0 as PaymentTransaction, a1 as PaymentTransactions, a2 as PreparePaymentRequest, a3 as PreparePaymentResponse, a4 as Quote, a5 as QuoteRequestAccepted, a6 as QuoteRequestResponse, a7 as QuoteRequestStatusResponse, a8 as ResolvePaymentResponse, a9 as SenderAuth, aa as SenderAuthMessageScheme, ab as TimelineStep, ac as VerifiableCredential, ad as VerifiableCredentialAuth, V as VerifiedSenderAuth, b as VerifyPaymentRequestExpectations, c as VerifyResult, ae as domain, af as error_code, ag as status, ah as status2, ai as status3, aj as status4, ak as status5, al as status6, am as status7 } from './sender-auth-verify-C-Q-zvAO.js';
2
4
  import { Signer } from 'ethers';
3
5
 
4
6
  type ApiRequestOptions = {
@@ -73,1916 +75,6 @@ declare abstract class BaseHttpRequest {
73
75
  abstract request<T>(options: ApiRequestOptions): CancelablePromise<T>;
74
76
  }
75
77
 
76
- /**
77
- * The result of a counterparty authorization request. Contains either
78
- * the PSP's authorization decision (authorized/declined with proof) or
79
- * an error indicating why authorization could not be completed.
80
- *
81
- */
82
- type AuthorizationResult = {
83
- /**
84
- * Correlation key for this authorization
85
- */
86
- payment_id: string;
87
- /**
88
- * The beneficiary PSP's DID
89
- */
90
- counterparty_did: string;
91
- /**
92
- * Authorization outcome. "authorized" or "declined" when the PSP responded.
93
- * "error" or "timeout" when the authorization could not be completed.
94
- *
95
- */
96
- status: 'authorized' | 'declined' | 'error' | 'timeout';
97
- /**
98
- * The PSP's raw authorization response (present when status is authorized or declined)
99
- */
100
- authorization_response?: {
101
- [key: string]: unknown;
102
- };
103
- /**
104
- * Machine-readable error code (present when status is error or timeout).
105
- * Counterparty-sourced codes are derived from the error code the
106
- * Counterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and
107
- * PROOF_STALE are raised by this gateway itself (no counterparty envelope corresponds).
108
- *
109
- */
110
- error_code?: 'COUNTERPARTY_NOT_FOUND' | 'COUNTERPARTY_TIMEOUT' | 'WEBHOOK_ERROR' | 'WEBHOOK_CONNECTION_ERROR' | 'INTERNAL_ERROR' | 'GATEWAY_TIMEOUT' | 'PROOF_INVALID' | 'PROOF_STALE';
111
- /**
112
- * Human-readable error description
113
- */
114
- error_message?: string;
115
- /**
116
- * HTTP status code from the PSP webhook (only for WEBHOOK_ERROR)
117
- */
118
- webhook_http_status?: number;
119
- };
120
- /**
121
- * Authorization outcome. "authorized" or "declined" when the PSP responded.
122
- * "error" or "timeout" when the authorization could not be completed.
123
- *
124
- */
125
- type status = 'authorized' | 'declined' | 'error' | 'timeout';
126
- /**
127
- * Machine-readable error code (present when status is error or timeout).
128
- * Counterparty-sourced codes are derived from the error code the
129
- * Counterparty Gateway publishes. GATEWAY_TIMEOUT, PROOF_INVALID, and
130
- * PROOF_STALE are raised by this gateway itself (no counterparty envelope corresponds).
131
- *
132
- */
133
- type error_code = 'COUNTERPARTY_NOT_FOUND' | 'COUNTERPARTY_TIMEOUT' | 'WEBHOOK_ERROR' | 'WEBHOOK_CONNECTION_ERROR' | 'INTERNAL_ERROR' | 'GATEWAY_TIMEOUT' | 'PROOF_INVALID' | 'PROOF_STALE';
134
- /**
135
- * Structured payment request with sender authorization and optional W3C Verifiable Credentials
136
- */
137
- type PaymentRequest = {
138
- /**
139
- * Semver-shaped declaration version (MAJOR.MINOR). The major component is locked to this schema's parent directory (v1 → major must be 1). Producers MUST emit the canonical value exported by the bindings' Version constant; the canonical bumps on each additive minor evolution.
140
- */
141
- version: string;
142
- /**
143
- * Unique identifier for this payment request (used for idempotency)
144
- */
145
- request_id: string;
146
- source: OwnedAsset;
147
- /**
148
- * Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
149
- * The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
150
- */
151
- destination: Array<OwnedAsset>;
152
- /**
153
- * The exact amount to be received at the destination (in the smallest unit, e.g., wei for ETH, cents for USD).
154
- */
155
- fulfillment_amount: string;
156
- /**
157
- * The maximum amount willing to be spent from the source (in the smallest unit).
158
- */
159
- max_source_amount?: string;
160
- /**
161
- * Required. The deadline for receiving price quotes from settlement providers. After this
162
- * point no new quotes are accepted. The gateway injects no default and validates the value
163
- * is in the future. The originator must supply it, and a request that omits it or supplies
164
- * a past value is rejected with 400.
165
- */
166
- quote_deadline: string;
167
- /**
168
- * Required. The final deadline for completing the payment. If not completed by this time the
169
- * payment is cancelled and eligible for a refund. The gateway injects no default and validates
170
- * the value is in the future. The originator must supply it, and a request that omits it or
171
- * supplies a past value is rejected with 400.
172
- */
173
- fulfillment_deadline: string;
174
- /**
175
- * Policy requirements for settler authentication. Keys are policy names, values indicate if the policy is required.
176
- */
177
- settler_auth_required?: {
178
- [key: string]: (boolean);
179
- };
180
- sender_auth: SenderAuth;
181
- originator_auth?: VerifiableCredentialAuth;
182
- /**
183
- * Wallet address or public key of a trusted service that will automatically select
184
- * the best exchange rate for your payment. Leave empty to use the default selector.
185
- */
186
- quote_selector?: string;
187
- /**
188
- * Third-party service that will independently verify your payment was delivered.
189
- * Leave empty to use the default verifier.
190
- */
191
- fulfillment_verifier?: {
192
- /**
193
- * The wallet address or public key of the verification service
194
- */
195
- account: string;
196
- /**
197
- * Origin of the fulfillment verifier service, with no path — the caller
198
- * appends the verifier's own API paths. The gateway's `/v1/defaults` response
199
- * supplies the default fulfillment verifier for each chain.
200
- */
201
- endpoint: string;
202
- };
203
- /**
204
- * Escrow contract address, used to protect source funds until proof of fulfillment has been verified. Leave empty to use the default.
205
- */
206
- escrow_contract_address?: string;
207
- /**
208
- * Fulfillment Proxy contract address, used to emit proof of fulfillment on the destination chain. Leave empty to use the default.
209
- */
210
- fulfillment_proxy?: string;
211
- /**
212
- * Optional settler filtering requirements. If whitelist is present, only whitelisted settlers may win. If blacklist is present, blacklisted settlers are excluded. Both can be specified; blacklist takes precedence (a settler in both lists is rejected).
213
- */
214
- settler_requirements?: {
215
- /**
216
- * List of settler DIDs permitted to fulfill this request. If present and non-empty, only these settlers may win. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
217
- */
218
- whitelist?: Array<(string)>;
219
- /**
220
- * List of settler DIDs excluded from fulfilling this request. If present and non-empty, these settlers are rejected. Use W3C DID format (e.g., did:pkh:eip155:1:0xABC...).
221
- */
222
- blacklist?: Array<(string)>;
223
- };
224
- };
225
- /**
226
- * Confirmation details after a payment has been successfully delivered.
227
- * Contains proof of delivery and transaction details for both source and destination chains.
228
- *
229
- */
230
- type FulfillmentConfirmation = {
231
- /**
232
- * Unique identifier for this payment transaction.
233
- * Use this to track the payment across all systems.
234
- *
235
- */
236
- payment_id: string;
237
- /**
238
- * Your original request ID that was provided when creating the payment.
239
- * Helps match confirmations to your internal systems.
240
- *
241
- */
242
- request_id: string;
243
- /**
244
- * Timestamp when the fulfillment was completed
245
- */
246
- fulfillment_timestamp: string;
247
- /**
248
- * The blockchain where funds were locked in escrow, using CAIP-2 format.
249
- * CAIP-2 is a standard way to identify blockchains: {namespace}:{reference}
250
- * Examples:
251
- * - "eip155:1" for Ethereum mainnet
252
- * - "eip155:42161" for Arbitrum
253
- * - "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" for Solana
254
- * - "tron:mainnet" for Tron
255
- *
256
- */
257
- source_chain_id: string;
258
- /**
259
- * The blockchain where the payment was delivered, using CAIP-2 format.
260
- * CAIP-2 is a standard way to identify blockchains: {namespace}:{reference}
261
- * Examples:
262
- * - "eip155:1" for Ethereum mainnet
263
- * - "eip155:42161" for Arbitrum
264
- * - "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" for Solana
265
- * - "tron:mainnet" for Tron
266
- *
267
- */
268
- destination_chain_id: string;
269
- /**
270
- * Transaction hash of the escrow reservation on the source chain
271
- */
272
- source_tx_hash?: string;
273
- /**
274
- * Transaction hash of the fulfillment on the destination chain
275
- */
276
- destination_tx_hash?: string;
277
- /**
278
- * Block number where the source transaction was confirmed
279
- */
280
- source_block_number?: number;
281
- /**
282
- * Block number where the destination transaction was confirmed
283
- */
284
- destination_block_number?: number;
285
- };
286
- /**
287
- * Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.
288
- */
289
- type OwnedAsset = {
290
- /**
291
- * A unique identifier for the asset using CAIP-19 format.
292
- * CAIP-19 is a standard way to identify blockchain assets: {chain_id}/{asset_namespace}:{asset_reference}
293
- * Examples:
294
- * - Ethereum USDC: "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
295
- * - Arbitrum USDC: "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
296
- * - Solana USDC: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
297
- * - Tron USDT: "tron:mainnet/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
298
- */
299
- asset_identifier: string;
300
- /**
301
- * The wallet address that owns this asset.
302
- * Format depends on the blockchain:
303
- * - Ethereum/EVM: 0x-prefixed hex address (42 characters)
304
- * - Solana: Base58 encoded address
305
- * - Tron: T-prefixed Base58 address
306
- *
307
- * A destination account is checked at ingress and must be payable on the chain named by
308
- * its `asset_identifier`: it parses for that chain, carries a valid EIP-55 checksum when
309
- * mixed-case, has no surrounding whitespace, and is not the zero address. A receiver that
310
- * fails any of these is refused with `INVALID_DESTINATION_ACCOUNT`, before any funds move.
311
- */
312
- account: string;
313
- };
314
- /**
315
- * Authorization from the asset owner to execute the payment. The exact format depends on the source blockchain's authorization mechanism.
316
- */
317
- type SenderAuth = {
318
- /**
319
- * DEPRECATED: inner-document credential carrier. Credentials MUST ride ONLY in the holder-signed PaymentRequestEnvelope (PRE); the inner PaymentRequest carries no credential and its Data Integrity signature EXCLUDES this field (stripped before canonicalization on both producer and verifier). Populated only for one back-compat rollout cycle, then removed.
320
- * @deprecated
321
- */
322
- verifiable_credential?: VerifiableCredentialAuth;
323
- message_scheme: SenderAuthMessageScheme;
324
- /**
325
- * Array of signed messages (at least one required)
326
- */
327
- signed_messages: Array<SignedMessage>;
328
- };
329
- /**
330
- * The signature method used for authorizing this payment:
331
- * - `EVM_PERMIT2`: Gasless token approvals for Ethereum/EVM chains
332
- * - `EVM_PERMIT2_ESCROW`: Gasless approvals with escrow support
333
- * - `SOLANA`: Standard Solana transaction signatures
334
- * - `TRON`: Tron transaction signatures
335
- */
336
- type SenderAuthMessageScheme = 'EVM_PERMIT2' | 'EVM_PERMIT2_ESCROW' | 'SOLANA' | 'TRON';
337
- /**
338
- * A message that has been cryptographically signed to prove authorization. The signature proves you control the wallet that's sending funds.
339
- */
340
- type SignedMessage = {
341
- /**
342
- * The data that was signed. Format depends on the blockchain:
343
- * - EVM: Hex-encoded message hash (with 0x prefix)
344
- * - Solana: Hex-encoded message hash (with 0x prefix)
345
- * - Tron: Hex-encoded message hash (possibly without 0x prefix)
346
- */
347
- message: string;
348
- /**
349
- * Optional: If 'message' contains a hash, this field contains the original data before it was hashed. Useful for verification and debugging.
350
- */
351
- message_prehash?: string;
352
- /**
353
- * The cryptographic signature proving you authorized this message. Hex-encoded with a 0x prefix on every supported chain. The signer's own public key is base58 on Solana, but the signature itself is not.
354
- */
355
- signature: string;
356
- /**
357
- * Optional chain-specific payload containing additional signing context (e.g., delegate_signer for Solana). Preserved through the pipeline for downstream consumers.
358
- */
359
- payload?: {
360
- [key: string]: unknown;
361
- };
362
- };
363
- /**
364
- * Optional identity verification using cryptographic credentials.
365
- *
366
- * DEPRECATED. Credentials are moving to a holder-signed W3C VerifiablePresentation that
367
- * travels alongside a request rather than inside it. That envelope is not part of this
368
- * HTTP contract, so there is nothing here to move them to yet: treat this as a legacy
369
- * carrier, and do not build a new integration on it.
370
- */
371
- type VerifiableCredentialAuth = {
372
- verifiable_credential: VerifiableCredential;
373
- /**
374
- * Reference to verification method from the DID Document
375
- */
376
- verification_method_id: string;
377
- /**
378
- * Cryptographic signature matching the verification method type
379
- */
380
- signature: string;
381
- };
382
- /**
383
- * W3C Verifiable Credential structure conforming to the W3C Verifiable Credentials Data Model v1.1
384
- */
385
- type VerifiableCredential = {
386
- /**
387
- * JSON-LD context array, must include 'https://www.w3.org/2018/credentials/v1'
388
- */
389
- '@context': Array<(string)>;
390
- /**
391
- * Unique identifier for this credential
392
- */
393
- id: string;
394
- /**
395
- * Credential types, must include 'VerifiableCredential'
396
- */
397
- type: Array<(string)>;
398
- /**
399
- * DID or issuer object of the credential issuer
400
- */
401
- issuer: string | {
402
- [key: string]: unknown;
403
- };
404
- /**
405
- * When the credential was issued
406
- */
407
- issuanceDate: string;
408
- /**
409
- * When the credential expires
410
- */
411
- expirationDate?: string;
412
- /**
413
- * Claims about the credential subject (structure varies by issuer)
414
- */
415
- credentialSubject: {
416
- [key: string]: unknown;
417
- };
418
- /**
419
- * Information for credential revocation checking. Not consulted by the verifier today.
420
- */
421
- credentialStatus?: {
422
- [key: string]: unknown;
423
- };
424
- /**
425
- * Cryptographic proof of credential integrity
426
- */
427
- proof: {
428
- [key: string]: unknown;
429
- };
430
- };
431
- /**
432
- * Response from submitting a payment request. If settlement completes inside the
433
- * gateway's synchronous window, the response includes a fulfillment_confirmation with
434
- * full settlement details. Otherwise you receive a payment_id plus the payment's
435
- * current `status`, and can poll /v1/payments/{paymentId}/status for updates.
436
- *
437
- * Read `status` before deciding what to do next: a `pending` payment is in flight and
438
- * must NOT be re-submitted under a new request_id (that would be a second payment),
439
- * whereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME
440
- * request_id resolves to the same terminal payment, so a genuine re-attempt needs a
441
- * new request_id.
442
- *
443
- * **A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When
444
- * settlement lands inside the window you get `status: completed`, a full
445
- * `fulfillment_confirmation`, and — since a quote necessarily was awarded to get there —
446
- * `quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to
447
- * verify: recompute `quote_hash` over the returned quote and compare it against the on-chain
448
- * commitment from this response alone.
449
- *
450
- */
451
- type PaymentResponse = {
452
- /**
453
- * Unique ID for tracking this payment. Save this to check status later.
454
- *
455
- */
456
- payment_id: string;
457
- /**
458
- * Current status of the payment, with the same meaning as on
459
- * /v1/payments/{paymentId}/status:
460
- * - `pending`: accepted and being processed
461
- * - `completed`: successfully delivered
462
- * - `failed`: failed (funds returned if escrowed)
463
- * - `cancelled`: cancelled before completion
464
- *
465
- * Present on every response. `completed` is always accompanied by
466
- * fulfillment_confirmation; `failed` is accompanied by `error` where a reason has
467
- * been recorded.
468
- *
469
- */
470
- status: 'pending' | 'completed' | 'failed' | 'cancelled';
471
- /**
472
- * Whether this response describes a payment that already existed, rather than one
473
- * created by this request. `true` means the request_id had been used before and you
474
- * are being handed the ORIGINAL payment — no second payment was created and nothing
475
- * additional was charged.
476
- *
477
- * **Re-attempting a payment.** Re-submit the same request and you get the same payment
478
- * back. You may re-send the original bytes unchanged: the deadlines will have expired by
479
- * then — `quote_deadline` bounds the auction and is short, while this endpoint may hold a
480
- * submission for up to 30 seconds — and an expired deadline on a re-submission is not an
481
- * error, because the request is resolved onto the payment that already exists rather than
482
- * used to create one.
483
- *
484
- * Re-signing with fresh deadlines is equally fine and returns the same payment. What you
485
- * must NOT change is the request_id, and what you must not change under it is the
486
- * payment's economics — source, destination, fulfillment_amount, max_source_amount — which
487
- * are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH. Deadlines and the signature are
488
- * exempt precisely so that a re-attempt is possible.
489
- *
490
- * A genuinely new payment needs a NEW request_id. In particular a `failed` payment is
491
- * terminal: re-submitting its request_id keeps returning that dead payment, so recovering
492
- * means starting a new one under a new key.
493
- *
494
- * Present on every response, `false` for a newly created payment. A response without
495
- * the field is from a gateway predating it, not a newly created payment.
496
- *
497
- * This is the field to read when reconciling a suspected double charge: two
498
- * submissions where the second reports `true` are one payment, whereas two both
499
- * reporting `false` are two. It says nothing about how far the payment has got —
500
- * read `status` for that.
501
- *
502
- */
503
- idempotent_replay: boolean;
504
- /**
505
- * The winning quote's ID. Present when `status` is `completed` — a payment cannot settle
506
- * without an award — and absent on a `pending` response, where no quote has been selected
507
- * yet. Same value and meaning as on GET /v1/payments/{paymentId}/status.
508
- *
509
- */
510
- quote_id?: string;
511
- /**
512
- * The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
513
- * opaque signed document — the PREIMAGE of the `quote_hash` committed on-chain. Same
514
- * value, semantics and canonicalization caveats as on
515
- * GET /v1/payments/{paymentId}/status; see that field for how to verify it.
516
- *
517
- * Present when `status` is `completed`. It may be absent even then, if the stored quote
518
- * is unreadable: the award is reported through `quote_id` regardless, so a present
519
- * `quote_id` with no `fulfillment_quote` means "verification preimage unavailable" and
520
- * never "no quote was awarded". A consumer that requires the preimage should fall back to
521
- * the status endpoint rather than treat the payment as unverified.
522
- *
523
- */
524
- fulfillment_quote?: {
525
- [key: string]: unknown;
526
- };
527
- fulfillment_confirmation?: FulfillmentConfirmation;
528
- error?: PaymentError;
529
- };
530
- /**
531
- * Current status of the payment, with the same meaning as on
532
- * /v1/payments/{paymentId}/status:
533
- * - `pending`: accepted and being processed
534
- * - `completed`: successfully delivered
535
- * - `failed`: failed (funds returned if escrowed)
536
- * - `cancelled`: cancelled before completion
537
- *
538
- * Present on every response. `completed` is always accompanied by
539
- * fulfillment_confirmation; `failed` is accompanied by `error` where a reason has
540
- * been recorded.
541
- *
542
- */
543
- type status2 = 'pending' | 'completed' | 'failed' | 'cancelled';
544
- type GetPaymentStatusResponse = {
545
- /**
546
- * The payment ID you're checking status for.
547
- *
548
- */
549
- payment_id?: string;
550
- /**
551
- * Current status of your payment:
552
- * - `pending`: Payment is being processed
553
- * - `completed`: Payment successfully delivered
554
- * - `failed`: Payment failed (funds returned if escrowed)
555
- * - `cancelled`: Payment was cancelled before completion
556
- *
557
- */
558
- status?: 'pending' | 'completed' | 'failed' | 'cancelled';
559
- /**
560
- * When the status was last updated
561
- */
562
- updated_at?: string;
563
- /**
564
- * The winning quote's ID. Present once a quote has been awarded for this payment;
565
- * absent while the payment is still collecting or awarding. Cross-references the
566
- * `quote_id` returned by GET /v1/payments/quote-requests/{quoteRequestId}.
567
- *
568
- */
569
- quote_id?: string;
570
- /**
571
- * The settler-signed FulfillmentQuote for the winning quote, returned verbatim as an
572
- * opaque signed document (structurally the canonical FulfillmentQuote/v1 declaration at
573
- * https://schemas.atum.xyz/declarations/FulfillmentQuote/v1). Present once a quote has
574
- * been awarded — including after the payment completes and `fulfillment_confirmation` is
575
- * populated, since that is precisely when a consumer verifies.
576
- *
577
- * This is the PREIMAGE of the `quote_hash` committed on-chain in the escrow deposit and
578
- * reserve witnesses. On-chain we commit only the hash, so a quote-selector consumer
579
- * recomputes quote_hash over these bytes and compares it against the on-chain commitment
580
- * to confirm the payment settled against the quote it selected ("trust but verify"), and
581
- * verifies the settler signature over the same bytes.
582
- *
583
- * quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON
584
- * key-order/whitespace normalization and across JSON string-escaping differences. The
585
- * returned bytes are hash-equivalent to, but not necessarily byte-identical with, what
586
- * the settler emitted (quotes are stored as JSONB, which normalizes on write). The
587
- * gateway still never re-serializes the quote through a typed struct (that renormalizes
588
- * timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw
589
- * JSON passthrough.
590
- *
591
- */
592
- fulfillment_quote?: {
593
- [key: string]: unknown;
594
- };
595
- fulfillment_confirmation?: FulfillmentConfirmation;
596
- error?: PaymentError;
597
- /**
598
- * How many settler agents this payment's auction was broadcast to. Absent means
599
- * unknown, never zero.
600
- *
601
- */
602
- requested_count?: number;
603
- /**
604
- * Why the payment drew few or no quotes. Read from the same settler reports as the
605
- * quote-request endpoints, keyed by this payment, so a payment that failed on an expired
606
- * quote deadline can say WHY nobody funded it instead of only that nobody did.
607
- *
608
- * Every declining agent is counted exactly once under its most recent reason. Empty means
609
- * no agent declined against this payment, absent means the breakdown could not be read. A
610
- * payment awarded out of a quote-request batch was bid on at quote time, so its declines
611
- * are keyed to that batch and are read from the batch's status endpoint rather than here.
612
- * As on the quote-request endpoints, the free-form decline detail is never relayed.
613
- *
614
- */
615
- decline_summary?: Array<DeclineSummaryEntry>;
616
- };
617
- /**
618
- * Error details when payment status is "failed".
619
- * Only present when the payment has failed. Contains a machine-readable
620
- * code for programmatic handling and a human-readable message for debugging.
621
- *
622
- */
623
- type PaymentError = {
624
- /**
625
- * Public error category in SCREAMING_SNAKE_CASE.
626
- * Common codes:
627
- * - `SETTLEMENT_FAILED`: The settlement could not be completed
628
- * - `NO_QUOTES_RECEIVED`: No quotes arrived within the auction window
629
- * - `INTERNAL_ERROR`: An unexpected error occurred
630
- *
631
- */
632
- code: string;
633
- /**
634
- * Human-readable error description with additional context.
635
- *
636
- */
637
- message: string;
638
- /**
639
- * Service domain where the error originated.
640
- *
641
- */
642
- domain?: 'PAYMENT_GATEWAY' | 'SETTLER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
643
- blockchain_context?: PaymentBlockchainContext;
644
- };
645
- /**
646
- * Service domain where the error originated.
647
- *
648
- */
649
- type domain = 'PAYMENT_GATEWAY' | 'SETTLER_GATEWAY' | 'SETTLER_AGENT' | 'WALLET_ORCHESTRATION' | 'VERIFICATION_SERVICE' | 'BLOCKCHAIN' | 'EXTERNAL_SERVICE';
650
- /**
651
- * Blockchain-specific error context. Only present when the error
652
- * originated from an on-chain operation (e.g., escrow revert,
653
- * fulfillment failure).
654
- *
655
- */
656
- type PaymentBlockchainContext = {
657
- /**
658
- * CAIP-2 chain identifier
659
- */
660
- chain_id?: string;
661
- /**
662
- * Failed transaction hash
663
- */
664
- tx_hash?: string;
665
- /**
666
- * Block number where error occurred
667
- */
668
- block_number?: number;
669
- /**
670
- * Contract address involved in the error
671
- */
672
- contract_address?: string;
673
- /**
674
- * Smart contract revert reason
675
- */
676
- revert_reason?: string;
677
- /**
678
- * Gas consumed before failure
679
- */
680
- gas_used?: string;
681
- /**
682
- * Estimated gas needed for success
683
- */
684
- estimated_gas_needed?: string;
685
- };
686
- /**
687
- * Human-readable payment request parameters for generating an unsigned PaymentRequest.
688
- * Asset identifiers use a CAIP-19-like format with "/" separator and support friendly names.
689
- *
690
- */
691
- type PreparePaymentRequest = {
692
- /**
693
- * Unique identifier for tracking this payment request.
694
- * Used for idempotency and matching responses to requests.
695
- *
696
- */
697
- request_id: string;
698
- /**
699
- * Source asset in human-readable CAIP-19-like format: {chain}/{asset}
700
- * Supports both friendly names and full CAIP-19 identifiers:
701
- * - "ethereum/usdc" (friendly names)
702
- * - "eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" (full CAIP-19)
703
- *
704
- */
705
- source_asset: string;
706
- /**
707
- * Wallet address that will send the payment
708
- */
709
- source_account: string;
710
- /**
711
- * Destination asset in human-readable CAIP-19-like format: {chain}/{asset}
712
- * Supports both friendly names and full CAIP-19 identifiers:
713
- * - "arbitrum/usdc"
714
- * - "eip155:42161/erc20:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
715
- *
716
- */
717
- destination_asset: string;
718
- /**
719
- * Wallet address that will receive the payment
720
- */
721
- destination_account: string;
722
- /**
723
- * Simple amount specification in decimal format (e.g., "1.50" for $1.50 USDC).
724
- * Use this OR specify both max_source_amount and fulfillment_amount.
725
- * Cannot be used together with max_source_amount/fulfillment_amount.
726
- *
727
- */
728
- amount?: string;
729
- /**
730
- * Maximum amount willing to spend from source (in decimal format).
731
- * Must be specified together with fulfillment_amount.
732
- * Cannot be used together with amount field.
733
- *
734
- */
735
- max_source_amount?: string;
736
- /**
737
- * Exact amount to be fulfilled at destination (in decimal format).
738
- * Must be specified together with max_source_amount.
739
- * Cannot be used together with amount field.
740
- *
741
- */
742
- fulfillment_amount?: string;
743
- /**
744
- * Seconds until quote deadline (from now).
745
- * How long to wait for settlement provider quotes.
746
- *
747
- */
748
- quote_deadline_seconds?: number;
749
- /**
750
- * Seconds until fulfillment deadline (from now).
751
- * Final deadline for completing the payment.
752
- *
753
- */
754
- fulfillment_deadline_seconds?: number;
755
- };
756
- /**
757
- * Complete unsigned PaymentRequest ready for signing.
758
- * Contains all resolved technical details and typed data ready for signing.
759
- *
760
- */
761
- type PreparePaymentResponse = {
762
- /**
763
- * Complete PaymentRequest with signature field set to null.
764
- * Client should fill in the signature field(s) in
765
- * sender_auth.signed_messages, either by signing the message_hash
766
- * field in signed_messages or by using typed data signing on the
767
- * message_prehash field in signed messages, and then submit the full
768
- * object to POST /v1/payments.
769
- *
770
- */
771
- payment_request: PaymentRequest;
772
- };
773
- type ResolvePaymentResponse = {
774
- /**
775
- * The payment ID that corresponds to the given request ID
776
- */
777
- payment_id: string;
778
- };
779
- /**
780
- * Step-by-step view of a payment's settlement lifecycle. Includes a route
781
- * summary, a list of steps with timings, and if the payment failed, a
782
- * structured error describing where and why.
783
- *
784
- */
785
- type PaymentTimelineResponse = {
786
- payment_id: string;
787
- /**
788
- * High-level status:
789
- * - `pending`: Bidding, awarded, or early in settlement
790
- * - `settling`: Settlement in progress (on-chain steps executing)
791
- * - `completed`: Payment successfully delivered
792
- * - `failed`: Payment failed
793
- * - `cancelled`: Payment was cancelled
794
- *
795
- */
796
- status: 'pending' | 'settling' | 'completed' | 'failed' | 'cancelled';
797
- created_at: string;
798
- updated_at: string;
799
- /**
800
- * Total time from first step to last completed step (only set for terminal states)
801
- */
802
- total_duration_ms?: number;
803
- summary?: PaymentSummary;
804
- error?: TimelineError;
805
- steps: Array<TimelineStep>;
806
- };
807
- /**
808
- * High-level status:
809
- * - `pending`: Bidding, awarded, or early in settlement
810
- * - `settling`: Settlement in progress (on-chain steps executing)
811
- * - `completed`: Payment successfully delivered
812
- * - `failed`: Payment failed
813
- * - `cancelled`: Payment was cancelled
814
- *
815
- */
816
- type status3 = 'pending' | 'settling' | 'completed' | 'failed' | 'cancelled';
817
- /**
818
- * Top-level context about the payment (parties, assets, amounts)
819
- */
820
- type PaymentSummary = {
821
- /**
822
- * CAIP-19 identifier of the source asset
823
- */
824
- source_asset?: string;
825
- source_account?: string;
826
- dest_asset?: string;
827
- dest_account?: string;
828
- /**
829
- * Raw fulfillment amount in smallest token units
830
- */
831
- fulfillment_amount?: string;
832
- /**
833
- * Human-readable formatted amount with symbol, e.g. "1.00 USDC".
834
- * Only set when the source asset's decimals are known via the token registry.
835
- *
836
- */
837
- display_amount?: string;
838
- /**
839
- * Raw max source amount in smallest token units
840
- */
841
- max_source_amount?: string;
842
- request_id?: string;
843
- };
844
- /**
845
- * Structured error details when a payment has failed
846
- */
847
- type TimelineError = {
848
- /**
849
- * Machine-readable error code
850
- */
851
- code: string;
852
- /**
853
- * Human-readable error description
854
- */
855
- message: string;
856
- /**
857
- * Which component reported the error
858
- */
859
- domain?: string;
860
- /**
861
- * CAIP-2 chain where the error occurred (if on-chain)
862
- */
863
- chain_id?: string;
864
- /**
865
- * Transaction hash of the failed on-chain attempt (if applicable)
866
- */
867
- tx_hash?: string;
868
- /**
869
- * Smart-contract revert reason (if the error was an on-chain revert)
870
- */
871
- revert_reason?: string;
872
- };
873
- type TimelineStep = {
874
- /**
875
- * Internal name of the step (matches settlement event type)
876
- */
877
- name: string;
878
- /**
879
- * Human-readable label
880
- */
881
- label: string;
882
- /**
883
- * Current status of this step:
884
- * - `completed`: Step finished successfully
885
- * - `in_progress`: Step currently executing
886
- * - `pending`: Step hasn't started yet
887
- * - `failed`: Step errored out
888
- * - `skipped`: Step will never execute because an earlier step failed
889
- *
890
- */
891
- status: 'completed' | 'in_progress' | 'pending' | 'failed' | 'skipped';
892
- /**
893
- * When the step completed (if it has)
894
- */
895
- timestamp?: string;
896
- /**
897
- * Time this step took, measured from the previous step
898
- */
899
- duration_ms?: number;
900
- /**
901
- * CAIP-2 chain this step happened on (if on-chain)
902
- */
903
- chain_id?: string;
904
- /**
905
- * Transaction hash associated with this step (if on-chain)
906
- */
907
- tx_hash?: string;
908
- /**
909
- * Additional step-specific data (e.g. block_number, settler, reason)
910
- */
911
- details?: {
912
- [key: string]: unknown;
913
- };
914
- };
915
- /**
916
- * Current status of this step:
917
- * - `completed`: Step finished successfully
918
- * - `in_progress`: Step currently executing
919
- * - `pending`: Step hasn't started yet
920
- * - `failed`: Step errored out
921
- * - `skipped`: Step will never execute because an earlier step failed
922
- *
923
- */
924
- type status4 = 'completed' | 'in_progress' | 'pending' | 'failed' | 'skipped';
925
- /**
926
- * Safe, outward-facing error. Derived from an internal error through the shared error catalog. The public code identifies the category and the message is a curated, safe description.
927
- *
928
- * A panic is caught by shared middleware that responds `{"error": "Internal server error occurred"}` instead, so a 500 is not guaranteed to carry this shape.
929
- */
930
- type ErrorResponse = {
931
- /**
932
- * Public, machine-readable error category in SCREAMING_SNAKE_CASE.
933
- */
934
- code: string;
935
- /**
936
- * Curated, safe, human-readable message.
937
- */
938
- message: string;
939
- /**
940
- * Correlation id to quote to support to locate the internal error record.
941
- */
942
- request_id?: string;
943
- /**
944
- * The payment this error was raised against. Absent when the error is not about a specific payment.
945
- */
946
- payment_id?: string;
947
- /**
948
- * Link to the documentation page for this public code.
949
- */
950
- docs_url?: string;
951
- /**
952
- * Originating service domain.
953
- */
954
- domain?: string;
955
- /**
956
- * What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.
957
- * Re-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new operation. See https://docs.atum.xyz/errors for the value set.
958
- */
959
- retry_classification?: string;
960
- };
961
- /**
962
- * Request body for opening a quote-request batch. Structurally the existing PaymentRequest
963
- * with `sender_auth` omitted (the spend authorization is deferred to the award call); see
964
- * schemas/declarations/PaymentRequest/v1/schema.json.
965
- *
966
- */
967
- type CreateQuoteRequest = {
968
- /**
969
- * Semver-shaped declaration version (MAJOR.MINOR), locked to major 1 for v1. Producers emit
970
- * the canonical value exported by the bindings' Version constant.
971
- *
972
- */
973
- version: string;
974
- /**
975
- * Client-supplied idempotency key for this quote-request. The same request_id from the
976
- * same originator returns the same quote_request_id. Independent of the award-call request_id.
977
- *
978
- */
979
- request_id: string;
980
- source: OwnedAsset;
981
- /**
982
- * Array of destination assets for the settlement agent to choose from (at least one required, at most 16).
983
- * The ceiling bounds the fan-out one request can buy: every consumer iterates this list.
984
- *
985
- */
986
- destination: Array<OwnedAsset>;
987
- /**
988
- * The exact amount to be received at the destination (smallest unit, e.g. wei or cents).
989
- */
990
- fulfillment_amount: string;
991
- /**
992
- * Optional cap on what the originator is willing to spend from source (smallest unit).
993
- * Quotes with source_amount above this are filtered. No cap applied if omitted.
994
- *
995
- */
996
- max_source_amount?: string;
997
- /**
998
- * Required. End of the collection window. After this point no new quotes are accepted.
999
- * The gateway injects no default and never mutates the originator-supplied body, so the
1000
- * value is carried through verbatim to the award call. It must be supplied and must be in
1001
- * the future. Must be strictly earlier than fulfillment_deadline.
1002
- *
1003
- */
1004
- quote_deadline: string;
1005
- /**
1006
- * Required. Final deadline for completing the payment. Past it the payment is cancelled and
1007
- * eligible for refund. The gateway injects no default and never mutates the
1008
- * originator-supplied body, so the value is carried through verbatim to the award call. It
1009
- * must be supplied and must be in the future. Must be strictly later than quote_deadline.
1010
- *
1011
- */
1012
- fulfillment_deadline: string;
1013
- /**
1014
- * Policy requirements for settler authentication. Keys are policy names, values indicate if required.
1015
- */
1016
- settler_auth_required?: {
1017
- [key: string]: (boolean);
1018
- };
1019
- originator_auth?: VerifiableCredentialAuth;
1020
- /**
1021
- * Wallet address or public key of a trusted service that auto-selects the best rate.
1022
- * Leave empty to use the default selector.
1023
- *
1024
- */
1025
- quote_selector?: string;
1026
- /**
1027
- * Optional third-party service that independently verifies delivery. Leave empty for the default verifier.
1028
- */
1029
- fulfillment_verifier?: {
1030
- /**
1031
- * The wallet address or public key of the verification service
1032
- */
1033
- account: string;
1034
- /**
1035
- * Origin of the fulfillment verifier service, with no path — the caller
1036
- * appends the verifier's own API paths. The gateway's `/v1/defaults` response
1037
- * supplies the default fulfillment verifier for each chain.
1038
- *
1039
- */
1040
- endpoint: string;
1041
- };
1042
- /**
1043
- * Optional escrow contract address. Leave empty to use the default.
1044
- */
1045
- escrow_contract_address?: string;
1046
- /**
1047
- * Optional fulfillment-proxy contract address on the destination chain. Leave empty to use the default.
1048
- */
1049
- fulfillment_proxy?: string;
1050
- /**
1051
- * Optional settler filtering. If whitelist is present, only whitelisted settlers may win.
1052
- * If blacklist is present, blacklisted settlers are excluded. Both can be specified;
1053
- * blacklist takes precedence (a settler in both is rejected).
1054
- *
1055
- */
1056
- settler_requirements?: {
1057
- /**
1058
- * Settler DIDs permitted to fulfill this request (W3C DID format). If present, only these may win.
1059
- */
1060
- whitelist?: Array<(string)>;
1061
- /**
1062
- * Settler DIDs excluded from fulfilling this request (W3C DID format).
1063
- */
1064
- blacklist?: Array<(string)>;
1065
- };
1066
- /**
1067
- * Optional JSON-LD context URLs — present when the originator wraps the request in a W3C
1068
- * Data Integrity envelope so a downstream verifier can recover the signer identity.
1069
- *
1070
- */
1071
- '@context'?: Array<(string)>;
1072
- proof?: DataIntegrityProof;
1073
- /**
1074
- * Optional document-level W3C Verifiable Credentials (e.g. KnownToAtum about the request producer).
1075
- */
1076
- verifiableCredential?: Array<VerifiableCredential>;
1077
- };
1078
- /**
1079
- * W3C Data Integrity proof conforming to the Data Integrity 1.0 specification. Which of jws or proofValue is required depends on the cryptosuite named in type, and that pairing is checked where the proof is verified rather than by this schema, so a document can satisfy the schema and still be refused at verification.
1080
- */
1081
- type DataIntegrityProof = {
1082
- /**
1083
- * Proof type identifier. ECDSA-secp256k1 (recoverable, EVM-compatible) for did:pkh:eip155:* signers; Ed25519 for did:pkh:solana:* signers.
1084
- */
1085
- type: string;
1086
- /**
1087
- * ISO 8601 timestamp when the proof was created. Canonicalize the value exactly as it appears in the raw JSON: parsing it into a date-time and re-serializing can change the spelling (Z versus +00:00), and a different spelling canonicalizes to different bytes, so the signature no longer verifies.
1088
- */
1089
- created: string;
1090
- /**
1091
- * DID URL identifying the verification method, e.g., 'did:pkh:eip155:1:0x...#blockchainAccountId' for ECDSA or 'did:pkh:solana:<chain>:<addr>#SolanaMethod2021' for Ed25519.
1092
- */
1093
- verificationMethod: string;
1094
- /**
1095
- * Purpose of the proof (e.g., assertionMethod, authentication).
1096
- */
1097
- proofPurpose: string;
1098
- /**
1099
- * Detached JWS signature in <base64url(header)>..<base64url(sig)> form, header {alg:ES256K-R, b64:false, crit:[b64]}. Required at runtime for EcdsaSecp256k1RecoverySignature2020.
1100
- */
1101
- jws?: string;
1102
- /**
1103
- * Multibase-encoded raw signature bytes. Required at runtime for Ed25519Signature2020; mutually exclusive with jws in practice.
1104
- */
1105
- proofValue?: string;
1106
- };
1107
- /**
1108
- * One collected quote — the content-hash identifier plus the verbatim settler-signed FulfillmentQuote.
1109
- */
1110
- type Quote = {
1111
- /**
1112
- * Canonical content-hash of the signed quote bytes; identifies the quote server-side at
1113
- * award time. Provided as a convenience — the gateway re-derives it from
1114
- * bid_award.fulfillment_quote_json.
1115
- *
1116
- */
1117
- quote_id: string;
1118
- /**
1119
- * The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
1120
- * declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
1121
- * verbatim as an opaque signed document. A client recomputes quote_hash over the returned
1122
- * bytes and verifies the settler signature, then re-embeds them into
1123
- * bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
1124
- * (URDNA2015), so it is stable across JSON key-order/whitespace normalization. The
1125
- * returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the
1126
- * settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway
1127
- * still never re-serializes the quote through a typed struct (that renormalizes timestamp
1128
- * values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.
1129
- *
1130
- */
1131
- fulfillment_quote: {
1132
- [key: string]: unknown;
1133
- };
1134
- };
1135
- /**
1136
- * A collected quote in the status response, annotated with its award linkage.
1137
- */
1138
- type AwardedQuote = {
1139
- quote_id: string;
1140
- /**
1141
- * The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1
1142
- * declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned
1143
- * verbatim as an opaque signed document. A client recomputes quote_hash over the returned
1144
- * bytes and verifies the settler signature, then re-embeds them into
1145
- * bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based
1146
- * (URDNA2015), so it is stable across JSON key-order/whitespace normalization. The
1147
- * returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the
1148
- * settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway
1149
- * still never re-serializes the quote through a typed struct (that renormalizes timestamp
1150
- * values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough.
1151
- *
1152
- */
1153
- fulfillment_quote: {
1154
- [key: string]: unknown;
1155
- };
1156
- /**
1157
- * payment_id if this quote was awarded; null otherwise. Under MVP single-award, at most
1158
- * one quote per batch carries a non-null value.
1159
- *
1160
- */
1161
- awarded_payment_id?: string | null;
1162
- };
1163
- /**
1164
- * A (quote_id, payment_id) pair for an awarded quote in a batch.
1165
- */
1166
- type AwardedPayment = {
1167
- quote_id: string;
1168
- payment_id: string;
1169
- };
1170
- /**
1171
- * Synchronous response to POST /v1/payments/quote-requests. Self-contained — the corridor
1172
- * fields are echoed at the response root so a drop-recovery client can build the award call
1173
- * without retaining the original request body.
1174
- *
1175
- * The corridor echoed here describes the batch you actually receive. On an idempotent
1176
- * replay that is the ORIGINAL batch's corridor and window, which may differ from what you
1177
- * just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
1178
- *
1179
- */
1180
- type QuoteRequestResponse = {
1181
- /**
1182
- * Gateway-generated resource ID for the batch, used in subsequent status reads and awards.
1183
- */
1184
- quote_request_id: string;
1185
- /**
1186
- * Collection-phase outcome of the create call:
1187
- * - `ready` — collection complete; `quotes` populated. If no settler bid, this is still
1188
- * `ready` with an empty `quotes` array (a successful "no quotes available" result —
1189
- * distinct from `expired`, which only applies to collected quotes that later lapse).
1190
- * - `collecting` — the sync wait cap fired before the quote deadline; poll the status endpoint for quotes.
1191
- * The `awarded` and `expired` lifecycle states are observed only via the status endpoint, not here.
1192
- *
1193
- */
1194
- status: 'collecting' | 'ready';
1195
- /**
1196
- * Whether this response describes a batch that already existed, rather than one opened
1197
- * by this request. `true` means the `request_id` had been used before and you are being
1198
- * handed the ORIGINAL batch — no second batch was opened and no second broadcast went
1199
- * out to settlement agents.
1200
- *
1201
- * **Re-attempting a quote-request.** Re-submit the same request and you get the same
1202
- * batch back. You may re-send the original bytes unchanged: `quote_deadline` bounds the
1203
- * collection window and is short, so it will usually have expired by the time you
1204
- * retry, and an expired deadline on a re-submission is not an error — the request is
1205
- * resolved onto the batch that already exists rather than used to open one.
1206
- * Re-signing with fresh deadlines is equally fine and returns the same batch.
1207
- *
1208
- * The window is NOT extended either way: it belongs to the batch, and `quote_deadline`
1209
- * in this response is the batch's own. Read `status` to see whether collection is
1210
- * still running.
1211
- *
1212
- * What you must not change under one `request_id` is the corridor's economics —
1213
- * accounts, assets, or amounts — which are rejected with 409
1214
- * IDEMPOTENCY_TERMS_MISMATCH rather than resolved onto the first batch. A genuinely
1215
- * different corridor needs a new `request_id`.
1216
- *
1217
- * Present on every response, `false` for a newly opened batch. A response without the
1218
- * field is from a gateway predating it, not a newly opened batch.
1219
- *
1220
- */
1221
- idempotent_replay: boolean;
1222
- source?: OwnedAsset;
1223
- destination?: Array<OwnedAsset>;
1224
- fulfillment_amount?: string;
1225
- max_source_amount?: string;
1226
- fulfillment_deadline?: string;
1227
- quote_deadline?: string;
1228
- /**
1229
- * Collected quotes. Present when status is `ready` — an empty array if no settler bid.
1230
- */
1231
- quotes?: Array<Quote>;
1232
- /**
1233
- * How many agents the request was broadcast to, so silence is distinguishable from a
1234
- * decline without a second call. Same meaning and same absence rule as on the status
1235
- * endpoint: absent means unknown, never zero.
1236
- *
1237
- */
1238
- requested_count?: number;
1239
- /**
1240
- * Why the request drew few or no quotes, carried here so that a `ready` response with an
1241
- * empty `quotes` array explains itself rather than requiring a follow-up read.
1242
- *
1243
- * Same counting rules as the status endpoint: every declining agent counted exactly once
1244
- * under its most recent reason, empty when nobody declined, absent when the detail could not
1245
- * be read. Provisional while `status` is `collecting`, because agents are still responding.
1246
- *
1247
- */
1248
- decline_summary?: Array<DeclineSummaryEntry>;
1249
- };
1250
- /**
1251
- * Collection-phase outcome of the create call:
1252
- * - `ready` — collection complete; `quotes` populated. If no settler bid, this is still
1253
- * `ready` with an empty `quotes` array (a successful "no quotes available" result —
1254
- * distinct from `expired`, which only applies to collected quotes that later lapse).
1255
- * - `collecting` — the sync wait cap fired before the quote deadline; poll the status endpoint for quotes.
1256
- * The `awarded` and `expired` lifecycle states are observed only via the status endpoint, not here.
1257
- *
1258
- */
1259
- type status5 = 'collecting' | 'ready';
1260
- /**
1261
- * Asynchronous (202) response to POST /v1/payments/quote-requests. Returns the batch handle
1262
- * plus the echoed corridor; quotes are retrieved via the status endpoint.
1263
- *
1264
- * The corridor echoed here describes the batch you actually receive. On an idempotent
1265
- * replay that is the ORIGINAL batch's corridor and window, which may differ from what you
1266
- * just sent in the ways a retry is allowed to differ (the deadlines, and address casing).
1267
- *
1268
- */
1269
- type QuoteRequestAccepted = {
1270
- quote_request_id: string;
1271
- /**
1272
- * Always `collecting` — a constant on this response, not a report of the batch's state.
1273
- * On an idempotent replay the batch's window may already have closed; read
1274
- * GET /v1/payments/quote-requests/{quoteRequestId} for its actual state.
1275
- *
1276
- */
1277
- status: 'collecting';
1278
- /**
1279
- * Whether this response describes a batch that already existed, rather than one opened
1280
- * by this request. `true` means the `request_id` had been used before and you are being
1281
- * handed the ORIGINAL batch — no second batch was opened and no second broadcast went
1282
- * out to settlement agents.
1283
- *
1284
- * The idempotency contract is the same as on the synchronous (200) response: a
1285
- * re-submission may carry expired deadlines and is resolved onto the existing batch
1286
- * rather than rejected, the collection window is the batch's own and is not extended,
1287
- * and differing economics are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH rather than
1288
- * collapsed onto the first batch.
1289
- *
1290
- * Present on every response, `false` for a newly opened batch. A response without the
1291
- * field is from a gateway predating it, not a newly opened batch.
1292
- *
1293
- */
1294
- idempotent_replay: boolean;
1295
- source?: OwnedAsset;
1296
- destination?: Array<OwnedAsset>;
1297
- fulfillment_amount?: string;
1298
- max_source_amount?: string;
1299
- fulfillment_deadline?: string;
1300
- quote_deadline?: string;
1301
- };
1302
- /**
1303
- * Always `collecting` — a constant on this response, not a report of the batch's state.
1304
- * On an idempotent replay the batch's window may already have closed; read
1305
- * GET /v1/payments/quote-requests/{quoteRequestId} for its actual state.
1306
- *
1307
- */
1308
- type status6 = 'collecting';
1309
- /**
1310
- * Response to GET /v1/payments/quote-requests/{quoteRequestId}. The `status` enum describes
1311
- * the quote-request batch lifecycle and is disjoint from the payment-status enum.
1312
- *
1313
- */
1314
- type QuoteRequestStatusResponse = {
1315
- quote_request_id: string;
1316
- /**
1317
- * Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
1318
- * from the payment-status enum returned by the award and payment-status endpoints.
1319
- * - `collecting` — collection window still open; `quotes` lists those collected so far
1320
- * (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until
1321
- * `collection_close`).
1322
- * - `ready` — collection complete; none awarded yet; either at least one quote is still
1323
- * within its `award_deadline`, or no settler bid (empty `quotes` array — the successful
1324
- * "no quotes available" result).
1325
- * - `awarded` — a quote produced a payment row; no further awards accepted (MVP).
1326
- * - `expired` — collection closed, nothing awarded, and every collected quote is now past
1327
- * its `award_deadline` ("quotes lapsed"). An empty batch is `ready`, not `expired` — the
1328
- * two are deliberately distinct ("no quotes available" vs "quotes lapsed").
1329
- *
1330
- */
1331
- status: 'collecting' | 'ready' | 'awarded' | 'expired';
1332
- /**
1333
- * Collected quotes with award linkage — those collected so far while `collecting`, the full set once the window closes.
1334
- */
1335
- quotes?: Array<AwardedQuote>;
1336
- /**
1337
- * Flat list of awarded (quote_id, payment_id) pairs. At most one entry under MVP single-award.
1338
- */
1339
- payments?: Array<AwardedPayment>;
1340
- /**
1341
- * How many agents the request was broadcast to. The only auction count that is not
1342
- * derivable from the rest of this response:
1343
- *
1344
- * - quoted = `quotes` length
1345
- * - declined = sum of `decline_summary[].count`
1346
- * - participated = quoted + declined
1347
- * - silent = `requested_count` - participated
1348
- *
1349
- * Silence and a decline are different signals, which is why the denominator is surfaced
1350
- * rather than left implicit.
1351
- *
1352
- * ABSENT when the number is unknown, which happens when the broadcast count was never
1353
- * recorded or when the auction detail could not be read. Absence means unknown, never zero,
1354
- * so `silent` is derivable only when this field is present.
1355
- *
1356
- */
1357
- requested_count?: number;
1358
- /**
1359
- * Why the request drew few or no quotes, so a caller can tell "nobody can fund this right
1360
- * now" from "my request was malformed".
1361
- *
1362
- * EXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most
1363
- * recent reason, so the counts sum to the number of agents that declined. An agent that
1364
- * declined more than once with different reasons is counted once, not once per reason.
1365
- *
1366
- * Empty means nobody declined. ABSENT means the auction detail could not be read, so the
1367
- * breakdown is unknown. While `status` is `collecting` it is provisional, because agents are
1368
- * still responding.
1369
- *
1370
- * The free-form decline detail is never relayed, because that detail carries an agent's
1371
- * balances and would let a caller map inventory by polling cheap quote-requests across
1372
- * corridors.
1373
- *
1374
- */
1375
- decline_summary?: Array<DeclineSummaryEntry>;
1376
- };
1377
- /**
1378
- * Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint
1379
- * from the payment-status enum returned by the award and payment-status endpoints.
1380
- * - `collecting` — collection window still open; `quotes` lists those collected so far
1381
- * (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until
1382
- * `collection_close`).
1383
- * - `ready` — collection complete; none awarded yet; either at least one quote is still
1384
- * within its `award_deadline`, or no settler bid (empty `quotes` array — the successful
1385
- * "no quotes available" result).
1386
- * - `awarded` — a quote produced a payment row; no further awards accepted (MVP).
1387
- * - `expired` — collection closed, nothing awarded, and every collected quote is now past
1388
- * its `award_deadline` ("quotes lapsed"). An empty batch is `ready`, not `expired` — the
1389
- * two are deliberately distinct ("no quotes available" vs "quotes lapsed").
1390
- *
1391
- */
1392
- type status7 = 'collecting' | 'ready' | 'awarded' | 'expired';
1393
- type DeclineSummaryEntry = {
1394
- reason: DeclineReason;
1395
- /**
1396
- * Agents whose most recent decline reason was this one. Counts agents, never rows, and an
1397
- * agent appears under one reason only.
1398
- *
1399
- */
1400
- count: number;
1401
- /**
1402
- * What would have to change for a settler giving this reason to bid, drawn from the same
1403
- * closed set as the `retry_classification` on an error response so a caller reads one
1404
- * vocabulary.
1405
- *
1406
- * It describes the decline only. The authoritative instruction for the payment is the
1407
- * `retry_classification` on its own error response: a payment can fail for a reason no
1408
- * settler named, and it can succeed while some settlers declined.
1409
- *
1410
- * Optional, and a pattern-constrained string for the same reason `DeclineReason` is.
1411
- *
1412
- */
1413
- retry_classification?: string;
1414
- };
1415
- /**
1416
- * A settler's reason for not bidding, projected from its internal reason code through
1417
- * the shared decline catalog (`apis/decline/v1/catalog.json`), which is the single
1418
- * source of truth for the reason set. Several internal codes may map to one public
1419
- * reason.
1420
- *
1421
- * Deliberately a pattern-constrained string rather than a closed enum. The set grows
1422
- * whenever a settler gains a cause worth naming, and a consumer whose generated client
1423
- * closes the set rejects the whole response on a value it has not seen. Treat an
1424
- * unrecognised value as `OTHER`.
1425
- *
1426
- * `OTHER` covers a reason whose detail is settler-authored free text, and any reason
1427
- * this gateway does not recognise. Both are counted so the summary stays exhaustive,
1428
- * without relaying text we neither author nor validate.
1429
- *
1430
- */
1431
- type DeclineReason = string;
1432
- /**
1433
- * Request body for POST /v1/payments/awards. Carries the two originator-signed artifacts:
1434
- * `sender_auth` (Permit2 deposit authorization) and a fully-formed `bid_award` declaration.
1435
- * The awarded quote is derived server-side from bid_award.fulfillment_quote_json — no
1436
- * explicit quote_id on the wire.
1437
- *
1438
- */
1439
- type AwardRequest = {
1440
- /**
1441
- * Client-supplied idempotency key for this award call. Independent of the quote-request's request_id.
1442
- */
1443
- request_id: string;
1444
- sender_auth: SenderAuth;
1445
- bid_award: BidAward;
1446
- };
1447
- /**
1448
- * Fully-formed, originator-signed bid award. Mirrors schemas/declarations/BidAward/v1/schema.json.
1449
- * `authorization` carries the Escrow reserve-witness signature naming the chosen settler;
1450
- * `fulfillment_quote_json` is the verbatim settler-signed quote string received in the quote
1451
- * response (carrying the settler's proof).
1452
- *
1453
- */
1454
- type BidAward = {
1455
- /**
1456
- * Semver-shaped declaration version (MAJOR.MINOR), locked to major 1 for v1. Producers emit
1457
- * the canonical value exported by the bindings' Version constant.
1458
- *
1459
- */
1460
- version: string;
1461
- authorization: SignedMessage;
1462
- /**
1463
- * The settler-signed FulfillmentQuote received in the quote response, forwarded verbatim.
1464
- * Verification is canonicalization-based — the settler's W3C Data Integrity proof is checked
1465
- * over the canonicalized form, and `quote_id` is derived as the canonical content-hash — so a
1466
- * JSON decode/re-encode that only changes key order or whitespace does not invalidate it.
1467
- * Clients SHOULD still forward the received bytes as-is rather than rebuild the object; the
1468
- * SDK helpers do this and also expose settler-proof verification.
1469
- *
1470
- */
1471
- fulfillment_quote_json: string;
1472
- /**
1473
- * Optional JSON-LD context URLs when the award is wrapped in a W3C Data Integrity envelope.
1474
- */
1475
- '@context'?: Array<(string)>;
1476
- proof?: DataIntegrityProof;
1477
- /**
1478
- * Optional W3C Verifiable Credentials attesting the award producer.
1479
- */
1480
- verifiableCredential?: Array<VerifiableCredential>;
1481
- };
1482
- /**
1483
- * Synchronous response to POST /v1/payments/awards. The `status` field describes the payment
1484
- * lifecycle. Note there are two distinct status surfaces for a Quote-API payment, with
1485
- * different vocabularies: (1) this award response (`awarding`/`completed`/…), and
1486
- * (2) the separate GET /v1/payments/{paymentId}/status endpoint you poll afterward, which
1487
- * reports the same payment under its own values (an in-progress payment reads as `pending`
1488
- * there). Both are disjoint from the quote-request batch status on the quote-request endpoints.
1489
- *
1490
- */
1491
- type AwardResponse = {
1492
- payment_id: string;
1493
- /**
1494
- * Payment lifecycle status on the award response:
1495
- * - `completed` — settlement finished within the sync wait (includes fulfillment_confirmation).
1496
- * - `awarding` — settlement still in progress when the sync cap fired (or on wait=false);
1497
- * poll GET /v1/payments/{paymentId}/status.
1498
- * - `failed` — settlement reached a terminal failure (e.g. the settler could not fulfill, or
1499
- * an on-chain step was rejected).
1500
- * - `cancelled` — the payment was terminated before settlement completed and will not proceed.
1501
- * `failed` and `cancelled` are terminal states surfaced here only when they occur within the
1502
- * sync wait; otherwise the response is `awarding` and the terminal state is read from the
1503
- * payment-status endpoint.
1504
- *
1505
- */
1506
- status: 'awarding' | 'completed' | 'failed' | 'cancelled';
1507
- fulfillment_confirmation?: FulfillmentConfirmation;
1508
- };
1509
- /**
1510
- * Payment lifecycle status on the award response:
1511
- * - `completed` — settlement finished within the sync wait (includes fulfillment_confirmation).
1512
- * - `awarding` — settlement still in progress when the sync cap fired (or on wait=false);
1513
- * poll GET /v1/payments/{paymentId}/status.
1514
- * - `failed` — settlement reached a terminal failure (e.g. the settler could not fulfill, or
1515
- * an on-chain step was rejected).
1516
- * - `cancelled` — the payment was terminated before settlement completed and will not proceed.
1517
- * `failed` and `cancelled` are terminal states surfaced here only when they occur within the
1518
- * sync wait; otherwise the response is `awarding` and the terminal state is read from the
1519
- * payment-status endpoint.
1520
- *
1521
- */
1522
- type status8 = 'awarding' | 'completed' | 'failed' | 'cancelled';
1523
- /**
1524
- * Asynchronous (202) response to POST /v1/payments/awards — just the payment handle.
1525
- */
1526
- type AwardAccepted = {
1527
- payment_id: string;
1528
- /**
1529
- * Always `awarding` — settlement is in progress server-side.
1530
- */
1531
- status: 'awarding';
1532
- };
1533
- /**
1534
- * Always `awarding` — settlement is in progress server-side.
1535
- */
1536
- type status9 = 'awarding';
1537
- /**
1538
- * The addresses for one chain. Optional fields appear only where they apply to that
1539
- * chain; an absent optional field is not an error.
1540
- *
1541
- */
1542
- type ChainDefaults$1 = {
1543
- /**
1544
- * CAIP-2 identifier of the chain these defaults describe, normalised to lower case.
1545
- */
1546
- chain_id: string;
1547
- /**
1548
- * The account named as the reserver in the deposit authorization. Sign against this exact value; a deposit reserved by anyone else is rejected.
1549
- */
1550
- quote_selector: string;
1551
- /**
1552
- * The escrow the deposit is made into, and the spender of the token approval. Empty when the chain is not fully configured.
1553
- */
1554
- escrow_contract: string;
1555
- /**
1556
- * The contract that pays the receiver. Read this from the DESTINATION chain's defaults, not the source chain's. Empty when the chain is not fully configured.
1557
- */
1558
- fulfillment_proxy: string;
1559
- /**
1560
- * The service that attests settlement, and the account it signs with.
1561
- */
1562
- fulfillment_verifier: {
1563
- /**
1564
- * The account named as the releaser in the deposit authorization. Sign against this exact value.
1565
- */
1566
- account: string;
1567
- /**
1568
- * Base URL of the fulfillment verifier serving this chain.
1569
- */
1570
- endpoint: string;
1571
- };
1572
- /**
1573
- * The Permit2 this chain's escrow verifies against, sent only when it is not the canonical deployment. When absent, use the canonical Permit2 address for the chain. EVM and Tron only.
1574
- */
1575
- permit2_contract?: string;
1576
- /**
1577
- * Which deposit witness this chain's escrow expects. `4` and above select the four-member witness, `3` the two-member one; absent means four. EVM and Tron only - on Solana this is carried by `svm_signature_domain_version`.
1578
- */
1579
- deposit_witness_version?: number;
1580
- /**
1581
- * Tokens this chain's escrow accepts for deposit. Absent when the gateway has no listing for the chain, which does not mean no token is accepted.
1582
- */
1583
- tokens?: Array<{
1584
- symbol: string;
1585
- /**
1586
- * Token contract address, in the chain's native address format.
1587
- */
1588
- address: string;
1589
- /**
1590
- * Decimal places, for converting a human amount to base units.
1591
- */
1592
- decimals: number;
1593
- }>;
1594
- /**
1595
- * Solana only. The cluster the escrow's signing domain is bound to, needed to build the deposit hash. Absent for EVM and Tron.
1596
- */
1597
- svm_signature_cluster_id?: string;
1598
- /**
1599
- * Solana only. Version of the escrow's signing domain. Absent for EVM and Tron.
1600
- */
1601
- svm_signature_domain_version?: number;
1602
- };
1603
- /**
1604
- * Either one chain's defaults or every chain keyed by CAIP-2 chain id, depending on whether `chain_id` was supplied. A top-level `chain_id` identifies the first.
1605
- */
1606
- type GetDefaultsResult = ChainDefaults$1 | ChainDefaultsByChain;
1607
- /**
1608
- * Defaults for every chain the gateway serves, keyed by CAIP-2 chain id. Each key repeats the `chain_id` of the value it maps to.
1609
- */
1610
- type ChainDefaultsByChain = {
1611
- [key: string]: ChainDefaults$1;
1612
- };
1613
- type SubmitPaymentData = {
1614
- requestBody: PaymentRequest;
1615
- };
1616
- type SubmitPaymentResponse = PaymentResponse;
1617
- type GetPaymentStatusData = {
1618
- /**
1619
- * The ID of the payment to query
1620
- */
1621
- paymentId: string;
1622
- };
1623
- type GetPaymentStatusResponse2 = GetPaymentStatusResponse;
1624
- type ResolvePaymentData = {
1625
- /**
1626
- * The client-supplied request ID embedded in the payment request
1627
- */
1628
- requestId: string;
1629
- };
1630
- type ResolvePaymentResponse2 = ResolvePaymentResponse;
1631
- type GetPaymentTimelineData = {
1632
- /**
1633
- * The ID of the payment to query
1634
- */
1635
- paymentId: string;
1636
- };
1637
- type GetPaymentTimelineResponse = PaymentTimelineResponse;
1638
- type PreparePaymentData = {
1639
- requestBody: PreparePaymentRequest;
1640
- };
1641
- type PreparePaymentResponse2 = PreparePaymentResponse;
1642
- type AuthorizePaymentData = {
1643
- requestBody: PaymentRequest;
1644
- };
1645
- type AuthorizePaymentResponse = AuthorizationResult;
1646
- type CreateQuoteRequestData = {
1647
- requestBody: CreateQuoteRequest;
1648
- /**
1649
- * Return a handle immediately (`false`, default) or hold the connection for collected quotes (`true`).
1650
- */
1651
- wait?: boolean;
1652
- };
1653
- type CreateQuoteRequestResponse = QuoteRequestResponse | QuoteRequestAccepted;
1654
- type GetQuoteRequestStatusData = {
1655
- /**
1656
- * The ID of the quote-request batch to query
1657
- */
1658
- quoteRequestId: string;
1659
- };
1660
- type GetQuoteRequestStatusResponse = QuoteRequestStatusResponse;
1661
- type AwardQuoteData = {
1662
- requestBody: AwardRequest;
1663
- /**
1664
- * Return a handle immediately (`false`, default) or hold the connection for the payment result (`true`).
1665
- */
1666
- wait?: boolean;
1667
- };
1668
- type AwardQuoteResponse = AwardResponse | AwardAccepted;
1669
- type GetDefaultsData = {
1670
- /**
1671
- * CAIP-2 chain identifier. Omit it, or send it empty, to receive every chain the gateway serves, keyed by chain id.
1672
- */
1673
- chainId?: string;
1674
- };
1675
- type GetDefaultsResponse = GetDefaultsResult;
1676
- type HealthCheckResponse = {
1677
- status?: string;
1678
- };
1679
- type $OpenApiTs = {
1680
- '/v1/payments': {
1681
- post: {
1682
- req: SubmitPaymentData;
1683
- res: {
1684
- /**
1685
- * Payment request submitted successfully
1686
- */
1687
- 200: PaymentResponse;
1688
- /**
1689
- * Invalid request
1690
- */
1691
- 400: ErrorResponse;
1692
- /**
1693
- * Signature or sender authorization could not be verified
1694
- */
1695
- 401: ErrorResponse;
1696
- /**
1697
- * Payment declined during counterparty authorization
1698
- */
1699
- 403: ErrorResponse;
1700
- /**
1701
- * The `request_id` has already been used for a payment with different economics
1702
- * (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a retry is
1703
- * made safe, so it must identify one payment; use a distinct `request_id` per
1704
- * payment.
1705
- *
1706
- */
1707
- 409: ErrorResponse;
1708
- /**
1709
- * Payment request too large to process
1710
- */
1711
- 413: ErrorResponse;
1712
- /**
1713
- * Internal server error
1714
- */
1715
- 500: ErrorResponse;
1716
- /**
1717
- * The request was not accepted: a dependency is temporarily unavailable, or this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the request is safe to retry.
1718
- */
1719
- 503: ErrorResponse;
1720
- };
1721
- };
1722
- };
1723
- '/v1/payments/{paymentId}/status': {
1724
- get: {
1725
- req: GetPaymentStatusData;
1726
- res: {
1727
- /**
1728
- * Payment status retrieved successfully
1729
- */
1730
- 200: GetPaymentStatusResponse;
1731
- /**
1732
- * Payment not found
1733
- */
1734
- 404: ErrorResponse;
1735
- /**
1736
- * Internal server error
1737
- */
1738
- 500: ErrorResponse;
1739
- };
1740
- };
1741
- };
1742
- '/v1/payments/resolve': {
1743
- get: {
1744
- req: ResolvePaymentData;
1745
- res: {
1746
- /**
1747
- * Payment found
1748
- */
1749
- 200: ResolvePaymentResponse;
1750
- /**
1751
- * Missing request_id parameter
1752
- */
1753
- 400: ErrorResponse;
1754
- /**
1755
- * No payment found for the given request ID
1756
- */
1757
- 404: ErrorResponse;
1758
- /**
1759
- * Internal server error
1760
- */
1761
- 500: ErrorResponse;
1762
- };
1763
- };
1764
- };
1765
- '/v1/payments/{paymentId}/timeline': {
1766
- get: {
1767
- req: GetPaymentTimelineData;
1768
- res: {
1769
- /**
1770
- * Timeline retrieved successfully
1771
- */
1772
- 200: PaymentTimelineResponse;
1773
- /**
1774
- * Payment not found
1775
- */
1776
- 404: ErrorResponse;
1777
- /**
1778
- * Internal server error
1779
- */
1780
- 500: ErrorResponse;
1781
- };
1782
- };
1783
- };
1784
- '/v1/payments/prepare': {
1785
- post: {
1786
- req: PreparePaymentData;
1787
- res: {
1788
- /**
1789
- * Payment request prepared successfully
1790
- */
1791
- 200: PreparePaymentResponse;
1792
- /**
1793
- * Invalid request parameters
1794
- */
1795
- 400: ErrorResponse;
1796
- /**
1797
- * Endpoint not yet implemented
1798
- */
1799
- 501: ErrorResponse;
1800
- };
1801
- };
1802
- };
1803
- '/v1/payments/authorizations': {
1804
- post: {
1805
- req: AuthorizePaymentData;
1806
- res: {
1807
- /**
1808
- * Authorization decision received (authorized or declined)
1809
- */
1810
- 200: AuthorizationResult;
1811
- /**
1812
- * The request was rejected before authorization was attempted, so no
1813
- * authorization outcome exists.
1814
- *
1815
- */
1816
- 400: ErrorResponse;
1817
- /**
1818
- * The counterparty's proof was rejected (`PROOF_INVALID` or `PROOF_STALE`).
1819
- * This is an authorization outcome, so the body is an `AuthorizationResult`
1820
- * with `status: error`.
1821
- *
1822
- */
1823
- 401: AuthorizationResult;
1824
- /**
1825
- * Counterparty not found (no registration for the resolved DID). An
1826
- * authorization outcome, so the body is an `AuthorizationResult` with
1827
- * `status: error` and `error_code: COUNTERPARTY_NOT_FOUND`.
1828
- *
1829
- */
1830
- 404: AuthorizationResult;
1831
- /**
1832
- * Either shape, depending on where the failure happened. A failure before
1833
- * authorization was attempted returns `ErrorResponse`. A failure carrying an
1834
- * authorization outcome returns `AuthorizationResult` with `status: error`.
1835
- *
1836
- */
1837
- 500: ErrorResponse | AuthorizationResult;
1838
- /**
1839
- * Counterparty webhook error (HTTP error or connection failure). An
1840
- * authorization outcome, so the body is an `AuthorizationResult` with
1841
- * `status: error` and `error_code: WEBHOOK_ERROR` or
1842
- * `WEBHOOK_CONNECTION_ERROR`.
1843
- *
1844
- */
1845
- 502: AuthorizationResult;
1846
- /**
1847
- * Authorization timed out (the counterparty did not respond). An
1848
- * authorization outcome, so the body is an `AuthorizationResult` with
1849
- * `status: timeout`.
1850
- *
1851
- */
1852
- 504: AuthorizationResult;
1853
- };
1854
- };
1855
- };
1856
- '/v1/payments/quote-requests': {
1857
- post: {
1858
- req: CreateQuoteRequestData;
1859
- res: {
1860
- /**
1861
- * Quote-request resolved synchronously. `status` is `ready` when quotes were collected,
1862
- * or `collecting` when the sync wait cap fired before the quote deadline.
1863
- *
1864
- */
1865
- 200: QuoteRequestResponse;
1866
- /**
1867
- * Quote-request accepted; collection continues asynchronously.
1868
- */
1869
- 202: QuoteRequestAccepted;
1870
- /**
1871
- * Invalid request. `QUOTE_DEADLINE_NOT_FUTURE` is the one worth planning for: a NEW
1872
- * quote-request whose `quote_deadline` has already passed is refused, because there is
1873
- * no window left to collect quotes in. It does not apply to a re-submission — an
1874
- * already-used `request_id` resolves onto the batch that exists and its expired
1875
- * deadline is ignored, which is what makes a retry recoverable.
1876
- *
1877
- */
1878
- 400: ErrorResponse;
1879
- /**
1880
- * The `request_id` has already been used for a quote-request with different
1881
- * economics (`IDEMPOTENCY_TERMS_MISMATCH`). Re-submitting one `request_id` is how a
1882
- * retry is made safe, so it must identify one batch; use a distinct `request_id`
1883
- * per quote-request.
1884
- *
1885
- */
1886
- 409: ErrorResponse;
1887
- /**
1888
- * Internal server error
1889
- */
1890
- 500: ErrorResponse;
1891
- /**
1892
- * The request was not accepted: a dependency is temporarily unavailable, or this operation is paused (`SERVICE_PAUSED`). Nothing was submitted, so the request is safe to retry.
1893
- */
1894
- 503: ErrorResponse;
1895
- };
1896
- };
1897
- };
1898
- '/v1/payments/quote-requests/{quoteRequestId}': {
1899
- get: {
1900
- req: GetQuoteRequestStatusData;
1901
- res: {
1902
- /**
1903
- * Quote-request status retrieved successfully
1904
- */
1905
- 200: QuoteRequestStatusResponse;
1906
- /**
1907
- * Quote-request not found, or not owned by the caller.
1908
- */
1909
- 404: ErrorResponse;
1910
- /**
1911
- * Internal server error
1912
- */
1913
- 500: ErrorResponse;
1914
- };
1915
- };
1916
- };
1917
- '/v1/payments/awards': {
1918
- post: {
1919
- req: AwardQuoteData;
1920
- res: {
1921
- /**
1922
- * Award resolved synchronously. `status` is `completed` with a fulfillment_confirmation
1923
- * when settlement finished within the sync wait, or a non-terminal payment status
1924
- * (e.g. `awarding`) if the cap fired first.
1925
- *
1926
- */
1927
- 200: AwardResponse;
1928
- /**
1929
- * Award accepted; settlement continues asynchronously.
1930
- */
1931
- 202: AwardAccepted;
1932
- /**
1933
- * Invalid request (bad signatures, expired quote, or ownership mismatch)
1934
- */
1935
- 400: ErrorResponse;
1936
- /**
1937
- * The quote, or another quote in the same batch, has already been awarded
1938
- * (single-award-per-batch, FR-09).
1939
- *
1940
- */
1941
- 409: ErrorResponse;
1942
- /**
1943
- * Internal server error
1944
- */
1945
- 500: ErrorResponse;
1946
- };
1947
- };
1948
- };
1949
- '/v1/defaults': {
1950
- get: {
1951
- req: GetDefaultsData;
1952
- res: {
1953
- /**
1954
- * Chain defaults. A single object when `chain_id` was supplied, otherwise an object keyed by CAIP-2 chain id.
1955
- */
1956
- 200: GetDefaultsResult;
1957
- /**
1958
- * The `chain_id` is not a valid CAIP-2 chain identifier
1959
- */
1960
- 400: ErrorResponse;
1961
- /**
1962
- * The requested chain is not served by this gateway, or - when `chain_id` was omitted - no chain could be resolved at all
1963
- */
1964
- 404: ErrorResponse;
1965
- /**
1966
- * A dependency is temporarily unavailable
1967
- */
1968
- 503: ErrorResponse;
1969
- };
1970
- };
1971
- };
1972
- '/health': {
1973
- get: {
1974
- res: {
1975
- /**
1976
- * Service is healthy
1977
- */
1978
- 200: {
1979
- status?: string;
1980
- };
1981
- };
1982
- };
1983
- };
1984
- };
1985
-
1986
78
  declare class PaymentsService {
1987
79
  readonly httpRequest: BaseHttpRequest;
1988
80
  constructor(httpRequest: BaseHttpRequest);
@@ -2285,10 +377,10 @@ interface ChainDefaults {
2285
377
  permit2Contract?: string;
2286
378
  /**
2287
379
  * Which deposit witness the escrow deployed on this chain pins, surfaced by payment-gw
2288
- * `/v1/defaults` as `deposit_witness_version` (CORE-2033). EVM/Tron only — Solana carries the
380
+ * `/v1/defaults` as `deposit_witness_version`. EVM/Tron only — Solana carries the
2289
381
  * same fact in `svmSignatureDomainVersion` below.
2290
382
  *
2291
- * `4` and above select the CORE-2120 four-member witness
383
+ * `4` and above select the four-member witness
2292
384
  * (`depositRequestHash`, `destination`, `reserver`, `releaser`); `3` selects the two-member
2293
385
  * witness a not-yet-redeployed escrow pins. ABSENT means four — see the sender-auth package's
2294
386
  * `ChainDefaults.depositWitnessVersion` for why absence is the permissive default.
@@ -2604,7 +696,7 @@ declare const $PaymentRequest: {
2604
696
  readonly fulfillment_deadline: {
2605
697
  readonly type: "string";
2606
698
  readonly format: "date-time";
2607
- readonly description: "Required. The final deadline for completing the payment. If not completed by this time the\npayment is cancelled and eligible for a refund. The gateway injects no default and validates\nthe value is in the future. The originator must supply it, and a request that omits it or\nsupplies a past value is rejected with 400.";
699
+ readonly description: "Required. The final deadline for completing the payment. If not completed by this time the\npayment fails and is eligible for a refund. The gateway injects no default and validates\nthe value is in the future. The originator must supply it, and a request that omits it or\nsupplies a past value is rejected with 400.";
2608
700
  readonly example: "2024-12-25T11:00:00Z";
2609
701
  };
2610
702
  readonly settler_auth_required: {
@@ -2896,9 +988,57 @@ declare const $VerifiableCredential: {
2896
988
  };
2897
989
  };
2898
990
  };
991
+ declare const $PaymentStatus: {
992
+ readonly type: "string";
993
+ readonly description: "Where your payment is in its lifecycle. One payment reads the same however you ask\nabout it.\n\n- `pending`: accepted and in progress. Nothing has reached the recipient yet.\n- `finalizing`: the transaction paying your recipient is on chain and is accruing\n the confirmations its chain requires. NOT FINAL, see below.\n- `completed`: delivered, with the required confirmations behind it.\n- `failed`: did not complete. Any funds held in escrow are returned, and `error`\n describes what went wrong.\n\n`completed` and `failed` are final and will not change afterwards. `pending` and\n`finalizing` will.\n\n**Do not treat `finalizing` as delivered.** It says the payment has been made on\nchain but is not yet irreversible, much as a card authorization is not yet a\nsettlement. It normally becomes `completed`, and it can still become `failed` if\nthe transaction never reaches the confirmation depth its chain requires. Acting on\n`finalizing` — releasing goods, crediting an account — means accepting that risk\ndeliberately, at whatever threshold suits you rather than the one we wait for.\n\n`finalizing` is about paying the recipient. While your own funds are still being\ncommitted on the source chain the payment is `pending`, because nothing has reached\nthe recipient yet.\n";
994
+ readonly enum: readonly ["pending", "finalizing", "completed", "failed"];
995
+ readonly example: "pending";
996
+ };
997
+ declare const $PaymentTransaction: {
998
+ readonly type: "object";
999
+ readonly description: "One on-chain transaction belonging to a payment: which chain, which transaction, and\nwhich block it landed in.\n\nWhether the payment has actually happened is answered by `status`, not here. Read this\nto look the transaction up on chain and to verify it yourself.\n";
1000
+ readonly required: readonly ["transaction_hash", "chain_id"];
1001
+ readonly properties: {
1002
+ readonly transaction_hash: {
1003
+ readonly type: "string";
1004
+ readonly description: "The transaction's hash on its chain. Hex hashes carry the `0x` prefix, including on\nTron, whose own tooling omits it.\n";
1005
+ readonly pattern: "^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$";
1006
+ readonly example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
1007
+ };
1008
+ readonly chain_id: {
1009
+ readonly type: "string";
1010
+ readonly description: "CAIP-2 identifier of the chain the transaction is on.";
1011
+ readonly pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$";
1012
+ readonly example: "eip155:42161";
1013
+ };
1014
+ readonly block_number: {
1015
+ readonly type: "integer";
1016
+ readonly description: "The block the transaction landed in. Absent until it has been mined.\n\nProvisional while `status` is `finalizing`: on a chain that settles against another,\na reorganization there can move the transaction to a different block. Settled once\n`status` is `completed` — keep it as a final record only from then.\n";
1017
+ readonly example: 61234567;
1018
+ };
1019
+ };
1020
+ };
1021
+ declare const $PaymentTransactions: {
1022
+ readonly type: "object";
1023
+ readonly description: "The transactions a payment has produced, one entry per stage, added as each becomes\nknown. A stage absent here has produced no transaction yet.\n\nThese are the two movements that decide whether your payment happened: your funds\nbeing committed, and your recipient being paid. Present on every outcome, so a\npayment that did not complete can still be traced on chain.\n`fulfillment_confirmation` is not a substitute: it is written only once a payment\ncompletes, and describes the finished delivery rather than progress towards it.\n\nWhere a stage is attempted more than once, the entry describes the attempt that\ncounts — the one that succeeded, or the last one if none did.\n";
1024
+ readonly properties: {
1025
+ readonly deposit: {
1026
+ readonly allOf: readonly [{
1027
+ readonly $ref: "#/components/schemas/PaymentTransaction";
1028
+ }];
1029
+ readonly description: "Committing your funds on the source chain.";
1030
+ };
1031
+ readonly fulfillment: {
1032
+ readonly allOf: readonly [{
1033
+ readonly $ref: "#/components/schemas/PaymentTransaction";
1034
+ }];
1035
+ readonly description: "Paying your recipient on the destination chain.";
1036
+ };
1037
+ };
1038
+ };
2899
1039
  declare const $PaymentResponse: {
2900
1040
  readonly type: "object";
2901
- readonly description: "Response from submitting a payment request. If settlement completes inside the\ngateway's synchronous window, the response includes a fulfillment_confirmation with\nfull settlement details. Otherwise you receive a payment_id plus the payment's\ncurrent `status`, and can poll /v1/payments/{paymentId}/status for updates.\n\nRead `status` before deciding what to do next: a `pending` payment is in flight and\nmust NOT be re-submitted under a new request_id (that would be a second payment),\nwhereas a `failed` or `cancelled` one is terminal — re-submitting it under the SAME\nrequest_id resolves to the same terminal payment, so a genuine re-attempt needs a\nnew request_id.\n\n**A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When\nsettlement lands inside the window you get `status: completed`, a full\n`fulfillment_confirmation`, and — since a quote necessarily was awarded to get there —\n`quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to\nverify: recompute `quote_hash` over the returned quote and compare it against the on-chain\ncommitment from this response alone.\n";
1041
+ readonly description: "Response from submitting a payment request. If settlement completes inside the\ngateway's synchronous window, the response includes a fulfillment_confirmation with\nfull settlement details. Otherwise you receive a payment_id plus the payment's\ncurrent `status`, and can poll /v1/payments/{paymentId}/status for updates.\n\nRead `status` before deciding what to do next: a `pending` or `finalizing` payment is\nin flight and must NOT be re-submitted under a new request_id (that would be a second\npayment), whereas a `failed` one is terminal — re-submitting it under the SAME\nrequest_id resolves to the same terminal payment, so a genuine re-attempt needs a\nnew request_id.\n\n**A synchronously-completed payment carries proof of QUOTE as well as of delivery.** When\nsettlement lands inside the window you get `status: completed`, a full\n`fulfillment_confirmation`, and — since a quote necessarily was awarded to get there —\n`quote_id` and `fulfillment_quote`. The fast path therefore needs no follow-up call to\nverify: recompute `quote_hash` over the returned quote and compare it against the on-chain\ncommitment from this response alone.\n\n`status` is present on every response. `completed` is always accompanied by\nfulfillment_confirmation; `failed` is accompanied by `error` where a reason has been\nrecorded.\n";
2902
1042
  readonly required: readonly ["payment_id", "status", "idempotent_replay"];
2903
1043
  readonly properties: {
2904
1044
  readonly payment_id: {
@@ -2907,9 +1047,10 @@ declare const $PaymentResponse: {
2907
1047
  readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
2908
1048
  };
2909
1049
  readonly status: {
2910
- readonly type: "string";
2911
- readonly enum: readonly ["pending", "completed", "failed", "cancelled"];
2912
- readonly description: "Current status of the payment, with the same meaning as on\n/v1/payments/{paymentId}/status:\n- `pending`: accepted and being processed\n- `completed`: successfully delivered\n- `failed`: failed (funds returned if escrowed)\n- `cancelled`: cancelled before completion\n\nPresent on every response. `completed` is always accompanied by\nfulfillment_confirmation; `failed` is accompanied by `error` where a reason has\nbeen recorded.\n";
1050
+ readonly $ref: "#/components/schemas/PaymentStatus";
1051
+ };
1052
+ readonly transactions: {
1053
+ readonly $ref: "#/components/schemas/PaymentTransactions";
2913
1054
  };
2914
1055
  readonly idempotent_replay: {
2915
1056
  readonly type: "boolean";
@@ -2930,7 +1071,7 @@ declare const $PaymentResponse: {
2930
1071
  readonly $ref: "#/components/schemas/FulfillmentConfirmation";
2931
1072
  };
2932
1073
  readonly error: {
2933
- readonly $ref: "#/components/schemas/PaymentError";
1074
+ readonly $ref: "#/components/schemas/PaymentFailure";
2934
1075
  };
2935
1076
  };
2936
1077
  };
@@ -2943,9 +1084,10 @@ declare const $GetPaymentStatusResponse: {
2943
1084
  readonly example: "0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f";
2944
1085
  };
2945
1086
  readonly status: {
2946
- readonly type: "string";
2947
- readonly enum: readonly ["pending", "completed", "failed", "cancelled"];
2948
- readonly description: "Current status of your payment:\n- `pending`: Payment is being processed\n- `completed`: Payment successfully delivered\n- `failed`: Payment failed (funds returned if escrowed)\n- `cancelled`: Payment was cancelled before completion\n";
1087
+ readonly $ref: "#/components/schemas/PaymentStatus";
1088
+ };
1089
+ readonly transactions: {
1090
+ readonly $ref: "#/components/schemas/PaymentTransactions";
2949
1091
  };
2950
1092
  readonly updated_at: {
2951
1093
  readonly type: "string";
@@ -2966,7 +1108,7 @@ declare const $GetPaymentStatusResponse: {
2966
1108
  readonly $ref: "#/components/schemas/FulfillmentConfirmation";
2967
1109
  };
2968
1110
  readonly error: {
2969
- readonly $ref: "#/components/schemas/PaymentError";
1111
+ readonly $ref: "#/components/schemas/PaymentFailure";
2970
1112
  };
2971
1113
  readonly requested_count: {
2972
1114
  readonly type: "integer";
@@ -2982,27 +1124,37 @@ declare const $GetPaymentStatusResponse: {
2982
1124
  };
2983
1125
  };
2984
1126
  };
2985
- declare const $PaymentError: {
1127
+ declare const $PaymentFailure: {
2986
1128
  readonly type: "object";
2987
- readonly description: "Error details when payment status is \"failed\".\nOnly present when the payment has failed. Contains a machine-readable\ncode for programmatic handling and a human-readable message for debugging.\n";
1129
+ readonly description: "Why a payment failed. Present only when `status` is `failed`, and identical\nhowever you ask about the payment.\n\n`code` is the stable, machine-readable identity of the failure — branch on it\nrather than on `message`, which is written for a person and may be reworded.\n`docs_url` points at the page describing that code.\n";
2988
1130
  readonly required: readonly ["code", "message"];
2989
1131
  readonly properties: {
2990
1132
  readonly code: {
2991
1133
  readonly type: "string";
2992
- readonly description: "Public error category in SCREAMING_SNAKE_CASE.\nCommon codes:\n- `SETTLEMENT_FAILED`: The settlement could not be completed\n- `NO_QUOTES_RECEIVED`: No quotes arrived within the auction window\n- `INTERNAL_ERROR`: An unexpected error occurred\n";
1134
+ readonly description: "Public error category in SCREAMING_SNAKE_CASE. Common codes:\n- `SETTLEMENT_FAILED`: the settlement could not be completed\n- `NO_QUOTES_RECEIVED`: no quotes arrived within the auction window\n- `INTERNAL_ERROR`: an unexpected error occurred\n";
2993
1135
  readonly example: "SETTLEMENT_FAILED";
2994
1136
  };
2995
1137
  readonly message: {
2996
1138
  readonly type: "string";
2997
- readonly description: "Human-readable error description with additional context.\n";
1139
+ readonly description: "Human-readable description of the failure, for a person reading it. Do not\nbranch on this text.\n";
2998
1140
  readonly example: "No quotes received within the auction window";
2999
1141
  };
3000
1142
  readonly domain: {
3001
1143
  readonly type: "string";
3002
- readonly description: "Service domain where the error originated.\n";
1144
+ readonly description: "Which part of the system reported the failure.\n";
3003
1145
  readonly enum: readonly ["PAYMENT_GATEWAY", "SETTLER_GATEWAY", "SETTLER_AGENT", "WALLET_ORCHESTRATION", "VERIFICATION_SERVICE", "BLOCKCHAIN", "EXTERNAL_SERVICE"];
3004
1146
  readonly example: "PAYMENT_GATEWAY";
3005
1147
  };
1148
+ readonly docs_url: {
1149
+ readonly type: "string";
1150
+ readonly format: "uri";
1151
+ readonly description: "Link to the documentation page for this public code.";
1152
+ };
1153
+ readonly retry_classification: {
1154
+ readonly type: "string";
1155
+ readonly description: "What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry.\nRe-sending the same `request_id` is an idempotent replay and always safe. This value is about submitting a new one, which starts a new payment. See https://docs.atum.xyz/errors for the value set.";
1156
+ readonly example: "RECONCILE_THEN_DECIDE";
1157
+ };
3006
1158
  readonly blockchain_context: {
3007
1159
  readonly $ref: "#/components/schemas/PaymentBlockchainContext";
3008
1160
  };
@@ -3010,44 +1162,45 @@ declare const $PaymentError: {
3010
1162
  };
3011
1163
  declare const $PaymentBlockchainContext: {
3012
1164
  readonly type: "object";
3013
- readonly description: "Blockchain-specific error context. Only present when the error\noriginated from an on-chain operation (e.g., escrow revert,\nfulfillment failure).\n";
1165
+ readonly description: "Where on chain a failed payment failed. Present only when the failure happened\non chain — an escrow revert, or a fulfillment that could not be delivered — so a\npayment that failed before any transaction was sent carries no context here.";
3014
1166
  readonly properties: {
3015
1167
  readonly chain_id: {
3016
1168
  readonly type: "string";
3017
1169
  readonly description: "CAIP-2 chain identifier";
3018
- readonly example: "eip155:42161";
1170
+ readonly pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$";
3019
1171
  };
3020
- readonly tx_hash: {
1172
+ readonly transaction_hash: {
3021
1173
  readonly type: "string";
3022
1174
  readonly description: "Failed transaction hash";
3023
- readonly example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef";
1175
+ readonly pattern: "^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{32,88})$";
3024
1176
  };
3025
1177
  readonly block_number: {
3026
1178
  readonly type: "integer";
3027
1179
  readonly description: "Block number where error occurred";
3028
- readonly example: 12345678;
3029
1180
  };
3030
1181
  readonly contract_address: {
3031
1182
  readonly type: "string";
3032
- readonly description: "Contract address involved in the error";
3033
- readonly example: "0x1234567890abcdef1234567890abcdef12345678";
1183
+ readonly description: "Contract that caused the error";
1184
+ readonly pattern: "^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$";
3034
1185
  };
3035
1186
  readonly revert_reason: {
3036
1187
  readonly type: "string";
3037
1188
  readonly description: "Smart contract revert reason";
3038
- readonly example: "Insufficient balance";
3039
1189
  };
3040
1190
  readonly gas_used: {
3041
1191
  readonly type: "string";
3042
1192
  readonly description: "Gas consumed before failure";
3043
- readonly example: "21000";
3044
1193
  };
3045
1194
  readonly estimated_gas_needed: {
3046
1195
  readonly type: "string";
3047
1196
  readonly description: "Estimated gas needed for success";
3048
- readonly example: "50000";
3049
1197
  };
3050
1198
  };
1199
+ readonly 'x-go-type': "atumerror.BlockchainContext";
1200
+ readonly 'x-go-type-import': {
1201
+ readonly name: "atumerror";
1202
+ readonly path: "github.com/atum-labs/protocol/schemas/apis/error/v1/bindings/go";
1203
+ };
3051
1204
  };
3052
1205
  declare const $PreparePaymentRequest: {
3053
1206
  readonly type: "object";
@@ -3140,9 +1293,10 @@ declare const $PaymentTimelineResponse: {
3140
1293
  readonly example: "0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f";
3141
1294
  };
3142
1295
  readonly status: {
3143
- readonly type: "string";
3144
- readonly enum: readonly ["pending", "settling", "completed", "failed", "cancelled"];
3145
- readonly description: "High-level status:\n- `pending`: Bidding, awarded, or early in settlement\n- `settling`: Settlement in progress (on-chain steps executing)\n- `completed`: Payment successfully delivered\n- `failed`: Payment failed\n- `cancelled`: Payment was cancelled\n";
1296
+ readonly $ref: "#/components/schemas/PaymentStatus";
1297
+ };
1298
+ readonly transactions: {
1299
+ readonly $ref: "#/components/schemas/PaymentTransactions";
3146
1300
  };
3147
1301
  readonly created_at: {
3148
1302
  readonly type: "string";
@@ -3161,7 +1315,7 @@ declare const $PaymentTimelineResponse: {
3161
1315
  readonly $ref: "#/components/schemas/PaymentSummary";
3162
1316
  };
3163
1317
  readonly error: {
3164
- readonly $ref: "#/components/schemas/TimelineError";
1318
+ readonly $ref: "#/components/schemas/PaymentFailure";
3165
1319
  };
3166
1320
  readonly steps: {
3167
1321
  readonly type: "array";
@@ -3213,40 +1367,6 @@ declare const $PaymentSummary: {
3213
1367
  };
3214
1368
  };
3215
1369
  };
3216
- declare const $TimelineError: {
3217
- readonly type: "object";
3218
- readonly description: "Structured error details when a payment has failed";
3219
- readonly required: readonly ["code", "message"];
3220
- readonly properties: {
3221
- readonly code: {
3222
- readonly type: "string";
3223
- readonly description: "Machine-readable error code";
3224
- readonly example: "ESCROW_DEPOSIT_FAILED";
3225
- };
3226
- readonly message: {
3227
- readonly type: "string";
3228
- readonly description: "Human-readable error description";
3229
- };
3230
- readonly domain: {
3231
- readonly type: "string";
3232
- readonly description: "Which component reported the error";
3233
- readonly example: "SETTLER_AGENT";
3234
- };
3235
- readonly chain_id: {
3236
- readonly type: "string";
3237
- readonly description: "CAIP-2 chain where the error occurred (if on-chain)";
3238
- readonly example: "eip155:1";
3239
- };
3240
- readonly tx_hash: {
3241
- readonly type: "string";
3242
- readonly description: "Transaction hash of the failed on-chain attempt (if applicable)";
3243
- };
3244
- readonly revert_reason: {
3245
- readonly type: "string";
3246
- readonly description: "Smart-contract revert reason (if the error was an on-chain revert)";
3247
- };
3248
- };
3249
- };
3250
1370
  declare const $TimelineStep: {
3251
1371
  readonly type: "object";
3252
1372
  readonly required: readonly ["name", "label", "status"];
@@ -3281,7 +1401,7 @@ declare const $TimelineStep: {
3281
1401
  readonly description: "CAIP-2 chain this step happened on (if on-chain)";
3282
1402
  readonly example: "eip155:1";
3283
1403
  };
3284
- readonly tx_hash: {
1404
+ readonly transaction_hash: {
3285
1405
  readonly type: "string";
3286
1406
  readonly description: "Transaction hash associated with this step (if on-chain)";
3287
1407
  };
@@ -3383,7 +1503,7 @@ declare const $CreateQuoteRequest: {
3383
1503
  readonly fulfillment_deadline: {
3384
1504
  readonly type: "string";
3385
1505
  readonly format: "date-time";
3386
- readonly description: "Required. Final deadline for completing the payment. Past it the payment is cancelled and\neligible for refund. The gateway injects no default and never mutates the\noriginator-supplied body, so the value is carried through verbatim to the award call. It\nmust be supplied and must be in the future. Must be strictly later than quote_deadline.\n";
1506
+ readonly description: "Required. Final deadline for completing the payment. Past it the payment fails and\neligible for refund. The gateway injects no default and never mutates the\noriginator-supplied body, so the value is carried through verbatim to the award call. It\nmust be supplied and must be in the future. Must be strictly later than quote_deadline.\n";
3387
1507
  readonly example: "2026-04-29T12:30:00Z";
3388
1508
  };
3389
1509
  readonly settler_auth_required: {
@@ -3741,10 +1861,16 @@ declare const $DeclineSummaryEntry: {
3741
1861
  };
3742
1862
  readonly retry_classification: {
3743
1863
  readonly type: "string";
3744
- readonly description: "What would have to change for a settler giving this reason to bid, drawn from the same\nclosed set as the `retry_classification` on an error response so a caller reads one\nvocabulary.\n\nIt describes the decline only. The authoritative instruction for the payment is the\n`retry_classification` on its own error response: a payment can fail for a reason no\nsettler named, and it can succeed while some settlers declined.\n\nOptional, and a pattern-constrained string for the same reason `DeclineReason` is.\n";
1864
+ readonly description: "What would have to change for a settler giving this reason to submit a price quote,\ndrawn from the same closed set as the `retry_classification` on an error response so\na caller reads one vocabulary.\n\nIt describes the decline only. The authoritative instruction for the payment is the\n`retry_classification` on its own error response: a payment can fail for a reason no\nsettler named, and it can succeed while some settlers declined.\n\nOptional, and a pattern-constrained string for the same reason `DeclineReason` is.\n";
3745
1865
  readonly pattern: "^[A-Z][A-Z0-9_]*$";
3746
1866
  readonly example: "RETRY_AFTER_DELAY";
3747
1867
  };
1868
+ readonly docs_url: {
1869
+ readonly type: "string";
1870
+ readonly format: "uri";
1871
+ readonly description: "Link to the documentation for this reason. Absent rather than empty when no page is\npublished, so a reader never follows a link to the site root.\n";
1872
+ readonly example: "https://docs.atum.xyz/decline-reasons#insufficient-liquidity";
1873
+ };
3748
1874
  };
3749
1875
  };
3750
1876
  declare const $DeclineReason: {
@@ -4665,13 +2791,13 @@ declare function createSolanaDepositPrehash(paymentId: string, params: SolanaDep
4665
2791
  * Every current program prefixes the preimage with its domain —
4666
2792
  * `"escrow" || signature_domain_version || cluster_id[32] || program_id[32]` — and from domain
4667
2793
  * version 4 also binds `destination_hash`. So the 199-byte hash is not merely out of date, it is
4668
- * unverifiable everywhere: `escrow.rs`'s `require!(deposit_hash == message, InvalidData)` rejects
4669
- * it on every cluster.
2794
+ * unverifiable everywhere: `escrow.rs`'s `require!(deposit_hash == message, DepositHashMismatch)`
2795
+ * rejects it on every cluster.
4670
2796
  *
4671
2797
  * WHY IT THROWS INSTEAD OF BEING DELETED OR LEFT ALONE. It was exported from this package's
4672
2798
  * entry point, so removing the symbol outright is a hard break for any consumer that imports it,
4673
2799
  * while leaving it was worse: it returned a well-formed 32-byte hash that fails on-chain with
4674
- * `InvalidData` and no indication why. Throwing turns an undiagnosable on-chain rejection into an
2800
+ * `DepositHashMismatch` and no indication why. Throwing turns an undiagnosable on-chain rejection into an
4675
2801
  * error at the call site that names the replacement.
4676
2802
  *
4677
2803
  * Build deposit authorizations through the shared sender_auth adapter
@@ -4908,4 +3034,4 @@ declare class PaymentGatewayClient extends PaymentGatewayClient$1 {
4908
3034
  }): Promise<CreateQuoteRequest>;
4909
3035
  }
4910
3036
 
4911
- export { $AuthorizationResult, $AwardAccepted, $AwardRequest, $AwardResponse, $AwardedPayment, $AwardedQuote, $BidAward, $ChainDefaults, $ChainDefaultsByChain, $CreateQuoteRequest, $DataIntegrityProof, $DeclineReason, $DeclineSummaryEntry, $ErrorResponse, $FulfillmentConfirmation, $GetDefaultsResult, $GetPaymentStatusResponse, type $OpenApiTs, $OwnedAsset, $PaymentBlockchainContext, $PaymentError, $PaymentRequest, $PaymentResponse, $PaymentSummary, $PaymentTimelineResponse, $PreparePaymentRequest, $PreparePaymentResponse, $Quote, $QuoteRequestAccepted, $QuoteRequestResponse, $QuoteRequestStatusResponse, $ResolvePaymentResponse, $SenderAuth, $SenderAuthMessageScheme, $SignedMessage, $TimelineError, $TimelineStep, $VerifiableCredential, $VerifiableCredentialAuth, ApiError, type ApiRequestOptions, type ApiResult, type ApprovalParams, type AuthorizationResult, AuthorizationsService, type AuthorizePaymentData, type AuthorizePaymentResponse, type AwardAccepted, type AwardQuoteData, type AwardQuoteResponse, type AwardRequest, type AwardResponse, type AwardedPayment, type AwardedQuote, type BidAward, CancelError, CancelablePromise, type ChainDefaults, type ChainDefaultsByChain, ChainDefaultsService, type ChainDefaults$1 as ChainDefaultsWire, type ConfirmationOptions, type CreateQuoteRequest, type CreateQuoteRequestData, type CreateQuoteRequestResponse, DEFAULT_FULFILLMENT_DEADLINE_SECONDS, DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_QUOTE_DEADLINE_SECONDS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SYNC_WAIT_TIMEOUT_MS, DEFAULT_WAIT_BUDGET_MS, DEPOSIT_MESSAGE_SIZE, type DataIntegrityProof, type DeclineReason, type DeclineSummaryEntry, type EnsureApprovalResult, type ErrorResponse, type FulfillmentConfirmation, GatewayTimeoutError, type GetDefaultsData, type GetDefaultsResponse, type GetDefaultsResult, type GetPaymentStatusData, type GetPaymentStatusResponse, type GetPaymentStatusResponse2, type GetPaymentTimelineData, type GetPaymentTimelineResponse, type GetQuoteRequestStatusData, type GetQuoteRequestStatusResponse, type HealthCheckResponse, HealthService, Interceptors, InvalidAccountError, type Reason as InvalidAccountReason, MAX_VALID_SLOT, type OnCancel, OpenAPI, type OpenAPIConfig, type OwnedAsset, PAYMENT_REQUEST_VERSION, PERMIT2_CONTRACT_ADDRESS, type ParsedAssetIdentifier, type PaymentBlockchainContext, type PaymentError, PaymentGatewayClient, type PaymentGatewayClientConfig, type PaymentRequest, type PaymentResponse, type PaymentSummary, type PaymentTimelineResponse, PaymentsService, type PermitWitnessTransferFromParams, type PreparePaymentData, type PreparePaymentRequest, type PreparePaymentResponse, type PreparePaymentResponse2, type Quote, type QuoteRequestAccepted, type QuoteRequestResponse, type QuoteRequestStatusResponse, QuoteRequestsService, REPLAY_HORIZON_SECS, type RequestTimeouts, type ResolvePaymentData, type ResolvePaymentResponse, type ResolvePaymentResponse2, type SenderAuth, type SenderAuthMessageScheme, type SenderSignature, type SenderSigner, type SenderSignerOptions, type SignedMessage, type SolanaClusterUnixTimeReader, type SolanaDepositParams, type SolanaDepositPrehash, type StatusSnapshot, type SubmitPaymentData, type SubmitPaymentResponse, TOTAL_BUCKETS, type TimelineError, type TimelineStep, type TronWebLike, type TurnkeyConfig, TurnkeySenderSigner, type TvmPermitWitnessTransferFromParams, type VerifiableCredential, type VerifiableCredentialAuth, type WaitOutcome, type WaitParams, assetChainId, base58ToBytes, base58ToHex, bytesToHex, createPermitWitnessTransferFromPrehash, createSenderSigner, createSolanaDepositPrehash, createTvmPermitWitnessTransferFromPrehash, defaultGateway, type domain, encodeU64LE, ensureSourceApproval, type error_code, generateSolanaNonce, generateSolanaPaymentId, getErrorResponse, hashPermitWitnessTransferFrom, hashRequestId, hashSolanaDeposit, hashTvmPermitWitnessTransferFrom, hexToBytes, isApiError, isGatewayTimeoutError, isTerminalStatus, isUnconfirmed, maskChainId, needsSourceApproval, normalizeAddress, parseAssetIdentifier, resolveTurnkeyAddresses, signPaymentRequest, type status, type status2, type status3, type status4, type status5, type status6, type status7, type status8, type status9, waitForTerminalStatus };
3037
+ export { $AuthorizationResult, $AwardAccepted, $AwardRequest, $AwardResponse, $AwardedPayment, $AwardedQuote, $BidAward, $ChainDefaults, $ChainDefaultsByChain, $CreateQuoteRequest, $DataIntegrityProof, $DeclineReason, $DeclineSummaryEntry, $ErrorResponse, $FulfillmentConfirmation, $GetDefaultsResult, $GetPaymentStatusResponse, $OwnedAsset, $PaymentBlockchainContext, $PaymentFailure, $PaymentRequest, $PaymentResponse, $PaymentStatus, $PaymentSummary, $PaymentTimelineResponse, $PaymentTransaction, $PaymentTransactions, $PreparePaymentRequest, $PreparePaymentResponse, $Quote, $QuoteRequestAccepted, $QuoteRequestResponse, $QuoteRequestStatusResponse, $ResolvePaymentResponse, $SenderAuth, $SenderAuthMessageScheme, $SignedMessage, $TimelineStep, $VerifiableCredential, $VerifiableCredentialAuth, ApiError, type ApiRequestOptions, type ApiResult, type ApprovalParams, AuthorizationsService, AuthorizePaymentData, AuthorizePaymentResponse, AwardQuoteData, AwardQuoteResponse, CancelError, CancelablePromise, type ChainDefaults, ChainDefaultsService, type ConfirmationOptions, CreateQuoteRequest, CreateQuoteRequestData, CreateQuoteRequestResponse, DEFAULT_FULFILLMENT_DEADLINE_SECONDS, DEFAULT_PAYMENT_QUOTE_DEADLINE_SECONDS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_QUOTE_DEADLINE_SECONDS, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SYNC_WAIT_TIMEOUT_MS, DEFAULT_WAIT_BUDGET_MS, DEPOSIT_MESSAGE_SIZE, type EnsureApprovalResult, ErrorResponse, GatewayTimeoutError, GetDefaultsData, GetDefaultsResponse, GetPaymentStatusData, GetPaymentStatusResponse2, GetPaymentTimelineData, GetPaymentTimelineResponse, GetQuoteRequestStatusData, GetQuoteRequestStatusResponse, HealthCheckResponse, HealthService, Interceptors, InvalidAccountError, type Reason as InvalidAccountReason, MAX_VALID_SLOT, type OnCancel, OpenAPI, type OpenAPIConfig, PAYMENT_REQUEST_VERSION, PERMIT2_CONTRACT_ADDRESS, type ParsedAssetIdentifier, PaymentGatewayClient, type PaymentGatewayClientConfig, PaymentRequest, PaymentsService, type PermitWitnessTransferFromParams, PreparePaymentData, PreparePaymentResponse2, QuoteRequestsService, REPLAY_HORIZON_SECS, type RequestTimeouts, ResolvePaymentData, ResolvePaymentResponse2, type SenderSignature, type SenderSigner, type SenderSignerOptions, SignedMessage, type SolanaClusterUnixTimeReader, type SolanaDepositParams, type SolanaDepositPrehash, type StatusSnapshot, SubmitPaymentData, SubmitPaymentResponse, TOTAL_BUCKETS, type TronWebLike, type TurnkeyConfig, TurnkeySenderSigner, type TvmPermitWitnessTransferFromParams, type WaitOutcome, type WaitParams, assetChainId, base58ToBytes, base58ToHex, bytesToHex, createPermitWitnessTransferFromPrehash, createSenderSigner, createSolanaDepositPrehash, createTvmPermitWitnessTransferFromPrehash, defaultGateway, encodeU64LE, ensureSourceApproval, generateSolanaNonce, generateSolanaPaymentId, getErrorResponse, hashPermitWitnessTransferFrom, hashRequestId, hashSolanaDeposit, hashTvmPermitWitnessTransferFrom, hexToBytes, isApiError, isGatewayTimeoutError, isTerminalStatus, isUnconfirmed, maskChainId, needsSourceApproval, normalizeAddress, parseAssetIdentifier, resolveTurnkeyAddresses, signPaymentRequest, waitForTerminalStatus };