Approval Flows

When a Bitcoin L1 deposit receives an instant-credit offer, the order enters awaiting_approval with zeroconfOffer.status: "pending". Use the endpoints below to accept or decline. Do not act on awaiting_approval alone. 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 start the instant-credit claim. It does not complete destination delivery.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/zeroconf/accept" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: zeroconf-accept:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "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. An expired pending offer returns 409 expired.

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.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/zeroconf/decline" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: zeroconf-decline:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_..."
  }'

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

This is the canonical zeroconfOffer schema. Status responses and webhook payloads use the same projection, so the object is identical wherever it appears. When a Bitcoin L1 deposit receives a ZeroConf quote, the order includes a zeroconfOffer object:

{
  "zeroconfOffer": {
    "version": 1,
    "status": "pending",
    "quoteId": "<spark static-deposit quote id>",
    "sparkAddress": "spark1...",
    "txid": "<bitcoin txid>",
    "vout": 0,
    "depositSats": "250000",
    "instantSats": "245000",
    "feeSats": "5000",
    "expiresAt": "2026-02-04T01:31:00.000Z",
    "offeredAt": "2026-02-04T01:30:00.000Z",
    "resolvedAt": null,
    "sparkTxid": null
  }
}

Always present:

Field	Type	Notes
`version`	`number`	Always `1`
`status`	`string`	`pending`, `accepted`, `declined`, `expired`, or `confirmed`. `confirmed` means the Bitcoin tx reached 1-conf before the offer was resolved, bypassing the approval window.
`quoteId`	`string`	Spark static-deposit quote id
`sparkAddress`	`string`	Spark address for the instant credit
`txid`	`string`	Bitcoin transaction id of the deposit
`vout`	`number`	Deposit output index
`depositSats`	`string`	Total BTC deposited (sats)
`instantSats`	`string`	Full net amount credited on acceptance (sats)
`feeSats`	`string`	Difference between `depositSats` and `instantSats` from Spark’s static-deposit quote
`expiresAt`	`string`	Offer expiry (ISO 8601)
`offeredAt`	`string`	When the offer was generated (ISO 8601)
`resolvedAt`	`string \| null`	When the offer was accepted, declined, or expired. `null` while pending.
`sparkTxid`	`string \| null`	Spark transfer id once the instant credit has executed. Informational only: use the order status and destination fields to determine final delivery.

Present only when set (omitted otherwise): quoteNetwork, quoteSignature, planId, planAmountSats, planConfirmations, planStatus, transferSparkId, and claimId. These carry Spark static-deposit quote and fulfillment-plan details. Treat them as informational; the fields above are the ones to act on. feeSats is not the Flashnet orchestration platform fee. Platform pricing stays in the normal quote and order fields such as feeBps, feeAmount, and totalFeeAmount. depositSats = instantSats + feeSats; accepting the offer credits the one net instantSats amount. Read feeSats from each offer. Do not hard-code a fixed percentage or fixed sat amount. Act only when both the order status is awaiting_approval and 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. zeroconfOffer can instead be { "status": "denied", "deniedAt": "..." }. That object is not an offer and has no accept or decline action; the order follows the confirmation path.

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.

Overview

Concepts

Guides

Reference

Security

POST /v1/orchestration/zeroconf/accept

POST /v1/orchestration/zeroconf/decline

ZeroConf offer fields

Market moves and refunds

​POST /v1/orchestration/zeroconf/accept

​POST /v1/orchestration/zeroconf/decline

​ZeroConf offer fields

​Market moves and refunds

POST /v1/orchestration/zeroconf/accept

POST /v1/orchestration/zeroconf/decline

ZeroConf offer fields

Market moves and refunds