Quotes and orders

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

The winning route's provider (D-26).

Decimal string, from_asset per to_asset (BSR-9) — the server's own final_in's decimal value ÷ final_out's decimal value for the winning offer, computed BEFORE either is rounded into the published Money fields below (when final_in is absent it equals the request's from_amount), in the SAME two request currencies, computed identically for every offer in this response regardless of provider or side (never a provider's own internal pricing field — Bridge's and Coinbase's own rate math disagree on this basis by side, which is exactly the bug BSR-9 closed: docs/api/CHANGELOG.md). Because rate is derived pre-rounding, rate × final_out.amount (scaled by final_out.decimals) can differ from final_in.amount in the last significant digit(s) when an asset's published Money.decimals is smaller than the server's own internal precision — do not treat that identity as exact. Informational only — NEVER compare offers by rate (rounding/precision differ by asset). Compare by final_out for a from_amount request (every offer targets a different final_out for the same pay amount). For a to_amount request, compare by final_in only among offers whose final_out equals the requested to_amount (lower final_in is better there) — an offer whose final_out differs is not comparable this way; not every provider honors an exact-output target.

What the caller receives (bestQuoteResponseSchema.finalOut).

Fee breakdown, field names from quoteFeesSchema (packages/contracts-exchange/schemas.ts). Each leg converts to a minor-unit Money object at the /v1 boundary per RESOURCE-MODEL §0.3; network_currency (the zod schema's optional currency-of-the-network-fee field) is folded into network.currency rather than published twice.

Quotes expire — re-quote rather than reusing a stale one.

Field names from quoteOfferSchema.checkoutReadiness — tells the caller how the eventual order will complete.

indicative came from a warm cache without running the live fan-out — re-quote live before acting on it once older than the safety window (bestQuoteResponseSchema.quoteStatus).

Opaque identifier of the winning offer; preserve it verbatim for selection.

Canonical method priced for the winning offer. This is requested funding intent, not proof of the eventual received settlement rail. Absent means unknown.

What the caller pays, when it differs from the request amount (bestQuoteResponseSchema.finalIn).

Field names from resolvedLimitsSchema. min/max share one currency rather than each carrying their own Money object, matching the zod source's flat shape verbatim — RESOURCE-MODEL §2.4 lists this field as resolved_limits{min,max,currency,source}, not as two nested Money objects. A1-4 — this schema is ALSO Capabilities.defaults.resolved_limits' shape (a producer outside this item's file ownership); min/max gained a pattern here rather than becoming Money objects, so that other producer's existing plain-decimal output is not broken by a shape change it was never part of fixing.

quoteOfferSchema.kycLevel — the identity tier this route requires, when known.

Field names from routeFactsSchema — comparison context for a poor-value or no-KYC-eligible alternative.

When the indicative price was actually fetched — never "now" (bestQuoteResponseSchema.indicativeAsOf).

Every fully priced offer from the same call, including sibling payment methods and providers. This additive list is the priced method surface; providers[] remains the terminal one-row-per-provider diagnostic summary for backward compatibility. An offer omitted from this list was not safely priced and must not be inferred from capabilities — including when the reason is this gateway being unable to verify that offer's own currency/asset decimal scale (fixer round 1, 2026-09-22), a money reason, not a rate one. If payment_method is absent, the provider did not return a canonical method and the client must not present that entry as a selectable named method.

Terminal outcomes from this call's existing provider offers and diagnostics (D-21, BS-G2). No additional provider requests are made to populate these rows. Reasons are public codes; raw diagnostics and provider payloads are never exposed.

The basis-point move that triggers a re-quote prompt on the client (today a server constant, 50) — D-27.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

The winning route's provider (D-26).

Decimal string, from_asset per to_asset (BSR-9) — the server's own final_in's decimal value ÷ final_out's decimal value for the winning offer, computed BEFORE either is rounded into the published Money fields below (when final_in is absent it equals the request's from_amount), in the SAME two request currencies, computed identically for every offer in this response regardless of provider or side (never a provider's own internal pricing field — Bridge's and Coinbase's own rate math disagree on this basis by side, which is exactly the bug BSR-9 closed: docs/api/CHANGELOG.md). Because rate is derived pre-rounding, rate × final_out.amount (scaled by final_out.decimals) can differ from final_in.amount in the last significant digit(s) when an asset's published Money.decimals is smaller than the server's own internal precision — do not treat that identity as exact. Informational only — NEVER compare offers by rate (rounding/precision differ by asset). Compare by final_out for a from_amount request (every offer targets a different final_out for the same pay amount). For a to_amount request, compare by final_in only among offers whose final_out equals the requested to_amount (lower final_in is better there) — an offer whose final_out differs is not comparable this way; not every provider honors an exact-output target.

What the caller receives (bestQuoteResponseSchema.finalOut).

Fee breakdown, field names from quoteFeesSchema (packages/contracts-exchange/schemas.ts). Each leg converts to a minor-unit Money object at the /v1 boundary per RESOURCE-MODEL §0.3; network_currency (the zod schema's optional currency-of-the-network-fee field) is folded into network.currency rather than published twice.

Quotes expire — re-quote rather than reusing a stale one.

Field names from quoteOfferSchema.checkoutReadiness — tells the caller how the eventual order will complete.

indicative came from a warm cache without running the live fan-out — re-quote live before acting on it once older than the safety window (bestQuoteResponseSchema.quoteStatus).

Opaque identifier of the winning offer; preserve it verbatim for selection.

Canonical method priced for the winning offer. This is requested funding intent, not proof of the eventual received settlement rail. Absent means unknown.

What the caller pays, when it differs from the request amount (bestQuoteResponseSchema.finalIn).

Field names from resolvedLimitsSchema. min/max share one currency rather than each carrying their own Money object, matching the zod source's flat shape verbatim — RESOURCE-MODEL §2.4 lists this field as resolved_limits{min,max,currency,source}, not as two nested Money objects. A1-4 — this schema is ALSO Capabilities.defaults.resolved_limits' shape (a producer outside this item's file ownership); min/max gained a pattern here rather than becoming Money objects, so that other producer's existing plain-decimal output is not broken by a shape change it was never part of fixing.

quoteOfferSchema.kycLevel — the identity tier this route requires, when known.

Field names from routeFactsSchema — comparison context for a poor-value or no-KYC-eligible alternative.

When the indicative price was actually fetched — never "now" (bestQuoteResponseSchema.indicativeAsOf).

Every fully priced offer from the same call, including sibling payment methods and providers. This additive list is the priced method surface; providers[] remains the terminal one-row-per-provider diagnostic summary for backward compatibility. An offer omitted from this list was not safely priced and must not be inferred from capabilities — including when the reason is this gateway being unable to verify that offer's own currency/asset decimal scale (fixer round 1, 2026-09-22), a money reason, not a rate one. If payment_method is absent, the provider did not return a canonical method and the client must not present that entry as a selectable named method.

Terminal outcomes from this call's existing provider offers and diagnostics (D-21, BS-G2). No additional provider requests are made to populate these rows. Reasons are public codes; raw diagnostics and provider payloads are never exposed.

The basis-point move that triggers a re-quote prompt on the client (today a server constant, 50) — D-27.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

A1-2: open — a new transactions.status value is a real, growing set (see K6/BL-36 history below); an unrecognized member is an opaque string, never a deserialization failure. transactions.status verbatim (D-22) — transactions/recovery.ts's ACTIVE_STATUSES + TERMINAL_STATUSES + UNCLASSIFIED_STATUSES vocabulary (19 values), widened from the seven the approved R15 §3 screens draw on (K6 fix: the original enum only covered the seven approved terminal/active screens and rejected every other real transactions.status value as a contract violation). BL-36 (2026-09-16) adds initiated (3 prod rows) and abandoned (1293 prod rows) — the DB status_check constraint has allowed both since 20260708201001_transactions_status_add_refunded.sql, but the vocabulary here and in recovery.ts never caught up: orders.get 500ed on either status (respondValidated rejects a status the enum does not list) and a page of orders.list containing one failed the same way whenever that row also carried a quote_id. abandoned joins TERMINAL_STATUSES; initiated is admitted here for contract purposes only and is deliberately left in recovery.ts's UNCLASSIFIED_STATUSES — prod shows every live initiated row already carries an on-chain tx_hash (one is metadata.lifecycle_stage: 'completed'), so it is a stranded post-broadcast swap the DEX reconciler never picked up, not a start-of-lifecycle "no money moved" state; see recovery.ts's comment for the full writer/reconciler trace. Never conflate with failure_kind — the failed screen's "Status code" must read failure_kind, not this field (BS-G9).

An opaque reference to the quote this order came from, when one exists. OPTIONAL — ABSENT, never a fabricated id, for an order that has no producer for it (a live write-path gap on some provider-native orders, or a swap that never went through a quote at all; see the API changelog for current prod scope). NOT resolvable via GET /v1/quotes/{id} for a historical order: this value can reference quote_attempts.rid, a different table than the one that endpoint reads, while an order created through POST /v1/orders carries a GET /v1/quotes/{id}-resolvable id instead.

Decimal string, from_asset per to_asset, the SAME basis as QuoteOffer.rate (BL-28, BS-10; fixer round 2, P1, independent review 2026-09-20 — round 1 published this on Bridge's own native, opposite basis, which collided with sibling PR BSR-9/#3357's provider-agnostic wire contract). BSR-10 gives this a live producer for a Bridge-native buy order: read rate_basis, below, to know which of two figures this is — never assume one from this field's mere presence. The planned read-time source (transactions.quote_id -> quotes.id -> quotes.offers) is a dead join in production — transactions.quote_id has referenced quote_attempts.rid, not quotes.id, since 20260210100000_fix_transactions_quote_fk.sql, and quote_attempts carries no rate/offers column. BL-48 re-examined this for orders.create's Bridge-native path (BL-47), which prices via api_quotes (a genuinely joinable row, unlike quotes) — still ruled out as a read-time source, since api_quotes is quote-cache infrastructure with its own TTL, and reading it back from orders.get/.list days after settlement, for a row a future cleanup job may have already pruned, would make this field's presence flicker on a purge schedule having nothing to do with the order itself. BSR-10 uses a WRITE-time source instead: createBridgeNativeOrder's execute-transfer call opens a server-sealed route claim and bridge-core.ts derives the persisted rate from THAT claim, inverted onto this wire basis (never from a request-body value), onto the transactions row itself at handoff (baseMetadata) — durable transaction history, never a re-derived read, and never a caller-supplied figure. Once settlement writes the observed to_amount (bridge-webhook/index.ts's transfer.payment_processed handler) AND Bridge's own transfer receipt proves the actual settled source amount, this field is RECOMPUTED as that receipt-proven source amount divided by the observed to_amount — a provider can legitimately re-price between quote and arrival for some corridors, so the settled figure is never assumed equal to the quoted one even when they agree; rate_basis flips to at_arrival in the same response. A row whose receipt never proves that source amount, or that reaches a terminal status without ever settling, publishes neither rate nor rate_basis rather than a stale or unproven figure. Still absent for every other order — a Sell/Swap order, a non-Bridge provider, or a Bridge buy this fix's write-time source never reached (a row created before this deploy) — never guessed.

Qualifies rate (above; both regimes share the same from_asset per to_asset basis). quoted: the taken offer's quote-time price, published only while the order is still active — the persisted estimate, never the final word; a terminal row without a receipt-proven settled figure publishes neither rate nor rate_basis (fixer round 3, P2, independent review 2026-09-20 — this paragraph had drifted to say the opposite of what buildOrderRateProjection actually gates on; rate's own description above, and RESOURCE-MODEL.md §2.4, already stated the gate correctly). at_arrival: the REALIZED rate, Bridge's own receipt-proven settled source amount divided by the observed amounts.receive once its transfer receipt lands — never assumed equal to the quoted figure, since a provider can legitimately re-price between quote and arrival for some corridors (Bridge's own "rate fixed on arrival" settlement semantics this field exists to name structurally, replacing a copy caveat with a field). Published alongside rate for a Bridge-native buy order (BSR-10); still absent alongside it for every other order, for the identical reason.

A provider's identity and, where the caller is pricing or reviewing capabilities, its registry-published limits — reused verbatim on Quote.provider, Order.provider and QuoteProviderResult (D-26, D-56). Capabilities.providers[] (product=buy_sell) uses CapabilityProvider below — a flat schema that duplicates these fields rather than an allOf extension of this one — so its own status vocabulary never collides with QuoteProviderResult.status, and so composing a second closed schema on top of this closed one never produces an unsatisfiable combined schema (K6b — see CapabilityProvider's own description).

The payment method originally requested for this order (transactions.payment_method, e.g. sepa/card/ach_push), verbatim — BL-48. Not restricted to a fiat leg: a Bridge buy funded from a crypto balance can carry a crypto method here too (e.g. bitcoin/ethereum) — prod carries 184 such rows. Absent when the row predates this column or the value was never set. Distinct from payment_rail: this is the REQUEST, not necessarily what settled — see that field.

Bridge's own OBSERVED settlement rail for a Bridge order (transactions.payment_rail, BL-48) — starts equal to payment_method at creation and is overwritten once bridge-webhook/index.ts's buildBridgeTransferUpdatePayload resolves one (from transfer.created onward, not only once settled), so the two can genuinely diverge. Published ONLY for provider.id: bridge orders (fix-pack, independent review): the same column carries Transak's own private rail vocabulary (order.paymentOptionId, e.g. credit_debit_card) for a Transak order, which is not Bridge's vocabulary and disagreed with payment_method on the method itself on 448 prod rows — publishing it under this Bridge-documented field for another provider would misrepresent what the customer paid with. Never inferred — published verbatim from the column, or absent when it was never set or the provider is not Bridge.

The checkout's own money lines (R15 §4: "You pay" / "You receive"). The exact sub-field set is not yet spelled out beyond this pairing in RESOURCE-MODEL — flagged for confirmation rather than invented further. Fixer round 1 (2026-09-22) — either leg is WITHHELD, never published at an unverified decimal scale, when this gateway cannot verify that leg's currency/asset — see docs/api/CHANGELOG.md's entry of the same date. This rule is identical on every order.* event's own amounts (GET /v1/events, the SSE stream, GET /v1/activity) — each leg withholds independently there too, and amounts is absent from the event only when NEITHER leg resolved, never when just one could not be verified — see docs/api/CHANGELOG.md's L5-FIX-event-money-parity fixer round 1 entry (2026-09-22).

OPTIONAL — absent when this row has never been classified (BL-38, #3086): the writer is the Paybis/Bridge failure-classification pipeline, gated on failed/cancelled Paybis rows only, so most rows never receive one. When present, read it together with money_status: money_state says whether funds were ever captured, money_status carries refund truth. A row can read status: completed while money_state reads never_authorized (D-10). Never infer a money state from status alone, and never treat its absence as never_authorized — that is exactly the fabricated-default bug this field's optionality fixes.

Drives the "Money:" line on the terminal screens (R15 §3). Every bank rail resolves to unknown; only a card rail is ever positively not_charged.

The seven normalized failure kinds (R15 BS-G9, prod-inventory §1.4). This is the field the failed screen's "Status code" must read from — never status.

Safe, human-readable copy for failure_kind — never a raw provider error string.

Why a settled leg was sent back, as the provider itself worded it (e.g. Receiver Name Mismatch, Too Many Recent Transactions) — the returned leg is a fiat pay-in on a buy, and either the crypto deposit or the fiat payout on a Bridge-native sell (L1-5). Present only on an order whose money actually arrived and was then returned — distinct from failure_reason, which is OUR safe copy for a failure_kind. Same field and same contract as payments.return_reason on a payment link, so one integration handles both. Provider vocabulary is open-ended and NOT an enum: branch on failure_kind/status, and treat this as display and support text.

What the caller must do next before this order can advance, when anything is required of them at all. Present ONLY while a hosted-provider checkout is open and reachable: the order is in an active status, a hand-off URL exists for it, that URL has not expired, and its host is one this API recognises. ABSENT — never null, never a stale URL — the moment any of those stops being true, including on a Bridge-native order (which completes in place and publishes bank_deposit_instructions or deposit_instructions instead). A caller that receives no next_action on a hosted order whose status is still active must request a new quote; there is no way to re-mint a checkout session for an order that already has one. L1-6b (contract only, no producer yet): every route stays silent on this field until L1-6c/d build the hosted-checkout branch and its resume. Published by orders.create's 201 and GET /v1/orders/{id} only — GET /v1/orders never carries it, for any row.

The offer actually executed for this order (transactions.offer_id), verbatim. Normally the offer_id the caller sent, or the quote's winning offer when none was sent; it can differ when the selected offer was not executable at order time and the server fell through to the next-ranked one — see offer_selection. Absent on an order created before this field existed or by a path that records no offer.

Why THIS offer ran, when that is not simply "the one you asked for". Published on the 201 from orders.create only — it is a record of a creation-time decision, and a later GET of the same order republishes offer_id but not this object. Absent when the executed offer is the one the request selected.

Present on a self-custody sell that needs crypto sent to a provider-issued address before payout — the shared DepositInstructions component, same shape as wallet.deposit_intents.deposit_instructions (D-24, BS-G7).

Present on a Buy order awaiting a bank-rail payment — the deposit slip (IBAN/account number, beneficiary, reference) the payer sends fiat to (BL-19). Reuses the shared BankDepositInstructions component verbatim rather than a second same-named shape, so this never drifts from the identical projection payment_sessions/payroll funding already publish. UNLIKE payout_destination below, this is deliberately the full, unmasked provider payload (D-24): the payer must have the real IBAN to actually send funds to it. Bound by the same D-24 rule as every BankDepositInstructions consumer — never logged, never placed in a URL or query string.

Present on a buy, sell or swap once its settlement destination is known (the buy crypto branch, BL-48, added below). The bank branch is masked the same way as payouts.beneficiary's output projection — never the full account number, never a public link or token (D-24); a sell order never itself becomes a payout object. The crypto branch (chain/address/tx_hash, BL-19; buy, BL-48) is exclusive with the bank branch: a self-custody payout is on-chain and has no account number to mask, so address is published verbatim (BS-G7's own deposit_instructions.address precedent). tx_hash on the buy branch is read from the SAME Bridge transfer receipt (bridge_data's receipt.destination_tx_hash) the amounts.fee producer reads (fix-pack, independent review — 66 of 70 completed Bridge buys carry one); absent before the transfer settles or on an older payload shape that predates the field, never guessed.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

A1-2: open — a new transactions.status value is a real, growing set (see K6/BL-36 history below); an unrecognized member is an opaque string, never a deserialization failure. transactions.status verbatim (D-22) — transactions/recovery.ts's ACTIVE_STATUSES + TERMINAL_STATUSES + UNCLASSIFIED_STATUSES vocabulary (19 values), widened from the seven the approved R15 §3 screens draw on (K6 fix: the original enum only covered the seven approved terminal/active screens and rejected every other real transactions.status value as a contract violation). BL-36 (2026-09-16) adds initiated (3 prod rows) and abandoned (1293 prod rows) — the DB status_check constraint has allowed both since 20260708201001_transactions_status_add_refunded.sql, but the vocabulary here and in recovery.ts never caught up: orders.get 500ed on either status (respondValidated rejects a status the enum does not list) and a page of orders.list containing one failed the same way whenever that row also carried a quote_id. abandoned joins TERMINAL_STATUSES; initiated is admitted here for contract purposes only and is deliberately left in recovery.ts's UNCLASSIFIED_STATUSES — prod shows every live initiated row already carries an on-chain tx_hash (one is metadata.lifecycle_stage: 'completed'), so it is a stranded post-broadcast swap the DEX reconciler never picked up, not a start-of-lifecycle "no money moved" state; see recovery.ts's comment for the full writer/reconciler trace. Never conflate with failure_kind — the failed screen's "Status code" must read failure_kind, not this field (BS-G9).

An opaque reference to the quote this order came from, when one exists. OPTIONAL — ABSENT, never a fabricated id, for an order that has no producer for it (a live write-path gap on some provider-native orders, or a swap that never went through a quote at all; see the API changelog for current prod scope). NOT resolvable via GET /v1/quotes/{id} for a historical order: this value can reference quote_attempts.rid, a different table than the one that endpoint reads, while an order created through POST /v1/orders carries a GET /v1/quotes/{id}-resolvable id instead.

Decimal string, from_asset per to_asset, the SAME basis as QuoteOffer.rate (BL-28, BS-10; fixer round 2, P1, independent review 2026-09-20 — round 1 published this on Bridge's own native, opposite basis, which collided with sibling PR BSR-9/#3357's provider-agnostic wire contract). BSR-10 gives this a live producer for a Bridge-native buy order: read rate_basis, below, to know which of two figures this is — never assume one from this field's mere presence. The planned read-time source (transactions.quote_id -> quotes.id -> quotes.offers) is a dead join in production — transactions.quote_id has referenced quote_attempts.rid, not quotes.id, since 20260210100000_fix_transactions_quote_fk.sql, and quote_attempts carries no rate/offers column. BL-48 re-examined this for orders.create's Bridge-native path (BL-47), which prices via api_quotes (a genuinely joinable row, unlike quotes) — still ruled out as a read-time source, since api_quotes is quote-cache infrastructure with its own TTL, and reading it back from orders.get/.list days after settlement, for a row a future cleanup job may have already pruned, would make this field's presence flicker on a purge schedule having nothing to do with the order itself. BSR-10 uses a WRITE-time source instead: createBridgeNativeOrder's execute-transfer call opens a server-sealed route claim and bridge-core.ts derives the persisted rate from THAT claim, inverted onto this wire basis (never from a request-body value), onto the transactions row itself at handoff (baseMetadata) — durable transaction history, never a re-derived read, and never a caller-supplied figure. Once settlement writes the observed to_amount (bridge-webhook/index.ts's transfer.payment_processed handler) AND Bridge's own transfer receipt proves the actual settled source amount, this field is RECOMPUTED as that receipt-proven source amount divided by the observed to_amount — a provider can legitimately re-price between quote and arrival for some corridors, so the settled figure is never assumed equal to the quoted one even when they agree; rate_basis flips to at_arrival in the same response. A row whose receipt never proves that source amount, or that reaches a terminal status without ever settling, publishes neither rate nor rate_basis rather than a stale or unproven figure. Still absent for every other order — a Sell/Swap order, a non-Bridge provider, or a Bridge buy this fix's write-time source never reached (a row created before this deploy) — never guessed.

Qualifies rate (above; both regimes share the same from_asset per to_asset basis). quoted: the taken offer's quote-time price, published only while the order is still active — the persisted estimate, never the final word; a terminal row without a receipt-proven settled figure publishes neither rate nor rate_basis (fixer round 3, P2, independent review 2026-09-20 — this paragraph had drifted to say the opposite of what buildOrderRateProjection actually gates on; rate's own description above, and RESOURCE-MODEL.md §2.4, already stated the gate correctly). at_arrival: the REALIZED rate, Bridge's own receipt-proven settled source amount divided by the observed amounts.receive once its transfer receipt lands — never assumed equal to the quoted figure, since a provider can legitimately re-price between quote and arrival for some corridors (Bridge's own "rate fixed on arrival" settlement semantics this field exists to name structurally, replacing a copy caveat with a field). Published alongside rate for a Bridge-native buy order (BSR-10); still absent alongside it for every other order, for the identical reason.

A provider's identity and, where the caller is pricing or reviewing capabilities, its registry-published limits — reused verbatim on Quote.provider, Order.provider and QuoteProviderResult (D-26, D-56). Capabilities.providers[] (product=buy_sell) uses CapabilityProvider below — a flat schema that duplicates these fields rather than an allOf extension of this one — so its own status vocabulary never collides with QuoteProviderResult.status, and so composing a second closed schema on top of this closed one never produces an unsatisfiable combined schema (K6b — see CapabilityProvider's own description).

The payment method originally requested for this order (transactions.payment_method, e.g. sepa/card/ach_push), verbatim — BL-48. Not restricted to a fiat leg: a Bridge buy funded from a crypto balance can carry a crypto method here too (e.g. bitcoin/ethereum) — prod carries 184 such rows. Absent when the row predates this column or the value was never set. Distinct from payment_rail: this is the REQUEST, not necessarily what settled — see that field.

Bridge's own OBSERVED settlement rail for a Bridge order (transactions.payment_rail, BL-48) — starts equal to payment_method at creation and is overwritten once bridge-webhook/index.ts's buildBridgeTransferUpdatePayload resolves one (from transfer.created onward, not only once settled), so the two can genuinely diverge. Published ONLY for provider.id: bridge orders (fix-pack, independent review): the same column carries Transak's own private rail vocabulary (order.paymentOptionId, e.g. credit_debit_card) for a Transak order, which is not Bridge's vocabulary and disagreed with payment_method on the method itself on 448 prod rows — publishing it under this Bridge-documented field for another provider would misrepresent what the customer paid with. Never inferred — published verbatim from the column, or absent when it was never set or the provider is not Bridge.

The checkout's own money lines (R15 §4: "You pay" / "You receive"). The exact sub-field set is not yet spelled out beyond this pairing in RESOURCE-MODEL — flagged for confirmation rather than invented further. Fixer round 1 (2026-09-22) — either leg is WITHHELD, never published at an unverified decimal scale, when this gateway cannot verify that leg's currency/asset — see docs/api/CHANGELOG.md's entry of the same date. This rule is identical on every order.* event's own amounts (GET /v1/events, the SSE stream, GET /v1/activity) — each leg withholds independently there too, and amounts is absent from the event only when NEITHER leg resolved, never when just one could not be verified — see docs/api/CHANGELOG.md's L5-FIX-event-money-parity fixer round 1 entry (2026-09-22).

OPTIONAL — absent when this row has never been classified (BL-38, #3086): the writer is the Paybis/Bridge failure-classification pipeline, gated on failed/cancelled Paybis rows only, so most rows never receive one. When present, read it together with money_status: money_state says whether funds were ever captured, money_status carries refund truth. A row can read status: completed while money_state reads never_authorized (D-10). Never infer a money state from status alone, and never treat its absence as never_authorized — that is exactly the fabricated-default bug this field's optionality fixes.

Drives the "Money:" line on the terminal screens (R15 §3). Every bank rail resolves to unknown; only a card rail is ever positively not_charged.

The seven normalized failure kinds (R15 BS-G9, prod-inventory §1.4). This is the field the failed screen's "Status code" must read from — never status.

Safe, human-readable copy for failure_kind — never a raw provider error string.

Why a settled leg was sent back, as the provider itself worded it (e.g. Receiver Name Mismatch, Too Many Recent Transactions) — the returned leg is a fiat pay-in on a buy, and either the crypto deposit or the fiat payout on a Bridge-native sell (L1-5). Present only on an order whose money actually arrived and was then returned — distinct from failure_reason, which is OUR safe copy for a failure_kind. Same field and same contract as payments.return_reason on a payment link, so one integration handles both. Provider vocabulary is open-ended and NOT an enum: branch on failure_kind/status, and treat this as display and support text.

What the caller must do next before this order can advance, when anything is required of them at all. Present ONLY while a hosted-provider checkout is open and reachable: the order is in an active status, a hand-off URL exists for it, that URL has not expired, and its host is one this API recognises. ABSENT — never null, never a stale URL — the moment any of those stops being true, including on a Bridge-native order (which completes in place and publishes bank_deposit_instructions or deposit_instructions instead). A caller that receives no next_action on a hosted order whose status is still active must request a new quote; there is no way to re-mint a checkout session for an order that already has one. L1-6b (contract only, no producer yet): every route stays silent on this field until L1-6c/d build the hosted-checkout branch and its resume. Published by orders.create's 201 and GET /v1/orders/{id} only — GET /v1/orders never carries it, for any row.

The offer actually executed for this order (transactions.offer_id), verbatim. Normally the offer_id the caller sent, or the quote's winning offer when none was sent; it can differ when the selected offer was not executable at order time and the server fell through to the next-ranked one — see offer_selection. Absent on an order created before this field existed or by a path that records no offer.

Why THIS offer ran, when that is not simply "the one you asked for". Published on the 201 from orders.create only — it is a record of a creation-time decision, and a later GET of the same order republishes offer_id but not this object. Absent when the executed offer is the one the request selected.

Present on a self-custody sell that needs crypto sent to a provider-issued address before payout — the shared DepositInstructions component, same shape as wallet.deposit_intents.deposit_instructions (D-24, BS-G7).

Present on a Buy order awaiting a bank-rail payment — the deposit slip (IBAN/account number, beneficiary, reference) the payer sends fiat to (BL-19). Reuses the shared BankDepositInstructions component verbatim rather than a second same-named shape, so this never drifts from the identical projection payment_sessions/payroll funding already publish. UNLIKE payout_destination below, this is deliberately the full, unmasked provider payload (D-24): the payer must have the real IBAN to actually send funds to it. Bound by the same D-24 rule as every BankDepositInstructions consumer — never logged, never placed in a URL or query string.

Present on a buy, sell or swap once its settlement destination is known (the buy crypto branch, BL-48, added below). The bank branch is masked the same way as payouts.beneficiary's output projection — never the full account number, never a public link or token (D-24); a sell order never itself becomes a payout object. The crypto branch (chain/address/tx_hash, BL-19; buy, BL-48) is exclusive with the bank branch: a self-custody payout is on-chain and has no account number to mask, so address is published verbatim (BS-G7's own deposit_instructions.address precedent). tx_hash on the buy branch is read from the SAME Bridge transfer receipt (bridge_data's receipt.destination_tx_hash) the amounts.fee producer reads (fix-pack, independent review — 66 of 70 completed Bridge buys carry one); absent before the transfer settles or on an older payload shape that predates the field, never guessed.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

A1-2: open — a new transactions.status value is a real, growing set (see K6/BL-36 history below); an unrecognized member is an opaque string, never a deserialization failure. transactions.status verbatim (D-22) — transactions/recovery.ts's ACTIVE_STATUSES + TERMINAL_STATUSES + UNCLASSIFIED_STATUSES vocabulary (19 values), widened from the seven the approved R15 §3 screens draw on (K6 fix: the original enum only covered the seven approved terminal/active screens and rejected every other real transactions.status value as a contract violation). BL-36 (2026-09-16) adds initiated (3 prod rows) and abandoned (1293 prod rows) — the DB status_check constraint has allowed both since 20260708201001_transactions_status_add_refunded.sql, but the vocabulary here and in recovery.ts never caught up: orders.get 500ed on either status (respondValidated rejects a status the enum does not list) and a page of orders.list containing one failed the same way whenever that row also carried a quote_id. abandoned joins TERMINAL_STATUSES; initiated is admitted here for contract purposes only and is deliberately left in recovery.ts's UNCLASSIFIED_STATUSES — prod shows every live initiated row already carries an on-chain tx_hash (one is metadata.lifecycle_stage: 'completed'), so it is a stranded post-broadcast swap the DEX reconciler never picked up, not a start-of-lifecycle "no money moved" state; see recovery.ts's comment for the full writer/reconciler trace. Never conflate with failure_kind — the failed screen's "Status code" must read failure_kind, not this field (BS-G9).

An opaque reference to the quote this order came from, when one exists. OPTIONAL — ABSENT, never a fabricated id, for an order that has no producer for it (a live write-path gap on some provider-native orders, or a swap that never went through a quote at all; see the API changelog for current prod scope). NOT resolvable via GET /v1/quotes/{id} for a historical order: this value can reference quote_attempts.rid, a different table than the one that endpoint reads, while an order created through POST /v1/orders carries a GET /v1/quotes/{id}-resolvable id instead.

Decimal string, from_asset per to_asset, the SAME basis as QuoteOffer.rate (BL-28, BS-10; fixer round 2, P1, independent review 2026-09-20 — round 1 published this on Bridge's own native, opposite basis, which collided with sibling PR BSR-9/#3357's provider-agnostic wire contract). BSR-10 gives this a live producer for a Bridge-native buy order: read rate_basis, below, to know which of two figures this is — never assume one from this field's mere presence. The planned read-time source (transactions.quote_id -> quotes.id -> quotes.offers) is a dead join in production — transactions.quote_id has referenced quote_attempts.rid, not quotes.id, since 20260210100000_fix_transactions_quote_fk.sql, and quote_attempts carries no rate/offers column. BL-48 re-examined this for orders.create's Bridge-native path (BL-47), which prices via api_quotes (a genuinely joinable row, unlike quotes) — still ruled out as a read-time source, since api_quotes is quote-cache infrastructure with its own TTL, and reading it back from orders.get/.list days after settlement, for a row a future cleanup job may have already pruned, would make this field's presence flicker on a purge schedule having nothing to do with the order itself. BSR-10 uses a WRITE-time source instead: createBridgeNativeOrder's execute-transfer call opens a server-sealed route claim and bridge-core.ts derives the persisted rate from THAT claim, inverted onto this wire basis (never from a request-body value), onto the transactions row itself at handoff (baseMetadata) — durable transaction history, never a re-derived read, and never a caller-supplied figure. Once settlement writes the observed to_amount (bridge-webhook/index.ts's transfer.payment_processed handler) AND Bridge's own transfer receipt proves the actual settled source amount, this field is RECOMPUTED as that receipt-proven source amount divided by the observed to_amount — a provider can legitimately re-price between quote and arrival for some corridors, so the settled figure is never assumed equal to the quoted one even when they agree; rate_basis flips to at_arrival in the same response. A row whose receipt never proves that source amount, or that reaches a terminal status without ever settling, publishes neither rate nor rate_basis rather than a stale or unproven figure. Still absent for every other order — a Sell/Swap order, a non-Bridge provider, or a Bridge buy this fix's write-time source never reached (a row created before this deploy) — never guessed.

Qualifies rate (above; both regimes share the same from_asset per to_asset basis). quoted: the taken offer's quote-time price, published only while the order is still active — the persisted estimate, never the final word; a terminal row without a receipt-proven settled figure publishes neither rate nor rate_basis (fixer round 3, P2, independent review 2026-09-20 — this paragraph had drifted to say the opposite of what buildOrderRateProjection actually gates on; rate's own description above, and RESOURCE-MODEL.md §2.4, already stated the gate correctly). at_arrival: the REALIZED rate, Bridge's own receipt-proven settled source amount divided by the observed amounts.receive once its transfer receipt lands — never assumed equal to the quoted figure, since a provider can legitimately re-price between quote and arrival for some corridors (Bridge's own "rate fixed on arrival" settlement semantics this field exists to name structurally, replacing a copy caveat with a field). Published alongside rate for a Bridge-native buy order (BSR-10); still absent alongside it for every other order, for the identical reason.

A provider's identity and, where the caller is pricing or reviewing capabilities, its registry-published limits — reused verbatim on Quote.provider, Order.provider and QuoteProviderResult (D-26, D-56). Capabilities.providers[] (product=buy_sell) uses CapabilityProvider below — a flat schema that duplicates these fields rather than an allOf extension of this one — so its own status vocabulary never collides with QuoteProviderResult.status, and so composing a second closed schema on top of this closed one never produces an unsatisfiable combined schema (K6b — see CapabilityProvider's own description).

The payment method originally requested for this order (transactions.payment_method, e.g. sepa/card/ach_push), verbatim — BL-48. Not restricted to a fiat leg: a Bridge buy funded from a crypto balance can carry a crypto method here too (e.g. bitcoin/ethereum) — prod carries 184 such rows. Absent when the row predates this column or the value was never set. Distinct from payment_rail: this is the REQUEST, not necessarily what settled — see that field.

Bridge's own OBSERVED settlement rail for a Bridge order (transactions.payment_rail, BL-48) — starts equal to payment_method at creation and is overwritten once bridge-webhook/index.ts's buildBridgeTransferUpdatePayload resolves one (from transfer.created onward, not only once settled), so the two can genuinely diverge. Published ONLY for provider.id: bridge orders (fix-pack, independent review): the same column carries Transak's own private rail vocabulary (order.paymentOptionId, e.g. credit_debit_card) for a Transak order, which is not Bridge's vocabulary and disagreed with payment_method on the method itself on 448 prod rows — publishing it under this Bridge-documented field for another provider would misrepresent what the customer paid with. Never inferred — published verbatim from the column, or absent when it was never set or the provider is not Bridge.

The checkout's own money lines (R15 §4: "You pay" / "You receive"). The exact sub-field set is not yet spelled out beyond this pairing in RESOURCE-MODEL — flagged for confirmation rather than invented further. Fixer round 1 (2026-09-22) — either leg is WITHHELD, never published at an unverified decimal scale, when this gateway cannot verify that leg's currency/asset — see docs/api/CHANGELOG.md's entry of the same date. This rule is identical on every order.* event's own amounts (GET /v1/events, the SSE stream, GET /v1/activity) — each leg withholds independently there too, and amounts is absent from the event only when NEITHER leg resolved, never when just one could not be verified — see docs/api/CHANGELOG.md's L5-FIX-event-money-parity fixer round 1 entry (2026-09-22).

OPTIONAL — absent when this row has never been classified (BL-38, #3086): the writer is the Paybis/Bridge failure-classification pipeline, gated on failed/cancelled Paybis rows only, so most rows never receive one. When present, read it together with money_status: money_state says whether funds were ever captured, money_status carries refund truth. A row can read status: completed while money_state reads never_authorized (D-10). Never infer a money state from status alone, and never treat its absence as never_authorized — that is exactly the fabricated-default bug this field's optionality fixes.

Drives the "Money:" line on the terminal screens (R15 §3). Every bank rail resolves to unknown; only a card rail is ever positively not_charged.

The seven normalized failure kinds (R15 BS-G9, prod-inventory §1.4). This is the field the failed screen's "Status code" must read from — never status.

Safe, human-readable copy for failure_kind — never a raw provider error string.

Why a settled leg was sent back, as the provider itself worded it (e.g. Receiver Name Mismatch, Too Many Recent Transactions) — the returned leg is a fiat pay-in on a buy, and either the crypto deposit or the fiat payout on a Bridge-native sell (L1-5). Present only on an order whose money actually arrived and was then returned — distinct from failure_reason, which is OUR safe copy for a failure_kind. Same field and same contract as payments.return_reason on a payment link, so one integration handles both. Provider vocabulary is open-ended and NOT an enum: branch on failure_kind/status, and treat this as display and support text.

What the caller must do next before this order can advance, when anything is required of them at all. Present ONLY while a hosted-provider checkout is open and reachable: the order is in an active status, a hand-off URL exists for it, that URL has not expired, and its host is one this API recognises. ABSENT — never null, never a stale URL — the moment any of those stops being true, including on a Bridge-native order (which completes in place and publishes bank_deposit_instructions or deposit_instructions instead). A caller that receives no next_action on a hosted order whose status is still active must request a new quote; there is no way to re-mint a checkout session for an order that already has one. L1-6b (contract only, no producer yet): every route stays silent on this field until L1-6c/d build the hosted-checkout branch and its resume. Published by orders.create's 201 and GET /v1/orders/{id} only — GET /v1/orders never carries it, for any row.

The offer actually executed for this order (transactions.offer_id), verbatim. Normally the offer_id the caller sent, or the quote's winning offer when none was sent; it can differ when the selected offer was not executable at order time and the server fell through to the next-ranked one — see offer_selection. Absent on an order created before this field existed or by a path that records no offer.

Why THIS offer ran, when that is not simply "the one you asked for". Published on the 201 from orders.create only — it is a record of a creation-time decision, and a later GET of the same order republishes offer_id but not this object. Absent when the executed offer is the one the request selected.

Present on a self-custody sell that needs crypto sent to a provider-issued address before payout — the shared DepositInstructions component, same shape as wallet.deposit_intents.deposit_instructions (D-24, BS-G7).

Present on a Buy order awaiting a bank-rail payment — the deposit slip (IBAN/account number, beneficiary, reference) the payer sends fiat to (BL-19). Reuses the shared BankDepositInstructions component verbatim rather than a second same-named shape, so this never drifts from the identical projection payment_sessions/payroll funding already publish. UNLIKE payout_destination below, this is deliberately the full, unmasked provider payload (D-24): the payer must have the real IBAN to actually send funds to it. Bound by the same D-24 rule as every BankDepositInstructions consumer — never logged, never placed in a URL or query string.

Present on a buy, sell or swap once its settlement destination is known (the buy crypto branch, BL-48, added below). The bank branch is masked the same way as payouts.beneficiary's output projection — never the full account number, never a public link or token (D-24); a sell order never itself becomes a payout object. The crypto branch (chain/address/tx_hash, BL-19; buy, BL-48) is exclusive with the bank branch: a self-custody payout is on-chain and has no account number to mask, so address is published verbatim (BS-G7's own deposit_instructions.address precedent). tx_hash on the buy branch is read from the SAME Bridge transfer receipt (bridge_data's receipt.destination_tx_hash) the amounts.fee producer reads (fix-pack, independent review — 66 of 70 completed Bridge buys carry one); absent before the transfer settles or on an older payload shape that predates the field, never guessed.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.