Fiat Onramp

Many popular apps support zero-fee Lightning payments. Orchestra combines zero-fee Lightning with its Lightning-to-Spark pipeline to create a fiat-to-crypto onramp with a single API call. The native destination is USDB on Spark (details). The onramp to USDB skips all bridging and settles in seconds. Direct BTC destinations on Spark and Bitcoin L1 keep the flow in BTC and charge the platform fee in sats before delivery. Other destinations, such as USDC on Solana or Base, work through the same pipeline but add swap, bridge, and delivery steps.

Try it live at orchestra.flashnet.xyz/onramp.

The fiat onramp is not available to residents of New York City.

How it works

Your app calls POST /v1/orchestration/onramp with the destination chain, asset, recipient address, and an amount. The amount can be:
- BTC sats the user sends (amount with amountMode: "exact_in", the default)
- Destination asset to receive (amount with amountMode: "exact_out")
- USD the user sees in Cash App (amountFiatUsd, runs as exact_in after Orchestra fetches BTC/USD spot).
Orchestra creates a Lightning invoice, builds the order, and returns payment deeplinks.
The user opens the deeplink (or scans a QR code) and pays via their preferred Lightning-compatible app.
Orchestra receives the Lightning payment, swaps BTC to the destination asset, and delivers it.

The onramp endpoint handles quoting and submission in one call. A separate /estimate endpoint exists as an optional preview step (see Integration).

Why choose USDB or direct BTC?

Every onramp route starts from lightning:BTC. When you choose USDB, Orchestra swaps BTC to USDB and finishes on Spark. When you choose BTC on Spark or Bitcoin L1, Orchestra stays in BTC and delivers the remaining sats after fees. When you choose USDC on another chain, Orchestra must also bridge and deliver, adding cost and latency.

	USDB on Spark	BTC on Spark / Bitcoin L1	USDC on Solana/Base
Platform fee	Custom pricing	Custom pricing	Custom pricing
Fee asset	USDB	BTC	USDC
Pipeline shape	Verify, swap	Verify, settle BTC fee, deliver	Verify, swap, bridge, deliver
Delivery time	Seconds	Seconds	Seconds
Sweep fee	None	None	May apply (details)
Rewards	3.5-6% rewards in BTC	None	None

See USDB Rewards for reward details.

What are the fees?

Many Lightning-compatible apps charge zero fees on Lightning payments. Orchestra uses route-and-volume-based pricing that undercuts card-based and bank-transfer onramps. No intermediary fees and no card processing fees. The /estimate endpoint returns the exact fee for each route. See Fees for the full fee model.

For lightning:BTC -> bitcoin:BTC, the platform fee is taken in BTC and the final on-chain withdrawal also pays the network withdrawal fee quoted by Spark at delivery time. That Bitcoin withdrawal fee is not Flashnet revenue.

What are the Lightning payment limits?

Some Lightning-compatible apps impose their own limits on Lightning payments (for example, up to $999 per rolling 7-day window). Check your payment app’s documentation for specific limits. Orchestra’s own per-route amount bounds come from GET /v1/orchestration/limits.

Validate amounts client-side against your payment app’s limits before calling the API.

Which routes are supported?

The source is always lightning:BTC. For the current destination list, call GET /v1/orchestration/routes and filter to routes with a lightning:BTC source. The set changes as chains and assets are added, so query it rather than hardcoding destinations.

Integration

Get a price estimate

Use the estimate endpoint to show the user what they’ll receive before committing.

curl 'https://orchestration.flashnet.xyz/v1/orchestration/estimate?\
sourceChain=lightning&sourceAsset=BTC&\
destinationChain=spark&destinationAsset=USDB&\
amount=100000'

Response:

{
  "estimatedOut": "96543210",
  "feeAmount": "19308",
  "feeBps": 20,
  "totalFeeAmount": "19308",
  "feeAsset": "USDB",
  "route": [
    "BTC",
    "USDB"
  ],
  "source": {
    "chain": "lightning",
    "asset": "BTC",
    "chainDisplayName": "Lightning",
    "chainIcon": "/chain-lightning.svg",
    "contractAddress": null,
    "decimals": 8,
    "chainId": null
  },
  "destination": {
    "chain": "spark",
    "asset": "USDB",
    "chainDisplayName": "Spark",
    "chainIcon": "/chain-spark.svg",
    "contractAddress": "btkn1usdb...",
    "decimals": 6,
    "chainId": null
  }
}

