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

# Orchestra

> Route swaps between BTC and stablecoins across chains using Orchestra's async API.

export const TabCards = ({categories, hideButtons = false}) => {
  const [activeCategory, setActiveCategory] = React.useState(categories[0].id);
  const [activeSubTab, setActiveSubTab] = React.useState(categories[0].items[0]?.id ?? null);
  const currentCategory = categories.find(cat => cat.id === activeCategory);
  const currentSub = currentCategory?.items.find(item => item.id === activeSubTab);
  return <div className="not-prose">
    {!hideButtons && <div className="flex flex-wrap gap-2 mb-4">
        {categories.map((cat, index) => {
    const colors = ['#02B302', '#02B302', '#02B302'];
    const activeColor = colors[index % colors.length];
    return <button key={cat.id} onClick={() => {
      setActiveCategory(cat.id);
      setActiveSubTab(cat.items[0]?.id ?? null);
    }} className={`px-4 py-2 text-sm font-medium transition-colors ${activeCategory === cat.id ? 'text-white' : 'fn-tabcard-btn'}`} style={activeCategory === cat.id ? {
      backgroundColor: activeColor
    } : {}}>
              {cat.label}
            </button>;
  })}
      </div>}

      <div>
        {currentCategory?.items?.length ? <div className="fn-tabcard-container flex flex-col lg:flex-row items-stretch" style={{
    padding: '12px',
    gap: '12px'
  }}>
            <div className="flex flex-col w-full lg:w-[38%] flex-shrink-0 justify-center" style={{
    gap: '2px'
  }}>
              {currentCategory.items.map(item => <a key={item.id} onMouseOver={() => setActiveSubTab(item.id)} className={`group flex items-start text-left transition-all cursor-pointer ${activeSubTab === item.id ? 'fn-tabcard-item-active' : ''}`} style={{
    padding: '6px 10px'
  }}>
                  <div className="flex-1 flex flex-col" style={{
    gap: '1px'
  }}>
                    <h3 className="fn-tabcard-title font-medium leading-tight" style={{
    fontSize: '13px'
  }}>
                      {item.title}
                    </h3>
                    <div className="fn-tabcard-desc leading-snug" style={{
    fontSize: '11px'
  }}>{item.desc}</div>
                  </div>
                </a>)}
            </div>
            <div className="w-full lg:w-[62%] overflow-hidden relative flex items-center justify-center" style={{
    minHeight: '340px',
    padding: '16px'
  }}>
              {currentSub?.image ? <>
                <img src={currentSub.image.light} alt={currentSub.title} className="fn-tabcard-img-light pointer-events-none" style={{
    maxHeight: '310px',
    width: 'auto',
    maxWidth: '100%',
    objectFit: 'contain'
  }} />
                <img src={currentSub.image.dark} alt={currentSub.title} className="fn-tabcard-img-dark pointer-events-none" style={{
    maxHeight: '310px',
    width: 'auto',
    maxWidth: '100%',
    objectFit: 'contain'
  }} />
              </> : <div className="flex items-center justify-center h-full fn-tabcard-container">
                  <p className="fn-tabcard-desc p-8">Image coming soon</p>
                </div>}
            </div>
          </div> : <p className="fn-tabcard-desc text-sm">
            No features available for this category.
          </p>}
      </div>
    </div>;
};

Flashnet Orchestra is an async orchestration protocol. It gives you deposit instructions, executes the route, and delivers the output asset to your recipient.

## Start here

<CardGroup cols={3}>
  <Card title="Quickstart" href="/products/orchestration/integration">
    Build a minimal end-to-end flow.
  </Card>

  <Card title="Choose Your Integration" href="/products/orchestration/choosing-a-flow">
    Compare quote/submit, accumulation, and liquidation patterns.
  </Card>

  <Card title="Order Lifecycle" href="/products/orchestration/order-lifecycle">
    State machine, field mapping, and how quotes become orders.
  </Card>
</CardGroup>

## Routes

