Skip to main content
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

1

Create a webhook endpoint

Register a webhook endpoint and store the returned secret.
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.
2

Request a quote

Quotes expire 2 minutes after creation. Expired quotes are repriced at live market rates if a deposit arrives after expiry.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.
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
  }'
3

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): depositAddress is a deposit address on the source chain.
For USDC routes, send exactly amountIn.
4

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

Track the order

Preferred: use webhooks.Fallback: poll status.
curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/status?id=ord_..."
Treat every webhook delivery as at least once.

​
Picking a Route

​
Beyond the Basics

For advanced flows, see the dedicated guides:
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 for approval/refund flows:
  • order.status
  • order.reprice
  • order.paymentIntent
  • order.zeroconfOffer
  • order.refund

​
Next Steps