Fiat onramp

The Lightning onramp creates an invoice to fund delivery of BTC, USDB, or a stablecoin to a supported destination. POST /v1/orchestration/onramp returns the order, invoice, fees, and expiry. Pay the BOLT11 invoice in depositAddress with Cash App or Strike. paymentLinks.cashApp opens Cash App with the invoice; the payer app controls its USD display.

Prerequisites

An Orchestra account. Create one in the dashboard. Flashnet reviews new accounts before enabling API access.
A server key (fn_...) from API keys in the dashboard. Keep it on your backend. For browsers and apps, use a scoped client key (fnp_...); see Authentication.

Flow

Preview the price (optional)

GET /v1/orchestration/estimate with sourceChain=lightning&sourceAsset=BTC returns an indicative estimatedOut without creating anything.

Create the onramp order

Request $50.00 over Lightning into USDB on Spark:

curl -X POST https://orchestration.flashnet.xyz/v1/orchestration/onramp \
  -H "Authorization: Bearer SERVER_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "spark",
    "destinationAsset": "USDB",
    "recipientAddress": "RECIPIENT_ADDRESS",
    "amountFiatUsd": "50.00"
  }'

const res = await fetch("https://orchestration.flashnet.xyz/v1/orchestration/onramp", {
  method: "POST",
  headers: {
    Authorization: "Bearer SERVER_KEY",
    "X-Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    destinationChain: "spark",
    destinationAsset: "USDB",
    recipientAddress: "RECIPIENT_ADDRESS",
    amountFiatUsd: "50.00",
  }),
});
const onramp = await res.json();

Replace SERVER_KEY with your fn_... key. Use a new X-Idempotency-Key for each operation and reuse it when retrying that same request. Amounts are integer strings in the asset’s smallest unit: "100000" is 0.001 BTC; "50000000" is 50 USDC on Base. Read each asset’s decimals from /routes.

Example response for exact-in pricing (values vary by quote):

{
  "orderId": "ord_01J9Q0X3K8M2N7P4R6S8T0V2W4",
  "quoteId": "q_01J9Q0X3K8M2N7P4R6S8T0V2W3",
  "depositAddress": "lnbc...",
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc...",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/8fQ2kL"
  },
  "amountIn": "44210",
  "estimatedOut": "49750000",
  "feeAmount": "250000",
  "feeAsset": "USDB",
  "expiresAt": "2026-09-11T20:59:00.000Z"
}

Optional shortUrl serves a mobile handoff page or desktop QR page for this order. Use pay links for repeat checkout.

Hand off to the user's wallet

For Cash App, navigate to paymentLinks.cashApp on mobile or encode that URL as a desktop QR code. Never fetch() it. Use the invoice for a compatible wallet’s Lightning payment flow.

Track the order

Subscribe to SSE or register a webhook; see Status and Frontend rules below.

Amount modes

Send exactly one of amount or amountFiatUsd.

amount: integer string in sats for amountMode: "exact_in" (default), or destination smallest units for "exact_out".
amountFiatUsd: USD string from "1.00" to "50000.00", converted to sats at spot. The order and webhooks record spotUsdPerBtc.

Fiat requests automatically use exact-out for eligible invoice-billed stablecoin payments; otherwise they use exact-in, where deducted fees reduce delivery. Set amountMode: "exact_in" to require that mode. Read the returned amountMode, amounts, and fees; partner-invoiced platform fees are billed separately.

exact_out is not supported to spark:BTC or bitcoin:BTC.
slippageBps is pinned to 1000. Lower values are clamped up; effectiveSlippageBps reports what was applied.
Use returned expiresAt. Exact-in normally lasts 24 hours; exact-out and fixed-delivery requests use 5 minutes. Fixed delivery can fall back when unavailable. Reopening does not extend expiry.
refundAddress is a Lightning address (user@domain) or an amountless BOLT11 invoice, used if the order fails before the swap. Other values are dropped and named in ignoredFields.

Destinations

Destinations are the lightning:BTC entry’s route.to set on GET /v2/orchestration/routes. Common targets:

USDB on Spark: swap into USDB; fees in USDB.
BTC on Spark or Bitcoin L1: settle the fee, then deliver BTC; fees in sats.
USDC on Solana or Base: swap, bridge, and deliver; fees in USDC.

Restrictions

Not available to residents of New York City. Lightning payer apps impose their own per-payment limits; validate client-side against the limits.fiatUsd band from GET /v1/orchestration/limits. See Routes and limits.

Frontend rules

Keep the API key on your backend. Proxy /v1/sse/ paths through your server with Content-Type: text/event-stream.
Separate invoice UI expiry from order tracking. Close SSE on completed, failed, or refunded; continue tracking unfulfilled for late settlement during the six-hour recovery window from timeout. If SSE fails, poll GET /v1/orchestration/status?id=ORDER_ID every 3 seconds.

Live demo: orchestra.flashnet.xyz/onramp. Source: flashnetxyz/pay-link-example.

Start

Core

Flows

Security

Legacy

Prerequisites

Flow

Amount modes

Destinations

Restrictions

Frontend rules

​Prerequisites

​Flow

​Amount modes

​Destinations

​Restrictions

​Frontend rules

Prerequisites

Flow

Amount modes

Destinations

Restrictions

Frontend rules