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. 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.
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:
  • order.status
  • order.error (for refund and failure diagnostics)
  • order.paymentIntent
  • order.zeroconfOffer
  • order.refund

​
Next steps