Skip to main content
When an eligible Bitcoin L1 deposit receives an instant-credit offer, the order enters awaiting_approval with a pending zeroconfOffer. Use the endpoints below to accept or decline. See Order Lifecycle for the full state machine and ZeroConf for how instant credit works.
Market-move repricing is handled automatically. If post-deposit execution would exceed the quote’s slippageBps, the order refunds without partner action. There is no accept/decline step. See Market moves and refunds below.

​
POST /v1/orchestration/zeroconf/accept

Accept a pending ZeroConf offer and resume execution with instant credit. Headers: 
Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>
Request: 
{
  "orderId": "ord_..."
}
Rules:
  • Order must be in awaiting_approval with a pending zeroconfOffer.
  • The offer must not be expired.
  • The API key must belong to the same partner as the order.
  • Retrying the same request with the same X-Idempotency-Key is safe. A new accept request after the offer has already resolved returns an invalid state error.
Response: 
{
  "orderId": "ord_...",
  "status": "processing"
}

​
POST /v1/orchestration/zeroconf/decline

Decline a pending ZeroConf offer. The order waits for 1 on-chain confirmation before proceeding. Headers: 
Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>
Request: 
{
  "orderId": "ord_...",
  "reason": "Optional partner reason"
}
Rules:
  • Order must be in awaiting_approval with a pending zeroconfOffer.
  • The API key must belong to the same partner as the order.
Response: 
{
  "orderId": "ord_...",
  "status": "confirming"
}
After declining, the engine waits for 1 on-chain confirmation before proceeding.

​
ZeroConf offer fields

When a Bitcoin L1 deposit receives a ZeroConf quote, the order includes a zeroconfOffer object: 
{
  "zeroconfOffer": {
    "version": 1,
    "status": "pending",
    "quoteId": "zc_...",
    "sparkAddress": "spark1...",
    "txid": "<bitcoin txid>",
    "vout": 0,
    "depositSats": "250000",
    "instantSats": "245000",
    "holdbackSats": "0",
    "feeSats": "5000",
    "expiresAt": "2026-02-04T01:35:00.000Z",
    "offeredAt": "2026-02-04T01:30:00.000Z",
    "resolvedAt": null
  }
}
Fields:
  • status: pending, accepted, declined, expired, or confirmed (confirmed means the Bitcoin tx reached 1-conf before the offer was resolved, bypassing the approval window)
  • depositSats: total BTC deposited (sats)
  • instantSats: amount credited instantly on acceptance (sats)
  • holdbackSats: amount reserved for later confirmed credit (sats). Current generated offers use "0".
  • feeSats: difference between depositSats and instantSats from Spark’s static-deposit quote
  • expiresAt: offer expiry time (ISO 8601)
  • offeredAt: when the offer was generated
  • resolvedAt: when the offer was accepted, declined, or expired (null while pending)
feeSats is not the Flashnet orchestration platform fee. Platform pricing stays in the normal quote and order fields such as feeBps, feeAmount, and totalFeeAmount. Read feeSats from each offer. Do not hard-code a fixed percentage or fixed sat amount. The order status is awaiting_approval while zeroconfOffer.status is pending. Resolve with:
  • POST /v1/orchestration/zeroconf/accept to accept and receive instant credit
  • POST /v1/orchestration/zeroconf/decline to wait for 1 on-chain confirmation before proceeding
If the offer expires without a response, it is marked expired and the engine waits for 1 on-chain confirmation before proceeding.

​
Market moves and refunds

If the pool moves against the quote between the deposit and execution, Orchestra refunds the order automatically. No partner action is required. The resulting order will have status=refunding and errorCode=slippage_exceeded before finalizing as refunded. Late deposits (arriving after quote expiry) are always accepted and repriced at the live market rate at detection time, then executed against slippageBps. If the pool has moved too far, the normal slippage_exceeded refund applies. Exact-out orders that can’t be satisfied from the received amount refund with one of:
  • exact_out_insufficient_input: the deposit was below requiredAmountIn
  • exact_out_input_above_max: the deposit exceeded maxAcceptedAmountIn
  • exact_out_target_not_met: the pool couldn’t produce targetAmountOut
In all cases the webhook event is order.refunding. Partners should treat these as normal refund flows.