Quotes and Orders
A quote is a priced intent with a 2-minute TTL. Call POST /v1/orchestration/quote to get deposit instructions and pricing. A quote does not create an order.
An order is created when you call POST /v1/orchestration/submit with the quote ID and a funded deposit proof. The order tracks execution from deposit through delivery.
Orders can also be created automatically via submissionless flows. When a deposit arrives at a quote’s deposit address, the system detects it via webhooks (Helius for Solana, Blockdaemon for Bitcoin) or polling (Spark ingress scan) and creates the order without requiring an explicit /submit call. Expired quotes are repriced at live market rates.
For submissionless flows, use GET /v1/orchestration/order?quoteId=... to poll for order creation. This endpoint returns both the quote state and the order (or null if no deposit has been detected yet). See API: Quotes and Orders for the full response shape.
GET /v1/orchestration/status?quoteId=... returns 404 for quotes that have not been submitted. Use GET /v1/orchestration/order instead when you need to poll before the order exists.
Status State Machine
Every order moves through a subset of these statuses. The allowed transitions from each status are:
| From | Allowed transitions |
|---|
processing | confirming, bridging, swapping, awaiting_approval, delivering, completed, failed, refunded |
confirming | bridging, swapping, delivering, completed, failed, refunded |
bridging | swapping, delivering, completed, failed, refunded |
swapping | awaiting_approval, bridging, delivering, completed, failed, refunded |
awaiting_approval | processing, confirming, swapping, refunding, failed, refunded |
refunding | refunded, failed |
delivering | confirming, completed, failed, refunded |
completed | (terminal) |
failed | (terminal) |
refunded | (terminal) |
Typical Happy Paths
Stablecoin to BTC:
processing -> bridging -> swapping -> delivering -> completed
BTC to Stablecoin (Spark source):
processing -> swapping -> bridging -> delivering -> completed
BTC to Stablecoin (Bitcoin L1 source, no ZeroConf):
processing -> confirming -> swapping -> bridging -> delivering -> completed
BTC to Stablecoin (Bitcoin L1 source, ZeroConf):
processing -> awaiting_approval -> processing -> swapping -> bridging -> delivering -> completed
Terminal statuses: completed, failed, refunded. No further transitions occur after reaching a terminal status.
Not every status appears in every route. A Spark-source sell may skip confirming and bridging. Track progress via webhooks or poll GET /v1/orchestration/status rather than assuming a fixed sequence.
Field Mapping
Fields shift names and semantics between the quote response and the order (status/webhook payload).
| Concept | Quote response | Order status / Webhook | Notes |
|---|
| Input amount | amountIn | amountIn | May differ from quote if actual deposit is over/under |
| Output amount | estimatedOut | amountOut | Quote: estimated. Order: actual. null until delivery completes |
| Platform fee | feeAmount | feeAmount | Recalculated if actual deposit differs from quote |
| Total fees | totalFeeAmount | — | Only on quote response when USDC fee asset |
| App fees | appFeeAmount | — | Only on quote when appFees/affiliateId requested |
| App fee platform cut | appFeePlatformCutAmount | — | Flashnet’s 20% cut of app fees. Only on quote when appFees/affiliateId requested |
| Deposit target | depositAddress | depositAddress | Same value carried from quote to order |
| Quote reference | quoteId | quoteId | Order references its source quote |
| Order reference | — | id (order) | Only exists after submit |
| Destination tx | — | destination.txHash (webhook) | Populated on delivery |
When the actual deposit differs from the quoted amount, the engine updates amountIn and feeAmount on the order before proceeding. An amount_reconciled stage is recorded. Webhook payloads and status responses reflect the updated values.
Deposit Amount Flexibility
Deposits do not need to match the quoted amountIn exactly. Any positive deposit is accepted. The engine adjusts amountIn and fees to reflect the actual deposit before execution. Slippage protection is enforced at swap execution time via the locked minimum output, not at the deposit gate.
- Underpayment: accepted. Smaller deposits produce less price impact, so the per-unit rate stays the same or improves.
- Overpayment: accepted. If the larger amount causes price impact that pushes the swap output below the locked minimum, the order enters the repricing approval flow.
Lightning deposits are excluded from flexible amounts since invoices are fixed-amount by protocol design.
Repricing (awaiting_approval)
When an order reaches awaiting_approval, inspect the order to determine the cause:
order.zeroconfOffer with status=pending: ZeroConf offer awaiting decision. See ZeroConf.order.reprice with status=awaiting_approval: repricing request.
Repricing Triggers
- Deposit is outside expected bounds for exact-out orders
- Price movement pushes the expected output below the locked minimum
- Actual deposit amount differs enough to affect execution
Resolution Options
- Approve:
POST /v1/orchestration/reprice/approve with approvedMinAmountOut. Execution resumes.
- Reject:
POST /v1/orchestration/reprice/reject. Order fails.
- Refund:
POST /v1/orchestration/reprice/refund (Bitcoin source only). BTC returned to refund address.
See Approval Flows for endpoint details.
Effective Limits
| Parameter | Value |
|---|
| Minimum | $1 equivalent |
| Maximum | $100,000 equivalent |
| BTC swap minimum | 1,000 sats |
| Platform fee | 0.05% (5 bps) |
| LP pool fee | ~0.05% (~5 bps) |
Some USDC-source routes include a sweep fee (sweepFeeAmount in the quote response). This creates an effective minimum higher than $1 because the sweep fee is deducted from the input before execution. Check the quote response for sweepFeeAmount on affected routes.
Next Steps
