Skip to main content

​
What does ZeroConf do?

When ZeroConf is enabled, Bitcoin L1 deposits can receive full credit instantly. Instead of waiting for on-chain confirmations, the engine generates a ZeroConf offer that partners accept or decline. Accepted offers credit the deposit immediately and proceed with execution.

​
How are confirmations handled?

ScenarioConfirmations required
ZeroConf offer accepted0 (instant)
ZeroConf offer declined1
ZeroConf offer expired (no response)1
ZeroConf disabled (zeroconfEnabled=false)3

​
What is the offer flow?

1

Quote with ZeroConf enabled

Create a quote with sourceChain=bitcoin and zeroconfEnabled=true (the default for bitcoin source, exact-in quotes). Set zeroconfEnabled=false explicitly to disable.
2

Deposit detected

After the Bitcoin transaction is broadcast and detected by the mempool monitor, the engine evaluates the deposit for ZeroConf eligibility.
3

Offer generated

The engine generates a ZeroConf offer and moves the order to awaiting_approval. The offer appears in order.zeroconfOffer in both status responses and webhook payloads.
4

Accept or decline

Call POST /v1/orchestration/zeroconf/accept for instant credit, or POST /v1/orchestration/zeroconf/decline to wait for 1 confirmation. If you do not respond before expiresAt, the offer expires and the engine waits for 1 confirmation.
5

Execution continues

After acceptance (instant credit) or confirmation (1 block), the order proceeds through swapping, bridging, and delivery.

​
What fields are in a ZeroConf offer?

When present, order.zeroconfOffer contains:
FieldTypeDescription
statusstringpending, accepted, declined, expired, or confirmed
quoteIdstringZeroConf quote identifier
depositSatsstringTotal BTC deposited (sats)
instantSatsstringAmount credited instantly on acceptance
holdbackSatsstringAmount held until on-chain confirmation
feeSatsstringZeroConf fee (sats)
confirmationProbabilitynumberEstimated probability the transaction confirms
expiresAtstringOffer expiry (ISO 8601)
offeredAtstringWhen the offer was generated
resolvedAtstring or nullWhen accepted, declined, or expired. null while pending
The confirmed status means the Bitcoin transaction reached 1 confirmation before the offer was resolved, bypassing the approval window entirely.

​
How do I distinguish ZeroConf from repricing?

Both ZeroConf offers and repricing requests move orders to awaiting_approval. Check which field is present:
  • order.zeroconfOffer with status=pending -> ZeroConf offer. Resolve with /zeroconf/accept or /zeroconf/decline.
  • order.reprice with status=awaiting_approval -> Repricing request. Resolve with /reprice/approve, /reprice/reject, or /reprice/refund.
Always check which field is present before resolving an awaiting_approval order. Calling the wrong endpoint returns an error.

​
How do I accept or decline an offer?

Accept (instant credit): 
curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/zeroconf/accept" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: zeroconf:accept:YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "ord_..."}'
Decline (wait for 1 confirmation): 
curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/zeroconf/decline" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: zeroconf:decline:YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "ord_...", "reason": "Optional reason"}'

​
When does ZeroConf apply?

  • ZeroConf applies when sourceChain=bitcoin and amountMode=exact_in.
  • Exact-out (amountMode=exact_out) uses confirmation-based processing and does not use ZeroConf.
  • zeroconfEnabled defaults to true when sourceChain=bitcoin. Set it to false explicitly to disable.
  • If the deployment does not have ZeroConf configured, the engine falls back to on-chain confirmations silently. No error is returned.

​
How does ZeroConf work with liquidation addresses?

Liquidation addresses support the zeroconfEnabled flag. When enabled, each Bitcoin deposit generates a ZeroConf offer requiring partner resolution via webhook + API call. When disabled, deposits wait for 3 on-chain confirmations. Some deployments require ZeroConf to be configured for liquidation address provisioning. If address creation returns a configuration error, contact your Flashnet operator. See reusable addresses for setup.

​
Next steps