totalFeeAmount is feeAmount plus roundingFeeAmount plus appFeeAmount. Estimates never include sweep fees. Some fields appear only when applicable: roundingFeeAmount when nonzero, deliveryMode when fixed delivery applies, and appFeeAmount, appFeePlatformCutAmount, and appFees when app fees were requested.

Create the onramp order

A single call creates the Lightning invoice, builds the order, and returns payment deeplinks.

const BASE_URL = 'https://orchestration.flashnet.xyz';

const onramp = await fetch(`${BASE_URL}/v1/orchestration/onramp`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `onramp:${Date.now()}`,
  },
  body: JSON.stringify({
    destinationChain: 'spark',
    destinationAsset: 'USDB',
    recipientAddress: 'spark1YourSparkAddress...',
    amount: '100000', // sats
  }),
}).then((r) => r.json());

Response:

{
  "orderId": "ord_abc123",
  "quoteId": "q_xyz789",
  "depositAddress": "lnbc1000n1pj...",
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1000n1pj...",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/a3xKm2Rq"
  },
  "amountIn": "100000",
  "estimatedOut": "96543210",
  "feeAmount": "19308",
  "feeBps": 20,
  "totalFeeAmount": "19308",
  "feeAsset": "USDB",
  "route": [
    "BTC",
    "USDB"
  ],
  "expiresAt": "2026-01-16T12:04:00.000Z"
}

Complete the payment

On mobile, redirect the user to the payment deeplink. On desktop, display the deeplink as a QR code for the user to scan with their phone. Use shortUrl when sharing payment links in messages or emails.

// Mobile: direct deeplink
window.location.href = onramp.paymentLinks.cashApp;

// Desktop: render QR code with the deeplink URL
// The QR encodes the full cash.app URL, not the BOLT11 invoice
renderQR(onramp.paymentLinks.cashApp);

// Sharing: use the short URL for texts, emails, etc.
const shareableLink = onramp.paymentLinks.shortUrl;
// e.g. https://orchestration.flashnet.xyz/pay/a3xKm2Rq

The quote and its Lightning invoice expire at expiresAt: 24 hours after creation for exact-in onramps, 5 minutes for exact-out and fixed-delivery exact-in onramps (the short TTL bounds BTC price drift against the locked target). If the user doesn’t pay in time, create a new onramp order.

Track the order

Use SSE or polling to track progress. USDB orders skip the bridge and delivery steps, so they complete faster.

// SSE (preferred)
const es = new EventSource(
  `${BASE_URL}/v1/sse/operations/${onramp.orderId}?token=${API_KEY}`
);
es.addEventListener('status', (e) => {
  const { status } = JSON.parse(e.data);
  console.log(status); // confirming, swapping, completed, etc.
});

