> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashnet.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quotes

> Deposit-driven swaps

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](https://orchestra.flashnet.xyz/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](https://docs.flashnet.xyz/api/authentication.md).

## Flow

**1. Estimate**

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

**2. Quote**

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

```bash curl theme={null}
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"
  }'
```

```typescript TypeScript theme={null}
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();
```

> [!NOTE]
>
> 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.

```bash theme={null}
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"
  }'
```

**3. Pay**

Send `amountIn` of the source asset to `depositAddress` before `expiresAt`. Include `depositMemo` when returned. Eligible late funding for variable quotes uses refreshed pricing; some expired submissions are rejected. Late funding for fixed-output quotes is held for review. See [Pricing](https://docs.flashnet.xyz/orchestra/pricing.md).

**4. Watch**

Poll `GET /v1/orchestration/order?quoteId=QUOTE_ID` with a server key until `order` is non-null, then follow the order on [Status](https://docs.flashnet.xyz/orchestra/status.md) by webhook, SSE, or `GET /v1/orchestration/status?id=ORDER_ID`.

## Fixed-output quotes

Fixed-output quotes commit to `estimatedOut` when the full `amountIn` is funded before `expiresAt`.

Available to approved partners. Contact your Flashnet representative to request access.

Choose a destination in the source asset's `route.fixedTo` set on `/v2/orchestration/routes`, using the same partner key as the quote.

Example: `POST /v1/orchestration/quote` for 50 USDC on Base into USDC on Arbitrum:

```json theme={null}
{
  "sourceChain": "base",
  "sourceAsset": "USDC",
  "destinationChain": "arbitrum",
  "destinationAsset": "USDC",
  "amount": "50000000",
  "amountMode": "exact_in",
  "deliveryMode": "fixed",
  "recipientAddress": "RECIPIENT_ADDRESS"
}
```

Confirm `deliveryMode: "fixed"` in the response. Send `amountIn` to `depositAddress` before `expiresAt`, then track [Order status](https://docs.flashnet.xyz/orchestra/status.md). Bitcoin funding must be observed by Flashnet before expiry; confirmation can follow later.

Underpayment can reduce the payout or require review; overpayment does not increase it. Late funding is held for review. See [Pricing](https://docs.flashnet.xyz/orchestra/pricing.md) and [Errors](https://docs.flashnet.xyz/api/errors.md) for funding rules and unsupported requests.

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

```bash theme={null}
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.

> [tab] ERC-20
>
> This trimmed example transfers 50 USDC on Base to the illustrative deposit address `0x1111111111111111111111111111111111111111`. Use the transaction from your own quote.
>
> ```json theme={null}
> {
>   "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`.

> [tab] Native asset
>
> This trimmed example funds a Base ETH quote with 0.001 ETH:
>
> ```json theme={null}
> {
>   "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](https://docs.flashnet.xyz/orchestra/status.md), and use [submit](https://docs.flashnet.xyz/orchestra/quotes.md#when-to-call-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

> [tab] EVM
>
> Send the quoted token or native asset on the source chain. If detection misses, submit the transaction:
>
> ```json theme={null}
> { "quoteId": "QUOTE_ID", "txHash": "0x...", "sourceAddress": "0x..." }
> ```
>
> `sourceAddress` is optional except on shared deposit addresses, where it identifies the sender.

> [tab] Solana
>
> `depositAddress` is a Solana address. Deposits are automatically detected. If auto-detection fails, submit the transaction:
>
> ```json theme={null}
> { "quoteId": "QUOTE_ID", "txHash": "<base58 signature>", "sourceAddress": "<sender>" }
> ```

> [tab] Spark
>
> `depositAddress` is a Spark address. Deposits are detected by the Spark ingress scan. Fallback submit body:
>
> ```json theme={null}
> { "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.

> [tab] Bitcoin
>
> `depositAddress` is an L1 address. Deposits are detected over ZMQ from a Bitcoin node. Fallback submit body:
>
> ```json theme={null}
> { "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](https://docs.flashnet.xyz/orchestra/zeroconf.md).

> [tab] Lightning
>
> `depositAddress` is a BOLT11 invoice and the quote also returns `lightningReceiveRequestId`. Paying the invoice creates the order. Fallback submit body:
>
> ```json theme={null}
> { "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](https://docs.flashnet.xyz/api/overview.md#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](#evm-funding-transactions).
* `amountIn`: source amount the price is based on.
* `estimatedOut`: destination output; fixed-output quotes commit to it with timely, full funding. See [Fixed-output quotes](#fixed-output-quotes).
* `deliveryMode`: `"fixed"` when fixed delivery applies. Omitted for variable delivery.
* `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](https://docs.flashnet.xyz/orchestra/fees.md).
* `route`: path labels, which may be symbols or asset ids. Do not use them as catalog keys.
* `minAmountOut`, `fallback`: present when the destination is a token named by address. See [Any token](https://docs.flashnet.xyz/orchestra/any-token.md).
* `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`.
* `tag`: the `tag` you sent, or null. See [Tags](#tags).
* Exact-out quotes add `amountMode`, `targetAmountOut`, `requiredAmountIn`, `maxAcceptedAmountIn`, and `inputBufferBps`.
* Lightning sources add `lightningReceiveRequestId`, and `flexibleAmount: true` when the invoice has no amount.

## Tags

Set `tag` to your own reference, such as your order ID or an integrator ID, on `/quote`, `/offramp`, or `/onramp`. It is 1 to 64 letters, digits, `.`, `_`, `:`, or `-`. Other values return `400 validation_error`; `null` is the same as omitting it. Every order the quote funds carries the tag. It appears on the create response, on `/status`, `/order`, and `/history`, and as `data.tag` on every `order.*` webhook, so you can match events to your records without storing Orchestra ids.

A tag is not unique. A second deposit to a reused deposit address creates another order with the same tag, so key records on the order `id`. The tag is fixed once the quote exists: a replay with a different tag returns `409 idempotency_conflict`. Whoever holds the key that creates the quote chooses the tag, so set it from your backend.

## 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, for a source token named by address, 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.