Quotes and Orders
A quote is a priced intent with a 2-minute TTL. CallPOST /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
Lightning to direct BTC (Spark or Bitcoin L1):
processing -> confirming -> 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 quotedamountIn 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.
Repricing (awaiting_approval)
When an order reachesawaiting_approval, inspect the order to determine the cause:
order.zeroconfOfferwithstatus=pending: ZeroConf offer awaiting decision. See ZeroConf.order.repricewithstatus=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/approvewithapprovedMinAmountOut. Execution resumes. - Reject:
POST /v1/orchestration/reprice/reject. Order fails. - Refund:
POST /v1/orchestration/reprice/refund(Bitcoin source only). BTC returned to refund address.
Effective Limits
| Parameter | Value |
|---|---|
| Minimum | $1 equivalent |
| Maximum | $100,000 equivalent |
| BTC swap minimum | 1,000 sats |
| Platform fee | Custom pricing based on route and volume |
For
lightning:BTC -> bitcoin:BTC, the final on-chain withdrawal also pays the network withdrawal fee quoted at delivery time. That fee is separate from the platform fee shown on the quote or order.