// Or poll
const status = await fetch(
  `${BASE_URL}/v1/orchestration/status?id=${onramp.orderId}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then((r) => r.json());

Frontend integration

Onramp shares the browser-side deep link patterns with Pay Links. For the Cash App navigation trick, the SSE order-tracking hook, the API-key proxy pattern, and the pipeline-progress UI, see Deep link best practices.

Exact output mode

By default, you specify how many sats the user sends (exact_in) and Orchestra estimates the output. With amountMode: "exact_out", you specify the destination amount the recipient should receive, and Orchestra calculates the required Lightning payment. This is useful when your UX needs to guarantee a specific dollar amount, for example “onramp exactly $50 USDC.”

const onramp = await fetch(`${BASE_URL}/v1/orchestration/onramp`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `onramp:${Date.now()}`,
  },
  body: JSON.stringify({
    destinationChain: 'solana',
    destinationAsset: 'USDC',
    recipientAddress: 'So1anaAddress...',
    amount: '50000000', // 50 USDC (6 decimals)
    amountMode: 'exact_out',
  }),
}).then((r) => r.json());

The response includes the calculated amountIn (sats required) and a Lightning invoice for that amount. The user pays the invoice, and the recipient receives the specified output amount. Exact-out quotes expire 5 minutes after creation, not the 24 hours of exact-in quotes. For stablecoin destinations, exact-out amount must be a whole-cent value in the destination asset’s smallest units. For 6-decimal stables, send multiples of 10000, for example "50000000" for $50.00. If execution produces extra stablecoin units above the exact-out target, Orchestra retains the surplus as roundingFeeAmount instead of overdelivering.

Affiliate fees (appFees, affiliateId, affiliateIds) are not supported with exact_out. Use exact_in (or amountFiatUsd) if you need affiliate fees on the transaction.

Exact-out is not supported for the direct BTC passthrough routes lightning:BTC -> spark:BTC and lightning:BTC -> bitcoin:BTC.

USD-pinned mode (`amountFiatUsd`)

amountFiatUsd lets the partner pin the sender’s USD figure. Cash App displays the exact dollar amount, the receiver gets the net after fees, and Orchestra runs the order in exact_in mode. The conversion happens server-side at request time: Orchestra fetches the current BTC/USD spot from a Coinbase and Kraken price oracle, computes the equivalent sats, and pins that as the source amount. The spot used is recorded on the order and surfaced on the webhook as spotUsdPerBtc.

const onramp = await fetch(`${BASE_URL}/v1/orchestration/onramp`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `onramp:${Date.now()}`,
  },
  body: JSON.stringify({
    destinationChain: 'solana',
    destinationAsset: 'USDC',
    recipientAddress: 'So1anaAddress...',
    amountFiatUsd: '100.00', // sender pays exactly $100 in Cash App
  }),
}).then((r) => r.json());

The order webhook for the resulting completed order includes the fiat snapshot at the top level:

{
  "amountIn": "<sats>",
  "amountOut": "99500000",
  "feeBps": 50,
  "feeAmount": "500000",
  "amountFiatUsd": "100.00",
  "amountFiatCurrency": "USD",
  "spotUsdPerBtc": "100450.00"
}

amountFiatUsd is mutually exclusive with amount. Range

1.00 to

50,000.00. If BTC/USD spot is unavailable at request time, the route fails closed with HTTP 503 (spot_unavailable); a stale price would silently misalign the user-displayed Cash App figure.

amountFiatUsd combined with amountMode: "exact_out" is available only for USD-stablecoin destinations and only for invoice-billing partners (other partners get invoice_required). It rejects app and affiliate fees with unsupported_fee_plan. Plain amountFiatUsd runs as exact_in and has none of these restrictions.

API reference

Field-level request and response documentation for POST /v1/orchestration/onramp lives in Quotes and orders. Two behaviors to keep in mind while integrating: slippage is pinned to 1000 bps on every onramp regardless of input, and exact-in quotes last 24 hours while exact-out and fixed-delivery quotes last 5 minutes.

Affiliate fees

The onramp accepts the same affiliate fee fields as the quote flow: appFees (inline), affiliateId (one registered affiliate), or affiliateIds (several registered affiliates, each optionally overriding the profile’s fee bps for that order). Two onramp-specific gates apply: affiliate fees require amountMode: "exact_in" (the default), and they require a stablecoin settlement path, so the direct BTC routes lightning:BTC -> spark:BTC and lightning:BTC -> bitcoin:BTC reject them. See Fees for the fee model and Resources for registration and claims.

Webhooks

Register an endpoint via POST /v1/webhooks to receive order status updates. An onramp order emits order.processing on creation, then one event per pipeline stage the route includes (order.confirming, order.swapping, order.bridging, order.delivering), and ends with order.completed. A failure emits order.failed; a refund emits order.refunding then order.refunded. Orders created with amountFiatUsd carry the fiat snapshot (amountFiatUsd, amountFiatCurrency, spotUsdPerBtc) at the top level of the payload. See Webhooks for signature verification and delivery semantics, and Webhook events for the full payload field reference.

Next steps

USDB Rewards for yield details
API Overview for authentication and error handling
Order Lifecycle for status transitions and webhook payloads
Webhooks for real-time order updates

Overview

Concepts

Guides

Reference

Security

How it works

Why choose USDB or direct BTC?

What are the fees?

What are the Lightning payment limits?

Which routes are supported?

Integration

Frontend integration

Exact output mode

USD-pinned mode (`amountFiatUsd`)

API reference

Affiliate fees

Webhooks

Next steps

​How it works

​Why choose USDB or direct BTC?

​What are the fees?

​What are the Lightning payment limits?

​Which routes are supported?

​Integration

​Frontend integration

​Exact output mode

​USD-pinned mode (amountFiatUsd)

​API reference

​Affiliate fees

​Webhooks

​Next steps

How it works

Why choose USDB or direct BTC?

What are the fees?

What are the Lightning payment limits?

Which routes are supported?

Integration

Frontend integration

Exact output mode

USD-pinned mode (`amountFiatUsd`)

API reference

Affiliate fees

Webhooks

Next steps