<CardGroup cols={2}>
  <Card title="Buy BTC" href="/products/orchestration/stablecoin-to-btc">
    Convert supported stablecoins and native assets, including Tempo USDC, into BTC on Spark, Bitcoin L1, or Lightning.
  </Card>

  <Card title="Sell BTC" href="/products/orchestration/btc-to-stablecoin">
    Convert BTC or USDB into USDC, PathUSD, USDT, ETH, SOL, BNB, DAI, TRX, WBTC, cbBTC, or USDC.e across supported chains.
  </Card>
</CardGroup>

## Fiat onramp

<CardGroup cols={2}>
  <Card title="Lightning Onramp" href="/products/orchestration/onramp">
    The cheapest fiat-to-crypto path. Users pay via any Lightning-compatible app, Orchestra delivers USDB, BTC on Spark or Bitcoin L1, USDC, or any supported asset. Custom pricing. Single API call.
  </Card>

  <Card title="Pay Links" href="/products/orchestration/pay-links">
    Shareable payment links that never expire. Specify the stablecoin output, share the URL. Each click creates a fresh Lightning invoice at the current rate.
  </Card>
</CardGroup>

## Reusable deposit addresses

<CardGroup cols={2}>
  <Card title="Accumulation addresses" href="/products/orchestration/reusable-addresses#accumulation-addresses">
    Reusable deposit address (Solana or any chain Orchestra supports) that auto-delivers BTC or USDB on Spark.
  </Card>

  <Card title="Liquidation addresses" href="/products/orchestration/reusable-addresses#liquidation-addresses">
    Reusable Bitcoin L1 address that auto-delivers to any chain and asset Orchestra supports.
  </Card>
</CardGroup>

## What it does

Partners specify source asset, destination asset, amount, and recipient. Orchestra returns a deposit instruction and then advances the order through deposit detection, execution, and delivery.

You integrate the same interface across routes:

* `POST /v1/orchestration/quote` to get `depositAddress` and quote metadata
* fund the deposit instruction (address or invoice)
* `POST /v1/orchestration/submit` to create the order
* track progress via webhooks or `GET /v1/orchestration/status`

## What can I build with Orchestra?

<TabCards
  hideButtons={true}
  categories={[
{
id: 'usecases',
label: 'Use Cases',
items: [
  {
    id: 'wallets',
    title: 'Wallets',
    desc: 'Stablecoin-to-BTC swaps with slippage-bounded execution. Users swap and receive BTC on Spark in seconds.',
    image: {
      light: '/assets/usecases/swap.png',
      dark: '/assets/usecases/swap.png'
    }
  },
  {
    id: 'exchanges-trading',
    title: 'Exchanges & Trading',
    desc: 'Lightning and ZeroConf Bitcoin deposits confirmed in under 10 seconds. On-chain deposits supported with standard confirmations.',
    image: {
      light: '/assets/usecases/deposit.png',
      dark: '/assets/usecases/deposit.png'
    }
  },
  {
    id: 'payouts',
    title: 'Payouts',
    desc: 'Send Bitcoin anywhere, instantly. Pay in USDC, settle in BTC. Employees and contractors paid in under a minute.',
    image: {
      light: '/assets/usecases/send.png',
      dark: '/assets/usecases/send.png'
    }
  },
  {
    id: 'commerce',
    title: 'Commerce',
    desc: 'Accept Bitcoin, settle in stablecoins. Your customers pay in BTC. You receive USDC. Zero volatility risk.',
    image: {
      light: '/assets/usecases/commerce.png',
      dark: '/assets/usecases/commerce.png'
    }
  },
  {
    id: 'savings-dca',
    title: 'Savings & DCA',
    desc: 'Automated Bitcoin accumulation. Set it and forget it. Users stack sats daily, weekly, or monthly.',
    image: {
      light: '/assets/usecases/dca.png',
      dark: '/assets/usecases/dca.png'
    }
  },
  {
    id: 'engagement',
    title: 'Engagement',
    desc: 'Reward users with real Bitcoin. Drive retention with sats-back rewards. Every action earns Bitcoin.',
    image: {
      light: '/assets/usecases/rewards.png',
      dark: '/assets/usecases/rewards.png'
    }
  }
]
}
]}
/>

