BTC to Stablecoin

This flow starts with a BTC (or USDB) deposit and ends with USDC or another supported asset delivered to any supported chain. If you want a reusable Bitcoin address that runs this flow automatically on each deposit, use reusable addresses. Common uses:

Merchant settlement: accept BTC and deliver stablecoins to any supported chain.
Wallet sell flow: users sell BTC and receive the destination asset on their preferred chain.
Exact-out payments: deliver a precise USDC amount for invoices (Bitcoin L1 only). For exact-out BTC delivery to Lightning, see Stablecoin to BTC.

Live pairs, per-asset contract addresses, decimals, and chain ids come from GET /v1/orchestration/routes. Per-route amount bounds come from GET /v1/orchestration/limits. Never hardcode contract addresses; read them from the route entry’s source and destination detail objects.

Flow

Create a quote: POST /v1/orchestration/quote.
Initiate the source deposit to depositAddress.
Submit the deposit transaction identifier: POST /v1/orchestration/submit.
Track status via webhooks or GET /v1/orchestration/status?id=....
If status becomes awaiting_approval, a ZeroConf offer is pending (order.zeroconfOffer). Accept or decline via the zeroconf endpoints. See ZeroConf.

Quotes expire 2 minutes after creation.

Example: BTC (Spark) to USDC (Base)

const BASE_URL = 'https://orchestration.flashnet.xyz';

const quote = await fetch(`${BASE_URL}/v1/orchestration/quote`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `quote:${Date.now()}`,
  },
  body: JSON.stringify({
    sourceChain: 'spark',
    sourceAsset: 'BTC',
    destinationChain: 'base',
    destinationAsset: 'USDC',
    amount: '1000000',
    recipientAddress: '0xYourBaseUsdcAddress',
    slippageBps: 50,
  }),
}).then((r) => r.json());

// Send BTC on Spark to quote.depositAddress for quote.amountIn.
// Capture the Spark transfer id.
const sparkTransferId = await sendSparkBtc({
  toSparkAddress: quote.depositAddress,
  amountSats: quote.amountIn,
});

