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

# Quickstart

> Build a working Orchestra integration: quote, deposit, submit, and track an order end to end.

Orchestra is async. You request a quote, accept a deposit, submit it, then track the order to completion.

Base URL: `https://orchestration.flashnet.xyz`

## The minimal flow

<Steps>
  <Step title="Create a webhook endpoint">
    Register a webhook endpoint and store the returned secret.

    ```bash theme={null}
    curl -sS -X POST "https://orchestration.flashnet.xyz/v1/webhooks" \
      -H "Authorization: Bearer fn_..." \
      -H "X-Idempotency-Key: webhook:create:YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url":"https://yourapp.example.com/flashnet/webhooks"}'
    ```

    Verify inbound webhooks using `X-Flashnet-Signature` and the raw request body. See [Webhooks](/products/orchestration/webhooks).
  </Step>

  <Step title="Request a quote">
    Quotes expire 2 minutes after creation. Late deposits are always repriced at live market rates at detection time and execute against the quote's `slippageBps`.

    Quote requests that you intend to submit must include `Authorization` and `X-Idempotency-Key`.

    Example (exact-in, default mode): buy BTC on Spark with USDC on Base.

    ```bash theme={null}
    curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/quote" \
      -H "Authorization: Bearer fn_..." \
      -H "X-Idempotency-Key: quote:create:YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "sourceChain": "base",
        "sourceAsset": "USDC",
        "destinationChain": "spark",
        "destinationAsset": "BTC",
        "amount": "100000000",
        "recipientAddress": "spark1...",
        "slippageBps": 50
      }'
    ```
  </Step>

  <Step title="Send the deposit">
    Send the source asset to `depositAddress`.

    The deposit instruction depends on the route:

    * Base/Solana source (`sourceChain = base|solana`): `depositAddress` is a chain address that receives the source asset.
    * Spark source (`sourceChain = spark`): `depositAddress` is a Spark address.
    * Bitcoin source (`sourceChain = bitcoin`): `depositAddress` is a Bitcoin L1 address.
    * Lightning source (`sourceChain = lightning`): `depositAddress` is a BOLT11 invoice.
    * Chain source (`sourceChain = ethereum|arbitrum|optimism|polygon|tron|monad`): `depositAddress` is a deposit address on the source chain.

    For USDC routes, send exactly `amountIn`.
  </Step>

  <Step title="Submit the deposit">
    Submitting creates an order. Processing is async.

    `submit` requires:

    * `Authorization: Bearer fn_...`
    * `X-Idempotency-Key`

    USDC deposit submit:

    ```bash theme={null}
    curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/submit" \
      -H "Authorization: Bearer fn_..." \
      -H "X-Idempotency-Key: submit:YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "quoteId": "q_...",
        "txHash": "0x...",
        "sourceAddress": "0x..."
      }'
    ```

    Submit shape depends on the quote `sourceChain`. Examples:

    ```json theme={null}
    { "quoteId": "q_...", "sparkTxHash": "spark_transfer_id_or_token_tx_hash" }
    ```

    ```json theme={null}
    { "quoteId": "q_...", "bitcoinTxid": "<txid>", "bitcoinVout": 0 }
    ```

    ```json theme={null}
    { "quoteId": "q_...", "lightningReceiveRequestId": "<id>" }
    ```

    See [API Reference](/products/orchestration/api/quotes-and-orders) for the full request shapes and optional fields.
  </Step>

  <Step title="Track the order">
    Preferred: use webhooks.

    Fallback: poll status.

    ```bash theme={null}
    curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/status?id=ord_..."
    ```

    Treat every webhook delivery as at least once.
  </Step>
</Steps>

## Picking a route

* Swaps: start with [Stablecoin to BTC](/products/orchestration/stablecoin-to-btc) or [BTC to Stablecoin](/products/orchestration/btc-to-stablecoin).
* Reusable deposit addresses: use [reusable addresses](/products/orchestration/reusable-addresses) when you do not want to call `/quote` and `/submit` per deposit.

## Beyond the basics

<Info>
  For advanced flows, see the dedicated guides:

  * [Order Lifecycle](/products/orchestration/order-lifecycle): State machine, deposit flexibility, repricing, field mapping
  * [ZeroConf](/products/orchestration/zeroconf): Instant Bitcoin L1 credit
  * [BTC to Stablecoin](/products/orchestration/btc-to-stablecoin#example-btc-bitcoin-l1-to-usdc-exact-out-payment-intent): Exact-out payment intents
  * [API: Quotes and Orders](/products/orchestration/api/quotes-and-orders#post-v1orchestrationquote): Affiliate fees (`appFees` / `affiliateId`)
  * [API: Approval Flows](/products/orchestration/api/approval-flows): Repricing and refund endpoints
</Info>

## Recommended data model

Persist these identifiers:

* `quoteId`
* `orderId`
* the source transaction identifier you submitted (`txHash`, `bitcoinTxid` + `bitcoinVout`, Spark transfer id, or Lightning receive request id)

Persist these optional workflow fields:

* `order.status`
* `order.error` (for refund and failure diagnostics)
* `order.paymentIntent`
* `order.zeroconfOffer`
* `order.refund`

## Next steps

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