## Which chains and assets are supported?

Orchestra currently supports:

* Chains: `base`, `solana`, `ethereum`, `arbitrum`, `optimism`, `polygon`, `bsc`, `tron`, `plasma`, `tempo`, `monad`, `spark`, `bitcoin`, `lightning`
* Assets: `USDC`, `USDC.e`, `USDT`, `USDB`, `BTC`, `ETH`, `SOL`, `BNB`, `DAI`, `WBTC`, `cbBTC`, `PathUSD`

Tempo `USDC` is supported as both a source and destination asset. Tempo `PathUSD` is currently supported as a destination asset. `WBTC` and `DAI` are available on Ethereum. `cbBTC` is available on Base, Solana, and Monad. `BNB` and `USDT` are available on BSC. `USDC.e` is available on Polygon. Monad supports `USDC` and `cbBTC`.

Not all chain/asset combinations are valid. Use `GET /v1/orchestration/routes` to see available trading pairs, or see the route listings in:

* [Stablecoin to BTC](/products/orchestration/stablecoin-to-btc)
* [BTC to Stablecoin](/products/orchestration/btc-to-stablecoin)

## How it works

Under the hood, Orchestra combines three primitives:

1. Bridge: Bridges stablecoin value between source chains and Spark via Solana USDC as the settlement hub. The bridge handles any chain-to-chain transfers.
2. AMM: Swaps USDB and BTC on Spark liquidity.
3. Bitcoin ingress handling: Supports both confirmation-based and ZeroConf-assisted L1 deposit processing.

Partners do not integrate these primitives directly. Orchestra abstracts bridge, AMM, and ingress handling as quote, submit, status, and webhook flows.

## Execution model

Quotes expire after 2 minutes. Expired quotes are not rejected at submit time: late deposits are always accepted, repriced at the live market rate at detection time, and executed against the quote's `slippageBps`. Deposits do not need to match the quoted amount exactly. The engine adjusts amounts and fees to reflect the actual deposit. Orders that cannot execute within `slippageBps` refund automatically without partner action.

See [Order Lifecycle](/products/orchestration/order-lifecycle) for the full state machine, field mapping between quotes and orders, deposit flexibility rules, and market-move refund behavior. See [ZeroConf](/products/orchestration/zeroconf) for instant Bitcoin L1 credit.

## What are the fees?

Swaps have two cost components, both embedded in the quoted output amount:

* **Platform fee**: Custom pricing based on route and volume. The fee is denominated on the stablecoin side of the swap (`USDC` for most routes, `USDB` for the BTC/USDB direct pair). Direct BTC passthrough routes charge the platform fee in BTC. The `/estimate` and `/quote` endpoints return the exact fee for each transaction.
* **LP pool fee**: Charged by the BTC/USDB pool on Spark in the input asset. When selling BTC, the LP fee is in BTC. When buying BTC with stablecoins, the LP fee is in USDB. This goes to liquidity providers, not Flashnet. The exact amount varies with pool depth and trade size.

Both fees are embedded in the quoted output. The user sends X, receives the quoted Y. Spark-to-Spark transfers incur no network gas fees (platform fees still apply). Lightning and Bitcoin L1 withdrawals incur network fees quoted at delivery time (see below).

[Onramp](/products/orchestration/onramp) and [Pay Links](/products/orchestration/pay-links) use custom pricing. USDB routes are cheaper because they settle natively on Spark without bridging. All fees on onramp and pay links are sender-side: the recipient receives the configured output net of route-specific execution costs, and the sender's Lightning invoice is sized to cover output plus fees.

For approved partners, Flashnet can configure invoice billing for a specific route. In invoice billing, the per-transaction platform fee is not deducted from the user flow. The billed bps accrue to the partner account and are visible through `GET /v1/partner/dashboard/fee-invoices`. This is configured by Flashnet and is not a request parameter.

For `lightning:BTC -> bitcoin:BTC`, the final on-chain withdrawal also pays the network withdrawal fee quoted by Spark at delivery time. That withdrawal fee is separate from Flashnet's platform fee.

