Skip to main content
POST
Create a quote-request batch

Query Parameters

​
wait
boolean
default:false

Return a handle immediately (false, default) or hold the connection for collected quotes (true).

Body

application/json

Request body for opening a quote-request batch. Structurally the existing PaymentRequest with sender_auth omitted (the spend authorization is deferred to the award call); see schemas/declarations/PaymentRequest/v1/schema.json.

​
version
string
required

Semver-shaped declaration version (MAJOR.MINOR), locked to major 1 for v1. Producers emit the canonical value exported by the bindings' Version constant.

Pattern: ^1\.[0-9]+$
Example:

"1.0"

​
request_id
string
required

Client-supplied idempotency key for this quote-request. The same request_id from the same originator returns the same quote_request_id. Independent of the award-call request_id.

Example:

"qr-2026-04-29-001"

​
source
object
required

Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.

​
destination
object[]
required

Array of destination assets for the settlement agent to choose from (at least one required, at most 16). The ceiling bounds the fan-out one request can buy: every consumer iterates this list.

Required array length: 1 - 16 elements
​
fulfillment_amount
string
required

The exact amount to be received at the destination (smallest unit, e.g. wei or cents).

Example:

"100000000"

​
quote_deadline
string<date-time>
required

Required. End of the collection window. After this point no new quotes are accepted. The gateway injects no default and never mutates the originator-supplied body, so the value is carried through verbatim to the award call. It must be supplied and must be in the future. Must be strictly earlier than fulfillment_deadline.

Keep this window short. A settler holds its quoted price for a limited period of its own choosing, and the gateway selects only once the window has closed, so a deadline set beyond that hold leaves no quote still awardable and the request is declined with QUOTE_WINDOW_TOO_LONG. That hold is set by each settler and is not part of this contract, so treat 60 seconds as a practical upper bound and prefer a shorter window where your integration allows.

Example:

"2026-04-29T12:00:03Z"

​
fulfillment_deadline
string<date-time>
required

Required. The time by which the payout to the recipient must be mined on the destination chain. If no payout is mined by then, your escrowed funds are refunded. The payout does not have to be final by then: completed follows once the destination chain judges it final. The gateway injects no default and never mutates the originator-supplied body, so the value is carried through verbatim to the award call. It must be supplied and must be in the future. Must be strictly later than quote_deadline.

Example:

"2026-04-29T12:30:00Z"

​
fulfillment_verifier
object
required

The verification service that confirms the payment was delivered before the escrow releases the source funds, and the account it signs with. Required on every chain: the gateway's /v1/defaults response supplies it for each chain.

​
escrow_contract_address
string
required

Escrow contract on the source chain that holds the source funds until proof of fulfillment has been verified. Required on every chain: the gateway's /v1/defaults response supplies it for each chain (escrow_contract).

Example:

"0x742D35cC6634c0532925a3b844Bc9e7595F41360"

​
max_source_amount
string

Optional cap on what the originator is willing to spend from source (smallest unit). Quotes with source_amount above this are filtered. No cap applied if omitted.

Example:

"101000000"

​
settler_auth_required
object

Policy requirements for settler authentication. Keys are policy names, values indicate if required.

​
originator_auth
object

Optional identity verification using cryptographic credentials.

DEPRECATED. Credentials are moving to a holder-signed W3C VerifiablePresentation that travels alongside a request rather than inside it. That envelope is not part of this HTTP contract, so there is nothing here to move them to yet: treat this as a legacy carrier, and do not build a new integration on it.

​
quote_selector
string

Wallet address or public key of a trusted service that auto-selects the best rate. Leave empty to use the default selector.

Example:

"0x742D35cC6634c0532925a3b844Bc9e7595F41360"

​
fulfillment_proxy
string

Optional fulfillment-proxy contract address on the destination chain. Leave empty to use the default.

Example:

"0x892BB2e4F6b14a2B5b82Ba8d33E5925D42D4431F"

​
settler_requirements
object

Optional settler filtering. 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 is rejected).

​
@context
string[]

Optional JSON-LD context URLs — present when the originator wraps the request in a W3C Data Integrity envelope so a downstream verifier can recover the signer identity.

​
proof
object

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.

​
verifiableCredential
object[]

Optional document-level W3C Verifiable Credentials (e.g. KnownToAtum about the request producer).

Response

Quote-request resolved synchronously. status is ready when quotes were collected, or collecting when the sync wait cap fired before the quote deadline.

Synchronous response to POST /v1/payments/quote-requests. Self-contained — the corridor fields are echoed at the response root so a drop-recovery client can build the award call without retaining the original request body.

The corridor echoed here describes the batch you actually receive. On an idempotent replay that is the ORIGINAL batch's corridor and window, which may differ from what you just sent in the ways a retry is allowed to differ (the deadlines, and address casing).

​
quote_request_id
string
required

Gateway-generated resource ID for the batch, used in subsequent status reads and awards.

Example:

"qr_a1b2c3d4-5678-90ef-1234-567890abcdef"

​
status
enum<string>
required

Collection-phase outcome of the create call:

  • ready — collection complete; quotes populated. If no settler bid, this is still ready with an empty quotes array (a successful "no quotes available" result — distinct from expired, which only applies to collected quotes that later lapse).
  • collecting — the sync wait cap fired before the quote deadline; poll the status endpoint for quotes. The awarded and expired lifecycle states are observed only via the status endpoint, not here.
Available options:
collecting,
ready
Example:

"ready"

​
idempotent_replay
boolean
required

Whether this response describes a batch that already existed, rather than one opened by this request. true means the request_id had been used before and you are being handed the ORIGINAL batch — no second batch was opened and no second broadcast went out to settlement agents.

Re-attempting a quote-request. Re-submit the same request and you get the same batch back. You may re-send the original bytes unchanged: quote_deadline bounds the collection window and is short, so it will usually have expired by the time you retry, and an expired deadline on a re-submission is not an error — the request is resolved onto the batch that already exists rather than used to open one. Re-signing with fresh deadlines is equally fine and returns the same batch.

The window is NOT extended either way: it belongs to the batch, and quote_deadline in this response is the batch's own. Read status to see whether collection is still running.

What you must not change under one request_id is the corridor's economics — accounts, assets, or amounts — which are rejected with 409 IDEMPOTENCY_TERMS_MISMATCH rather than resolved onto the first batch. A genuinely different corridor needs a new request_id.

Present on every response, false for a newly opened batch. A response without the field is from a gateway predating it, not a newly opened batch.

​
source
object

Represents a cryptocurrency or token in a specific wallet. This tells the system what asset you're sending/receiving and which wallet to use.

​
destination
object[]
​
fulfillment_amount
string
Example:

"100000000"

​
max_source_amount
string
Example:

"101000000"

​
fulfillment_deadline
string<date-time>
Example:

"2026-04-29T12:30:00Z"

​
quote_deadline
string<date-time>
Example:

"2026-04-29T12:00:03Z"

​
quotes
object[]

Collected quotes. Present when status is ready — an empty array if no settler bid.

​
requested_count
integer

How many agents the request was broadcast to, so silence is distinguishable from a decline without a second call. Same meaning and same absence rule as on the status endpoint: absent means unknown, never zero.

Example:

8

​
decline_summary
object[]

Why the request drew few or no quotes, carried here so that a ready response with an empty quotes array explains itself rather than requiring a follow-up read.

Same counting rules as the status endpoint: every declining agent counted exactly once under its most recent reason, empty when nobody declined, absent when the detail could not be read. Provisional while status is collecting, because agents are still responding.