Skip to main content
When an order reaches awaiting_approval, use these endpoints to resolve it. See Order Lifecycle for the state machine and ZeroConf for instant Bitcoin credit concepts.

​
POST /v1/orchestration/reprice/approve

Approve a pending repricing request and resume execution. Headers: 
Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>
Request: 
{
  "orderId": "ord_...",
  "approvedMinAmountOut": "99500000"
}
Rules:
  • Order must be in awaiting_approval.
  • approvedMinAmountOut must be less than or equal to the previous locked minimum in order.reprice.previousLockedMinAmountOut.
Response: 
{
  "orderId": "ord_...",
  "status": "swapping"
}

​
POST /v1/orchestration/reprice/reject

Reject repricing and fail the order. Headers: 
Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>
Request: 
{
  "orderId": "ord_...",
  "reason": "Optional partner reason"
}
Response: 
{
  "orderId": "ord_...",
  "status": "failed"
}

​
POST /v1/orchestration/reprice/refund

Reject repricing and request an on-chain BTC refund. Headers: 
Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>
Request: 
{
  "orderId": "ord_...",
  "reason": "Optional partner reason",
  "refundAddress": "bc1qoptionaloverride..."
}
Rules:
  • Order must be in awaiting_approval.
  • Refund is currently supported only for Bitcoin source orders.
  • refundAddress can come from the quote or this request; one must be present.
Response: 
{
  "orderId": "ord_...",
  "status": "refunding"
}
The worker executes the refund asynchronously and finalizes the order as refunded or failed.

​
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.