Quickstart

Orchestra uses one async flow for every live route. You request a quote, accept a deposit, submit it, then track the order to completion. Base URL: https://orchestration.flashnet.xyz

Before you start

Create an account in the Orchestra dashboard. Flashnet reviews new accounts before enabling API access. After approval, create a server key and keep it outside client-side code.

The minimal flow

Create a webhook endpoint

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.

Request a quote

Show prices with the public GET /v1/orchestration/estimate while the user is browsing; call /quote only when they commit. Each /quote persists a quote and allocates a deposit address.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): route USDC on Base to USDT on Solana.

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": "solana",
    "destinationAsset": "USDT",
    "amount": "100000000",
    "recipientAddress": "So1anaRecipientAddress...",
    "slippageBps": 50
  }'

Send the deposit

Send the source asset to depositAddress.The deposit instruction depends on the route:

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.
Any other source chain (Solana, Base, other EVM chains, Tron, and the rest of GET /v1/orchestration/routes): depositAddress is a deposit address on the source chain that receives the source asset.

Send exactly amountIn of the source asset.

Submit the deposit

Submitting creates an order. Processing is async.submit requires:

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

USDC deposit submit:

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:

{ "quoteId": "q_...", "sparkTxHash": "spark_transfer_id_or_token_tx_hash" }

{ "quoteId": "q_...", "bitcoinTxid": "<txid>", "bitcoinVout": 0 }

{ "quoteId": "q_...", "lightningReceiveRequestId": "<id>" }

See API Reference for the full request shapes and optional fields.

Track the order

Preferred: use webhooks.Fallback: poll status after an order exists. For submissionless flows, use GET /v1/orchestration/order?quoteId=... until the deposit creates an order.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/status?id=ord_..." \
  -H "Authorization: Bearer fn_..."

Treat every webhook delivery as at least once.

Picking a route

General payments and swaps: start with General Swaps, then choose a pair from Supported Routes.
Bitcoin swaps: use Stablecoin to BTC or BTC to Stablecoin.
Reusable deposit addresses: use reusable addresses when you do not want to call /quote and /submit per deposit.

Beyond the basics

For advanced flows, see the dedicated guides:

Order Lifecycle: State machine, deposit flexibility, repricing, field mapping
ZeroConf: Instant Bitcoin L1 credit
BTC to Stablecoin: Exact-out payment intents
API: Quotes and Orders: Affiliate fees (appFees / affiliateId)
API: Approval Flows: Repricing and refund endpoints

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: Compare quote/submit, accumulation, and liquidation patterns
Supported Routes: Discover live source and destination pairs
General Swaps: Route stablecoins and native assets without a BTC endpoint
Order Lifecycle: State machine and field mapping
Stablecoin to BTC: Buy Bitcoin with USDC
BTC to Stablecoin: Sell Bitcoin for USDC
Webhooks: Receive order status updates
API Reference: Complete endpoint documentation

Overview

Concepts

Guides

Reference

Security

Before you start

The minimal flow

Picking a route

Beyond the basics

Recommended data model

Next steps

​Before you start

​The minimal flow

​Picking a route

​Beyond the basics

​Recommended data model

​Next steps

Before you start

The minimal flow

Picking a route

Beyond the basics

Recommended data model

Next steps