Quotes

A quote supplies deposit instructions and pricing valid for 2 minutes, subject to slippage. Choose a destination in the source asset’s route.to set. Orchestra detects funding, creates the order, and delivers to recipientAddress without a separate confirm call.

Prerequisites

An Orchestra account. Create one in the dashboard. Flashnet reviews new accounts before enabling API access.
A server key (fn_...) from API keys in the dashboard. Keep it on your backend. For browsers and apps, use a scoped client key (fnp_...); see Authentication.

Flow

Estimate

Call GET /v1/orchestration/estimate with the four route fields and amount on every input change. It is public and stateless.

Quote

Lock the price with POST /v1/orchestration/quote. Stablecoin on Base into BTC on Spark:

curl -X POST "https://orchestration.flashnet.xyz/v1/orchestration/quote" \
  -H "Authorization: Bearer SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceChain": "base",
    "sourceAsset": "USDC",
    "destinationChain": "spark",
    "destinationAsset": "BTC",
    "amount": "50000000",
    "recipientAddress": "RECIPIENT_ADDRESS"
  }'

const res = await fetch("https://orchestration.flashnet.xyz/v1/orchestration/quote", {
  method: "POST",
  headers: {
    Authorization: "Bearer SERVER_KEY",
    "Content-Type": "application/json",
    "X-Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    sourceChain: "base",
    sourceAsset: "USDC",
    destinationChain: "spark",
    destinationAsset: "BTC",
    amount: "50000000",
    recipientAddress: "RECIPIENT_ADDRESS",
  }),
});
const quote = await res.json();

Replace SERVER_KEY with your fn_... key. Use a new X-Idempotency-Key for each operation and reuse it when retrying that same request. Amounts are integer strings in the asset’s smallest unit: "100000" is 0.001 BTC; "50000000" is 50 USDC on Base. Read each asset’s decimals from /routes.

Another pair uses the same request shape: 0.001 BTC on Spark into USDC on Solana.

curl -X POST "https://orchestration.flashnet.xyz/v1/orchestration/quote" \
  -H "Authorization: Bearer SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceChain": "spark",
    "sourceAsset": "BTC",
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "amount": "100000",
    "recipientAddress": "RECIPIENT_ADDRESS"
  }'

Pay

Send amountIn of the source asset to depositAddress before expiresAt. Include depositMemo when returned. Eligible late funding uses refreshed pricing without the original guarantee; some expired submissions are rejected. See Pricing.

Watch

Poll GET /v1/orchestration/order?quoteId=QUOTE_ID with a server key until order is non-null, then follow the order on Status by webhook, SSE, or GET /v1/orchestration/status?id=ORDER_ID.

EVM funding transactions

Set includeCalldata: true on /quote to receive an unsigned transaction alongside depositAddress. /offramp accepts the same flag. Omitting it or setting it to false leaves transaction out of the response.

curl -X POST "https://orchestration.flashnet.xyz/v1/orchestration/quote" \
  -H "Authorization: Bearer SERVER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceChain": "base",
    "sourceAsset": "USDC",
    "destinationChain": "spark",
    "destinationAsset": "BTC",
    "amount": "50000000",
    "recipientAddress": "RECIPIENT_ADDRESS",
    "includeCalldata": true
  }'

The transaction fields are:

chainId: numeric EVM chain ID for the source network.
to: the token contract for ERC-20 funding, or depositAddress for native funding.
data: encoded transfer(depositAddress, amountIn) for ERC-20 funding, or "0x" for native funding.
value: decimal string in native smallest units; "0" for ERC-20 funding or the quote’s amountIn for native funding.

ERC-20
Native asset

This trimmed example transfers 50 USDC on Base to the illustrative deposit address 0x1111111111111111111111111111111111111111. Use the transaction from your own quote.

{
  "depositAddress": "0x1111111111111111111111111111111111111111",
  "amountIn": "50000000",
  "transaction": {
    "chainId": 8453,
    "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "data": "0xa9059cbb00000000000000000000000011111111111111111111111111111111111111110000000000000000000000000000000000000000000000000000000002faf080",
    "value": "0"
  }
}

The wallet calls the token’s transfer function and spends its own balance. No ERC-20 approval, allowance check, or transferFrom call is needed. Keep to set to the returned token contract; the deposit address is encoded in data.

This trimmed example funds a Base ETH quote with 0.001 ETH:

{
  "depositAddress": "0x1111111111111111111111111111111111111111",
  "amountIn": "1000000000000000",
  "transaction": {
    "chainId": 8453,
    "to": "0x1111111111111111111111111111111111111111",
    "data": "0x",
    "value": "1000000000000000"
  }
}

Send the returned native value to the deposit address. Keep enough native balance to pay gas in addition to value.

Switch the wallet to transaction.chainId, then send the returned to, data, and value. The wallet supplies the sender, nonce, and gas fees; ERC-20 transfers also require native gas. Convert value with BigInt for viem or ethers, or to a hex quantity for eth_sendTransaction. Never convert amounts through a JavaScript Number. For exact-out quotes, the transaction encodes the finalized source amountIn. The request’s amount is the destination target and must not replace it. Send one funding transaction before expiresAt; Orchestra then detects, sweeps, and executes the deposit. A confirmed funding transaction does not mean the swap is complete. Follow Status, and use submit when you have the funding transaction hash or need recovery. Only EVM sources with known native or ERC-20 metadata support the flag. Unsupported sources return 400 calldata_unsupported_source. A deposit instruction that needs a memo or cannot be encoded returns 502 calldata_unavailable; do not fund partial instructions. The flag is part of the idempotency body: use a new key when changing it, and reuse the same key and body after a timeout or 5xx.

