@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/CHANGELOG.md +19 -0
- package/LICENSE +202 -83
- package/NOTICE +2 -0
- package/README.md +30 -13
- package/THIRD-PARTY-NOTICES.txt +4 -5
- package/dist/cli/approve-permit2.js +262 -37
- package/dist/cli/payment-status.js +78 -17
- package/dist/cli/quote-status.js +76 -15
- package/dist/cli/request-quote.js +76 -15
- package/dist/cli/send-payment.js +257 -42
- package/dist/index.d.ts +108 -1982
- package/dist/index.js +440 -149
- package/dist/sender-auth-verify-C-Q-zvAO.d.ts +2013 -0
- package/dist/signing.d.ts +223 -0
- package/dist/signing.js +7219 -0
- package/docs/idempotency.md +2 -1
- package/docs/signing.md +218 -0
- package/package.json +25 -6
- package/signing.d.ts +2 -0
- package/signing.js +11 -0
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
2911
|
-
|
|
2912
|
-
|
|
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/
|
|
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
|
|
2947
|
-
|
|
2948
|
-
|
|
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/
|
|
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 $
|
|
1127
|
+
declare const $PaymentFailure: {
|
|
2986
1128
|
readonly type: "object";
|
|
2987
|
-
readonly description: "
|
|
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
|
|
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
|
|
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: "
|
|
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: "
|
|
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
|
|
1170
|
+
readonly pattern: "^[a-z0-9]+:[a-zA-Z0-9_-]+$";
|
|
3019
1171
|
};
|
|
3020
|
-
readonly
|
|
1172
|
+
readonly transaction_hash: {
|
|
3021
1173
|
readonly type: "string";
|
|
3022
1174
|
readonly description: "Failed transaction hash";
|
|
3023
|
-
readonly
|
|
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
|
|
3033
|
-
readonly
|
|
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
|
|
3144
|
-
|
|
3145
|
-
|
|
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/
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
* `
|
|
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,
|
|
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 };
|