> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashnet.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Fiat onramp

> Lightning-funded orders

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](https://orchestra.flashnet.xyz/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](/api/authentication).

## Flow

<Steps>
  <Step title="Preview the price (optional)">
    `GET /v1/orchestration/estimate` with `sourceChain=lightning&sourceAsset=BTC` returns an indicative `estimatedOut` without creating anything.
  </Step>

  <Step title="Create the onramp order">
    Request \$50.00 over Lightning into USDB on Spark:

    <CodeGroup>
      ```bash curl theme={null}
      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"
        }'
      ```

      ```typescript TypeScript theme={null}
      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();
      ```
    </CodeGroup>

    <Info>
      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`.
    </Info>

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

    ```json theme={null}
    {
      "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](/orchestra/pay-links) for repeat checkout.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Track the order">
    Subscribe to SSE or register a webhook; see [Status](/orchestra/status) and Frontend rules below.
  </Step>
</Steps>

## 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](/orchestra/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](https://orchestra.flashnet.xyz/onramp). Source: [flashnetxyz/pay-link-example](https://github.com/flashnetxyz/pay-link-example).