Orchestra supports optional app and affiliate fees on supported routes. Fees settle in Solana USDC or Spark USDB depending on the route.

### `appFees` (inline model)

Specify fee recipients directly in the quote request. Each entry includes a recipient address and fee in basis points. The fee plan is embedded in the order at creation time.

### `affiliateIds` (registered model)

Reference pre-registered affiliate profiles by ID. Entries can be plain strings (uses the profile's configured fee bps) or `{ affiliateId, feeBps }` objects to override the profile's bps for that request. The stored profile is not mutated.

Registered affiliates use a holdback model: they claim accumulated fees via `POST /v1/affiliates/:id/claim`. Claims settle to the `(payoutChain, payoutAsset, payoutAddress)` on the profile. Supported destinations include Solana USDC, Spark assets, and EVM chains (USDC/USDT on Base, Ethereum, Arbitrum, Optimism, Polygon, BSC).

### Fee rules

| Rule               | Detail                                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Amount mode        | Standard quote/submit flows require `amountMode=exact_in`. Pay links are sender-side and work with exact-out mode.                                                              |
| Reusable addresses | Accumulation and liquidation addresses accept `appFees` and `affiliateIds` at creation time. The fee plan is validated, frozen on the address, and replayed into every deposit. |
| Platform cut       | Flashnet takes 20% of all app/affiliate fees.                                                                                                                                   |
| Mutual exclusivity | `appFees` and `affiliateIds` cannot be combined in the same request.                                                                                                            |

See [Quotes and Orders](/products/orchestration/api/quotes-and-orders#post-v1orchestrationquote) for the full affiliate fee model.

## Settlement

* BTC settles to Spark wallets.
* Stablecoins settle to any supported chain (base, solana, ethereum, arbitrum, optimism, polygon, bsc, tron, plasma, tempo, monad).
* Orders can settle as `completed`, `failed`, `expired`, `unfulfilled`, or `refunded`.
* Partners track progress via webhooks or `GET /v1/orchestration/status`.

Bitcoin L1 deposits can use [ZeroConf](/products/orchestration/zeroconf) for instant credit or wait for on-chain confirmations.

## What do partners not need?

* Spark protocol integration
* Direct liquidity management
* Bitcoin node operations
* Bridge infrastructure management

## What do partners need?

* Ability to fund the provided deposit instruction (address or invoice)
* Destination address for delivery
* Optional affiliate configuration (`appFees`, `affiliateId`, or `affiliateIds`) for routes that support app fees
* Webhook endpoint or polling logic
* Approval handling if `awaiting_approval` is reached (ZeroConf offers only)

## What are the limits?

| Parameter            | Value                                    |
| -------------------- | ---------------------------------------- |
| Minimum              | \$1 equivalent                           |
| Maximum              | \$100,000 equivalent                     |
| BTC swap minimum     | 1,000 sats                               |
| Platform Fee         | Custom pricing based on route and volume |
| App Fee Platform Cut | 20% of app/affiliate fees                |

<Warning>
  Some USDC-source routes include a sweep fee that creates an effective minimum higher than \$1. The quote response includes `sweepFeeAmount` when applicable. See [Effective Limits](/products/orchestration/order-lifecycle#what-are-the-effective-limits) for details.
</Warning>

## Next steps

* [Quickstart](/products/orchestration/integration): Build a minimal end-to-end flow
* [Choose Your Integration](/products/orchestration/choosing-a-flow): Compare quote/submit, accumulation, and liquidation patterns
* [Order Lifecycle](/products/orchestration/order-lifecycle): State machine, field mapping, repricing
* [Stablecoin to BTC](/products/orchestration/stablecoin-to-btc): Buy Bitcoin with USDC
* [BTC to Stablecoin](/products/orchestration/btc-to-stablecoin): Sell Bitcoin for USDC
* [ZeroConf](/products/orchestration/zeroconf): Instant Bitcoin L1 credit
* [Webhooks](/products/orchestration/webhooks): Receive order status updates
* [API Reference](/products/orchestration/api/overview): Complete endpoint documentation