> ## Documentation Index > Fetch the complete documentation index at: https://docs.atum.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get quote-request status > Read a quote-request batch and the quotes collected for it so far. Reads a batch you opened with [create a quote-request](/api-reference/payment-gateway/create-quote-request), and the quotes collected for it so far. If you lost the create response, you don't need this id to recover: re-send the same request and its `request_id` returns the original batch. See [Idempotency](/payment-protocols/idempotency). ## OpenAPI ````yaml GET /v1/payments/quote-requests/{quoteRequestId} openapi: 3.0.3 info: title: Atum Payment Gateway API description: > The Atum Payment Gateway API enables secure, cross-chain payments with built-in escrow protection and settlement verification. This API facilitates decentralized payment routing across multiple blockchain networks while ensuring transaction atomicity and settlement guarantees. ## Supported Blockchains - Ethereum and EVM-compatible chains (Arbitrum, Optimism, Base, etc.) - Solana - Tron ## Authentication No API key, token, or authorization header is required on any operation. A payment carries its own authorization: the `sender_auth` signed messages prove control of the funding account, and are verified on every submission. version: 1.0.0 servers: - url: https://payment-gw.production-mainnet.atum.xyz description: Mainnet - url: https://payment-gw.production-testnet.atum.xyz description: Testnet security: [] tags: - name: Payments description: >- Submit a payment and follow it to settlement, by payment id, by your own request id, or step by step. - name: Authorizations description: Counterparty authorization requested while a payment is being accepted. - name: Quote Requests description: >- The two-phase quote flow - open a quote-request batch, poll it, then award one quote. - name: Chain Defaults description: >- The per-chain corridor addresses a client needs before it can build and sign a payment. - name: Health description: Liveness probe for the gateway. paths: /v1/payments/quote-requests/{quoteRequestId}: get: tags: - Quote Requests summary: Get quote-request batch status description: > Returns the current state of a quote-request batch: a derived status, the collected quotes (each with its settler-signed `award_deadline`), and the awarded (quote_id, payment_id) pairs once a quote has been awarded. Used for async polling, connection-drop recovery, and re-reading quotes before awarding. The `status` here describes the quote-request batch lifecycle (`collecting`/`ready`/`awarded`/`expired`) and is disjoint from the payment-status enum returned by the award and payment-status endpoints. operationId: getQuoteRequestStatus parameters: - name: quoteRequestId in: path required: true description: The ID of the quote-request batch to query schema: type: string responses: '200': description: Quote-request status retrieved successfully content: application/json: schema: $ref: '#/components/schemas/QuoteRequestStatusResponse' '404': description: Quote-request not found, or not owned by the caller. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: QuoteRequestStatusResponse: type: object description: > Response to GET /v1/payments/quote-requests/{quoteRequestId}. The `status` enum describes the quote-request batch lifecycle and is disjoint from the payment-status enum. required: - quote_request_id - status properties: quote_request_id: type: string example: qr_a1b2c3d4-5678-90ef-1234-567890abcdef status: type: string enum: - collecting - ready - awarded - expired description: > Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint from the payment-status enum returned by the award and payment-status endpoints. - `collecting` — collection window still open; `quotes` lists those collected so far (a quote is awardable from arrival, by its own `award_deadline`; more may arrive until `collection_close`). - `ready` — collection complete; none awarded yet; either at least one quote is still within its `award_deadline`, or no settler bid (empty `quotes` array — the successful "no quotes available" result). - `awarded` — a quote produced a payment row; no further awards accepted (MVP). - `expired` — collection closed, nothing awarded, and every collected quote is now past its `award_deadline` ("quotes lapsed"). An empty batch is `ready`, not `expired` — the two are deliberately distinct ("no quotes available" vs "quotes lapsed"). example: awarded quotes: type: array description: >- Collected quotes with award linkage — those collected so far while `collecting`, the full set once the window closes. items: $ref: '#/components/schemas/AwardedQuote' payments: type: array description: >- Flat list of awarded (quote_id, payment_id) pairs. At most one entry under MVP single-award. items: $ref: '#/components/schemas/AwardedPayment' requested_count: type: integer description: > How many agents the request was broadcast to. The only auction count that is not derivable from the rest of this response: - quoted = `quotes` length - declined = sum of `decline_summary[].count` - participated = quoted + declined - silent = `requested_count` - participated Silence and a decline are different signals, which is why the denominator is surfaced rather than left implicit. ABSENT when the number is unknown, which happens when the broadcast count was never recorded or when the auction detail could not be read. Absence means unknown, never zero, so `silent` is derivable only when this field is present. example: 8 decline_summary: type: array description: > Why the request drew few or no quotes, so a caller can tell "nobody can fund this right now" from "my request was malformed". EXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most recent reason, so the counts sum to the number of agents that declined. An agent that declined more than once with different reasons is counted once, not once per reason. Empty means nobody declined. ABSENT means the auction detail could not be read, so the breakdown is unknown. While `status` is `collecting` it is provisional, because agents are still responding. The free-form decline detail is never relayed, because that detail carries an agent's balances and would let a caller map inventory by polling cheap quote-requests across corridors. items: $ref: '#/components/schemas/DeclineSummaryEntry' ErrorResponse: type: object description: >- 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. 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. required: - code - message properties: code: type: string description: Public, machine-readable error category in SCREAMING_SNAKE_CASE. pattern: ^[A-Z][A-Z0-9_]*$ example: INVALID_SOURCE_ASSET message: type: string description: Curated, safe, human-readable message. maxLength: 500 example: The source asset identifier is not a valid CAIP-19 asset. request_id: type: string description: >- Correlation id to quote to support to locate the internal error record. example: req_123456789 payment_id: type: string description: >- The payment this error was raised against. Absent when the error is not about a specific payment. example: '0xc7108e200d11580e7e75185991084b42a535af588ba8267cd0d1e7df089e5c9c' docs_url: type: string format: uri description: Link to the documentation page for this public code. domain: type: string description: Originating service domain. example: PAYMENT_GATEWAY retry_classification: type: string description: >- What the caller should do next. Absent means the condition has not been classified, which is not the same as safe to retry. 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. example: RECONCILE_THEN_DECIDE request_id_reusable: type: boolean description: >- Whether the caller may re-send this same request_id. True means no payment was created for it, so the id is still free. False means a payment exists for it, so the id is spent and re-sending only replays this outcome. Absent means undetermined, which a caller should read as false. Separate from retry_classification, which answers what the caller must change rather than whether the id survived. example: false AwardedQuote: type: object description: >- A collected quote in the status response, annotated with its award linkage. required: - quote_id - fulfillment_quote properties: quote_id: type: string example: 0x9a3b...e8d4 fulfillment_quote: type: object description: > The settler-signed FulfillmentQuote (structurally the canonical FulfillmentQuote/v1 declaration at https://schemas.atum.xyz/declarations/FulfillmentQuote/v1), returned verbatim as an opaque signed document. A client recomputes quote_hash over the returned bytes and verifies the settler signature, then re-embeds them into bid_award.fulfillment_quote_json at award. quote_hash is canonicalization-based (URDNA2015), so it is stable across JSON key-order/whitespace normalization. The returned bytes are hash-equivalent to, but not necessarily byte-identical with, what the settler emitted (quotes are stored as JSONB, which normalizes on write). The gateway still never re-serializes the quote through a typed struct (that renormalizes timestamp values and WOULD change quote_hash), so the Go binding exposes it as a raw JSON passthrough. awarded_payment_id: type: string nullable: true description: > payment_id if this quote was awarded; null otherwise. Under MVP single-award, at most one quote per batch carries a non-null value. example: '0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f' AwardedPayment: type: object description: A (quote_id, payment_id) pair for an awarded quote in a batch. required: - quote_id - payment_id properties: quote_id: type: string example: 0x9a3b...e8d4 payment_id: type: string example: '0x761989729fefb4b0cb8b3e6f787301a3878c91e8fba35ed362a079292879f34f' DeclineSummaryEntry: type: object required: - reason - count properties: reason: $ref: '#/components/schemas/DeclineReason' count: type: integer description: > Agents whose most recent decline reason was this one. Counts agents, never rows, and an agent appears under one reason only. example: 4 retry_classification: type: string description: > What would have to change for a settler giving this reason to submit a price quote, drawn from the same closed set as the `retry_classification` on an error response so a caller reads one vocabulary. It describes the decline only. The authoritative instruction for the payment is the `retry_classification` on its own error response: a payment can fail for a reason no settler named, and it can succeed while some settlers declined. Optional, and a pattern-constrained string for the same reason `DeclineReason` is. pattern: ^[A-Z][A-Z0-9_]*$ example: RETRY_AFTER_DELAY docs_url: type: string format: uri description: > Link to the documentation for this reason. Absent rather than empty when no page is published, so a reader never follows a link to the site root. example: https://docs.atum.xyz/decline-reasons#insufficient-liquidity DeclineReason: type: string description: > A settler's reason for not bidding, projected from its internal reason code through the shared decline catalog (`apis/decline/v1/catalog.json`), which is the single source of truth for the reason set. Several internal codes may map to one public reason. Deliberately a pattern-constrained string rather than a closed enum. The set grows whenever a settler gains a cause worth naming, and a consumer whose generated client closes the set rejects the whole response on a value it has not seen. Treat an unrecognised value as `OTHER`. `OTHER` covers a reason whose detail is settler-authored free text, and any reason this gateway does not recognise. Both are counted so the summary stays exhaustive, without relaying text we neither author nor validate. pattern: ^[A-Z][A-Z0-9_]*$ example: INSUFFICIENT_LIQUIDITY ````