Deposit address by source chain

EVM
Solana
Spark
Bitcoin
Lightning

Send the quoted token or native asset on the source chain. If detection misses, submit the transaction:

{ "quoteId": "QUOTE_ID", "txHash": "0x...", "sourceAddress": "0x..." }

sourceAddress is optional except on shared deposit addresses, where it identifies the sender.

depositAddress is a Solana address. Deposits are automatically detected. If auto-detection fails, submit the transaction:

{ "quoteId": "QUOTE_ID", "txHash": "<base58 signature>", "sourceAddress": "<sender>" }

depositAddress is a Spark address. Deposits are detected by the Spark ingress scan. Fallback submit body:

{ "quoteId": "QUOTE_ID", "sparkTxHash": "<transfer id>", "sourceSparkAddress": "<sender>" }

Spark USDB uses a quote-scoped sell address. Use the address returned for each quote. sourceSparkAddress is required for shared deposit addresses and optional otherwise.

depositAddress is an L1 address. Deposits are detected over ZMQ from a Bitcoin node. Fallback submit body:

{ "quoteId": "QUOTE_ID", "bitcoinTxid": "<64 hex>", "bitcoinVout": 0 }

Set bitcoinVout to the output paying depositAddress; 0 is only an example. Include it because some routes require it. L1 deposits may receive a ZeroConf offer.

depositAddress is a BOLT11 invoice and the quote also returns lightningReceiveRequestId. Paying the invoice creates the order. Fallback submit body:

{ "quoteId": "QUOTE_ID", "lightningReceiveRequestId": "<from the quote>" }

Orchestra populates the id from the quote. Lightning funding is detected automatically; for cross-chain quotes, /submit can return an existing order but cannot create one before detection. Keep polling if it returns 409 xchain_lightning_submissionless.To let the payer choose the amount, send "flexibleAmount": true with an exact-in, variable-delivery quote. The invoice has no amount; amount still prices the quote as an indicative size. The order runs on what is paid: amountIn, fees, and estimatedOut update to the paid amount. Payments below the route minimum are held for refund. Each invoice is still single-use.

For TON, Tron, XRP, Litecoin, Zcash, and Hedera, use the returned address and memo or tag exactly. Transfer the quoted asset: native coins use native transfers, tokens and TON jettons use their token transfer operation. Submit the source transaction id as txHash, with sourceAddress when required for a shared address.

When to call /submit

POST /v1/orchestration/submit reports funding when detection misses it or you have the transaction id already. Authenticate with the quote’s partner key and send the body for its source chain. Repeating the same deposit returns the existing order. An order id is not guaranteed at broadcast. Bitcoin and TON paths can require observed deposit proof. After a definitive verification rejection, wait for evidence and use a new idempotency key for the next recovery attempt. Reuse the same key after a timeout or 5xx; see Idempotency. Keep polling and do not send another payment. On success, use the returned orderId and status, plus readToken for client keys.

Quote response

quoteId: q_...; use it for /order and /submit.
depositAddress: where the user sends the source asset. Use this quote’s instructions.
depositMemo: memo or tag the deposit must carry; present only on provider routes that require one.
transaction: unsigned EVM funding transaction, present only when includeCalldata is true. See EVM funding transactions.
amountIn: source amount the price is based on.
estimatedOut: destination output; fixed delivery commits to it with timely, full funding. See funding conditions.
feeAmount, feeBps: platform fee in feeAsset units and its rate.
totalFeeAmount: sum of feeAmount, roundingFeeAmount, appFeeAmount, sweepFeeAmount, and networkCostAmount.
feeAsset: denomination of every fee field; see Fees.
route: path labels, which may be symbols or asset ids. Do not use them as catalog keys.
expiresAt: ISO timestamp, 2 minutes after creation.
priceLockMode, lockedMinAmountOut: optional price-lock policy and output floor. A price lock is separate from fixed delivery.
readToken: client keys only; bound to this quote and passed on status reads as readToken or X-Read-Token.
Exact-out quotes add amountMode, targetAmountOut, requiredAmountIn, maxAcceptedAmountIn, and inputBufferBps.
Lightning sources add lightningReceiveRequestId, and flexibleAmount: true when the invoice has no amount.

Rules

Use each quote’s returned deposit instructions; do not reuse cached instructions.
A quote is bound to the partner that created it. Only a key from the same partner can submit it.
affiliateId and affiliateIds require Authorization.
Send refundAddress whenever you can. It is required for exact-out, for Lightning destinations, and for deposits from BNB, native TON, Tron, XRP, Litecoin, and Zcash. Without it, Orchestra refunds to the detected source address only when that is safe, and never to an exchange’s shared sender address.

Start

Core

Flows

Security

Legacy

Prerequisites

Flow

EVM funding transactions

Deposit address by source chain

When to call /submit

Quote response

Rules

​Prerequisites

​Flow

​EVM funding transactions

​Deposit address by source chain

​When to call /submit

​Quote response

​Rules

Prerequisites

Flow

EVM funding transactions

Deposit address by source chain

When to call /submit

Quote response

Rules