Skip to main content
When a Bitcoin L1 deposit with zeroconfEnabled=true 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.
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 with zeroconfEnabled=true 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": "237500",
    "holdbackSats": "12500",
    "feeSats": "125",
    "confirmationProbability": 0.998,
    "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 held back until on-chain confirmation (sats)
  • feeSats: ZeroConf fee (sats)
  • confirmationProbability: estimated probability the transaction confirms
  • expiresAt: offer expiry time (ISO 8601)
  • offeredAt: when the offer was generated
  • resolvedAt: when the offer was accepted, declined, or expired (null while pending)
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.