const submit = await fetch(`${BASE_URL}/v1/orchestration/submit`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.FLASHNET_API_KEY}`,
    'X-Idempotency-Key': `submit:${quote.quoteId}:${sparkTransferId}`,
  },
  body: JSON.stringify({
    quoteId: quote.quoteId,
    sparkTxHash: sparkTransferId,
    // Optional but recommended. When present, the deposit verifier checks the sender Spark address.
    sourceSparkAddress: 'spark1YourSenderAddress',
  }),
}).then((r) => r.json());

const status = await fetch(
  `${BASE_URL}/v1/orchestration/status?id=${encodeURIComponent(submit.orderId)}`,
).then((r) => r.json());

console.log(status.order.status);

Example: BTC (Bitcoin L1) to USDC (exact in)

A Bitcoin L1 quote returns a Bitcoin depositAddress. After you broadcast the transaction, submit the txid. The engine automatically finds the output that paid the deposit address. Quote request:

{
  "sourceChain": "bitcoin",
  "sourceAsset": "BTC",
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "amount": "250000",
  "recipientAddress": "So1...",
  "slippageBps": 50
}

Submit request:

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

bitcoinVout is optional. When omitted, the engine resolves it by scanning the transaction outputs for the one that pays the quote’s deposit address. You can still provide it explicitly for batched transactions where you want to specify a particular output.

Example: BTC (Bitcoin L1) to USDC (exact out payment intent)

Use exact-out when the destination must receive a precise USDC amount. Quote request:

{
  "sourceChain": "bitcoin",
  "sourceAsset": "BTC",
  "destinationChain": "base",
  "destinationAsset": "USDC",
  "amount": "100000000",
  "amountMode": "exact_out",
  "recipientAddress": "0xYourBaseUsdcAddress",
  "refundAddress": "bc1qyourrefundaddress...",
  "slippageBps": 0
}

Quote response adds:

targetAmountOut: requested destination amount
requiredAmountIn: minimum BTC input required
maxAcceptedAmountIn: highest BTC input auto-accepted
inputBufferBps: currently 2 when slippageBps=0, else 0

Deposit guidance:

Send requiredAmountIn for the cleanest path.
Keep actual input at or below maxAcceptedAmountIn.
If actual input is outside bounds, or target output cannot be met at current market conditions, the order refunds automatically to paymentIntent.refundAddress. The relevant errorCode will be exact_out_insufficient_input, exact_out_input_above_max, or exact_out_target_not_met. See Error codes.

Example: BTC (Spark) to USDC (Solana) with affiliate fees

{
  "sourceChain": "spark",
  "sourceAsset": "BTC",
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "amount": "100000",
  "recipientAddress": "So1RecipientAddress...",
  "appFees": [
    {
      "recipient": "So1AffiliateOne...",
      "fee": 100
    },
    {
      "recipient": "So1AffiliateTwo...",
      "fee": 50
    }
  ]
}

Example: BTC (Spark) to USDC (Solana) with affiliate registry

{
  "sourceChain": "spark",
  "sourceAsset": "BTC",
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "amount": "100000",
  "recipientAddress": "So1RecipientAddress...",
  "affiliateId": "flashpartner"
}

Affiliate fees on sell routes settle in USDC on the destination payout side. Flashnet retains a 20% platform cut; the remaining 80% goes to the fee recipient. See Fees for the full fee model and Quotes and Orders for the response fields.

Example: BTC (Spark) to USDT (Tron)

{
  "sourceChain": "spark",
  "sourceAsset": "BTC",
  "destinationChain": "tron",
  "destinationAsset": "USDT",
  "amount": "100000",
  "recipientAddress": "TYourTronAddress...",
  "slippageBps": 50
}

Delivery to other supported chains uses the same Orchestra routing. The order progresses through swap, bridge, and delivery steps.

How do deposit flexibility and ZeroConf work?

Deposits do not need to match the quoted amountIn exactly. See Deposit Amount Flexibility for how over/underpayments are handled. For Bitcoin L1 exact-in deposits, ZeroConf can offer instant credit after the transaction is detected. If no offer is generated, or if the offer is declined or expires, the order continues after 1 on-chain confirmation. Exact-out orders always use confirmation-based processing.

USDB sell flows

For USDB sell flows (USDB to stablecoin), the quote returns a per-partner derived Spark address in depositAddress. This address is deterministic for a given partner and recipient combination. The sourceSparkAddress field is not required on submit for these flows.

Example: BTC (Lightning) to USDC

Lightning-source routes use custom pricing. USDB destinations get the lowest rates. A Lightning quote returns a BOLT11 invoice in depositAddress and a lightningReceiveRequestId. Pay the invoice, then submit the receive request id. Quote response fields to pay:

depositAddress: BOLT11 invoice
amountIn: sats to pay
lightningReceiveRequestId: identifier used by submit

Submit request:

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

Overview

Concepts

Guides

Reference

Security

BTC to Stablecoin

Flow

Example: BTC (Spark) to USDC (Base)

Example: BTC (Bitcoin L1) to USDC (exact in)

Example: BTC (Bitcoin L1) to USDC (exact out payment intent)

Example: BTC (Spark) to USDC (Solana) with affiliate fees

Example: BTC (Spark) to USDC (Solana) with affiliate registry

Example: BTC (Spark) to USDT (Tron)

How do deposit flexibility and ZeroConf work?

USDB sell flows

Example: BTC (Lightning) to USDC

Next steps

​Flow

​Example: BTC (Spark) to USDC (Base)

​Example: BTC (Bitcoin L1) to USDC (exact in)

​Example: BTC (Bitcoin L1) to USDC (exact out payment intent)

​Example: BTC (Spark) to USDC (Solana) with affiliate fees

​Example: BTC (Spark) to USDC (Solana) with affiliate registry

​Example: BTC (Spark) to USDT (Tron)

​How do deposit flexibility and ZeroConf work?

​USDB sell flows

​Example: BTC (Lightning) to USDC

​Next steps

Flow

Example: BTC (Spark) to USDC (Base)

Example: BTC (Bitcoin L1) to USDC (exact in)

Example: BTC (Bitcoin L1) to USDC (exact out payment intent)

Example: BTC (Spark) to USDC (Solana) with affiliate fees

Example: BTC (Spark) to USDC (Solana) with affiliate registry

Example: BTC (Spark) to USDT (Tron)

How do deposit flexibility and ZeroConf work?

USDB sell flows

Example: BTC (Lightning) to USDC

Next steps