Quotes and Orders

For authentication, error codes, and request conventions, see API Overview.

GET /v1/orchestration/routes

List all supported trading pairs. No authentication required.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/routes"

Response:

{
  "routes": [
    {
      "sourceChain": "base",
      "sourceAsset": "USDC",
      "destinationChain": "spark",
      "destinationAsset": "BTC",
      "exactOutEligible": false,
      "fixedEligible": true,
      "source": {
        "chain": "base",
        "asset": "USDC",
        "chainDisplayName": "Base",
        "chainIcon": "/chain-base.svg",
        "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "decimals": 6,
        "chainId": "8453"
      },
      "destination": {
        "chain": "spark",
        "asset": "BTC",
        "chainDisplayName": "Spark",
        "chainIcon": "/chain-spark.svg",
        "contractAddress": null,
        "decimals": 8,
        "chainId": null
      }
    },
    {
      "sourceChain": "spark",
      "sourceAsset": "BTC",
      "destinationChain": "base",
      "destinationAsset": "USDC",
      "exactOutEligible": false,
      "fixedEligible": true,
      "source": {
        "chain": "spark",
        "asset": "BTC",
        "chainDisplayName": "Spark",
        "chainIcon": "/chain-spark.svg",
        "contractAddress": null,
        "decimals": 8,
        "chainId": null
      },
      "destination": {
        "chain": "base",
        "asset": "USDC",
        "chainDisplayName": "Base",
        "chainIcon": "/chain-base.svg",
        "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "decimals": 6,
        "chainId": "8453"
      }
    }
  ]
}

Each entry is a valid (sourceChain, sourceAsset) -> (destinationChain, destinationAsset) pair that can be used with /estimate, /quote, and /submit. The list is derived from the pipeline route resolver and stays in sync automatically as new pairs are added. It covers both the canonical BTC/USDB routes and the cross-chain (non-BTC) planner routes, sorted BTC-zone first; cross-chain pairs are exact-in only and never fixed-eligible. Each route carries two eligibility booleans: exactOutEligible (the pair accepts amountMode=exact_out) and fixedEligible (the pair can support deliveryMode=fixed, subject to per-partner configuration; see Fixed delivery). Each route includes source and destination detail objects:

Field	Type	Notes
`chain`	`string`	Chain identifier
`asset`	`string`	Asset symbol
`chainDisplayName`	`string`	Human-readable chain name (e.g. `"Base"`, `"Spark"`)
`chainIcon`	`string \| null`	Chain icon path (e.g. `"/chain-base.svg"`), relative to the API host
`contractAddress`	`string \| null`	Token contract address (EVM, checksummed), mint address (Solana), or token ID (Spark USDB). `null` for native assets (BTC, ETH, SOL, etc.).
`decimals`	`number`	Smallest-unit decimals for the asset (e.g. 6 for USDC, 8 for BTC)
`chainId`	`string \| null`	Chain ID as a string. Numeric for EVM chains (e.g. `"8453"`), CAIP-2 for Solana (`"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"`). `null` for spark, bitcoin, and lightning.

GET /v1/orchestration/limits

Amount limits per route. Call this before quoting to pre-validate amounts instead of hardcoding bounds in your integration. No authentication required; rate limited to 60 requests per minute per IP. /limits covers the canonical routes. Cross-chain planner routes appear on /routes but not on /limits today.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/limits?sourceChain=bitcoin&sourceAsset=BTC&destinationChain=solana&destinationAsset=USDC"

Query parameters (all optional, each narrows the returned list):

Param	Notes
`sourceChain`	Filter by source chain
`sourceAsset`	Filter by source asset
`destinationChain`	Filter by destination chain
`destinationAsset`	Filter by destination asset

The response is { generatedAt, routes: [...] }. Each entry extends the /routes pair shape with direction ("buy" or "sell") and a limits object. Response (filtered to bitcoin:BTC -> solana:USDC):

{
  "generatedAt": "2026-07-13T12:00:00.000Z",
  "routes": [
    {
      "sourceChain": "bitcoin",
      "sourceAsset": "BTC",
      "destinationChain": "solana",
      "destinationAsset": "USDC",
      "direction": "sell",
      "exactOutEligible": true,
      "fixedEligible": true,
      "source": {
        "chain": "bitcoin",
        "asset": "BTC",
        "chainDisplayName": "Bitcoin",
        "chainIcon": "/btc.svg",
        "contractAddress": null,
        "decimals": 8,
        "chainId": null
      },
      "destination": {
        "chain": "solana",
        "asset": "USDC",
        "chainDisplayName": "Solana",
        "chainIcon": "/chain-solana.svg",
        "contractAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "decimals": 6,
        "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
      },
      "limits": {
        "orderNotionalUsd": {
          "minCents": "80",
          "maxCents": "2000000",
          "source": "runtime_order_bounds"
        },
        "exactIn": {
          "supported": true,
          "requestAmount": {
            "leg": "source",
            "chain": "bitcoin",
            "asset": "BTC",
            "minAmountSmallest": "5149",
            "maxAmountSmallest": null,
            "minUsdCents": "80",
            "maxUsdCents": "2000000"
          },
          "constraints": ["order_notional_usd", "flashnet_btc_swap_input_min"]
        },
        "exactOut": {
          "supported": true,
          "requestAmount": {
            "leg": "destination",
            "chain": "solana",
            "asset": "USDC",
            "minAmountSmallest": null,
            "maxAmountSmallest": null,
            "minUsdCents": "80",
            "maxUsdCents": "2000000"
          },
          "constraints": ["order_notional_usd"]
        },
        "fiatUsd": null,
        "dynamicProviderLimits": {
          "possible": false,
          "components": [],
          "description": null
        },
        "constraints": [
          {
            "id": "order_notional_usd",
            "amountMode": "all",
            "leg": "route",
            "source": "runtime_order_bounds",
            "description": "Runtime USD notional bounds apply to estimate, quote, submit, and onramp when the route amount can be priced.",
            "chain": null,
            "asset": null,
            "minAmountSmallest": null,
            "maxAmountSmallest": null,
            "minUsdCents": "80",
            "maxUsdCents": "2000000"
          },
          {
            "id": "flashnet_btc_swap_input_min",
            "amountMode": "exact_in",
            "leg": "source",
            "source": "flashnet_static_limit",
            "description": "Bitcoin L1 source quotes must leave at least 5000 sats after the static deposit fee.",
            "chain": "bitcoin",
            "asset": "BTC",
            "minAmountSmallest": "5149",
            "maxAmountSmallest": null,
            "minUsdCents": null,
            "maxUsdCents": null
          }
        ]
      }
    }
  ]
}

Field notes:

orderNotionalUsd is the operator-tuned USD notional bound for the route’s direction (source: "runtime_order_bounds"). Treat this endpoint as authoritative; the values change without notice.
exactIn and exactOut each report supported, a requestAmount range for the amount you would send in that mode (source leg for exact-in, destination leg for exact-out), and the IDs of the constraints entries that apply to that mode.
fiatUsd reports the amountFiatUsd band ( $1.00 to$ 50,000.00) and the surfaces that accept it (onramp, pay_link). It is non-null only on lightning:BTC source routes.
dynamicProviderLimits flags routes where provider-backed legs (components) impose additional quote-time limits. A live /estimate or /quote can still return amount_too_small, amount_too_large, amount_exceeds_liquidity, or route_unavailable on these routes even when the static bounds pass.
constraints is a typed list of every limit on the route. source values: runtime_order_bounds, flashnet_static_limit, bitcoin_l1_delivery, provider_quote, fiat_amount. The sample above shows one static limit; read the live values from this endpoint instead of hardcoding them.

GET /v1/orchestration/estimate

Lightweight price preview. This does not create a quote and does not create a durable order. Use /estimate for price display and browsing: it is public, stateless, allocates no deposit address, and is safe to call on every input change within its 120 requests per minute per IP limit. Use /quote only when the user has committed to the swap: it is authenticated and idempotent, persists the quote, allocates a deposit address, and starts a 2 minute expiry. /estimate requires no API key. Client keys (fnp_) cannot pass the fee fields (appFees, affiliateId, affiliateIds) on this endpoint.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/estimate?sourceChain=base&sourceAsset=USDC&destinationChain=spark&destinationAsset=BTC&amount=100000000"

Query parameters:

Param	Required	Notes
`sourceChain`	Yes	One of the supported chains
`sourceAsset`	Yes	One of the supported assets
`destinationChain`	Yes	One of the supported chains
`destinationAsset`	Yes	One of the supported assets
`amount`	Yes	Integer string. With `amountMode=exact_out`, this is the destination amount. Stablecoin exact-out amounts must be whole-cent values.
`amountMode`	No	`"exact_in"` (default) or `"exact_out"`
`deliveryMode`	No	`"variable"` (default) or `"fixed"`. See Fixed delivery.
`slippageBps`	No	Preview slippage. Defaults to `100` when omitted.
`appFees`	No	JSON-encoded array of `{recipient, fee}`. Same shape as the `/quote` body field.
`affiliateId`	No	Registered affiliate ID (single). Requires `Authorization` header.
`affiliateIds`	No	Registered affiliate IDs. Accepts either a comma-separated list (`a,b,c`) for the plain-string form, or a JSON-encoded array (`[...]`) when you need the `{affiliateId, feeBps}` override form. Requires `Authorization` header.

Authentication is optional. When an Authorization header is provided, affiliateId and affiliateIds are resolved against partner-scoped affiliate profiles. Response:

{
  "estimatedOut": "string",
  "feeAmount": "string",
  "feeBps": 5,
  "totalFeeAmount": "string",
  "feeAsset": "USDC",
  "route": ["USDC", "USDB", "BTC"],
  "source": {
    "chain": "base",
    "asset": "USDC",
    "chainDisplayName": "Base",
    "chainIcon": "/chain-base.svg",
    "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "decimals": 6,
    "chainId": "8453"
  },
  "destination": {
    "chain": "spark",
    "asset": "BTC",
    "chainDisplayName": "Spark",
    "chainIcon": "/chain-spark.svg",
    "contractAddress": null,
    "decimals": 8,
    "chainId": null
  }
}

Three field groups are conditional:

roundingFeeAmount appears only when nonzero.
deliveryMode appears only when fixed delivery applies (see Fixed delivery).
appFeeAmount, appFeePlatformCutAmount, and appFees appear only when appFees, affiliateId, or affiliateIds was provided:

{
  "estimatedOut": "string",
  "feeAmount": "string",
  "feeBps": 5,
  "totalFeeAmount": "string",
  "appFeeAmount": "string",
  "appFeePlatformCutAmount": "string",
  "appFees": [
    {
      "recipient": "So1AffiliateOne...",
      "feeBps": 100,
      "amount": "string",
      "platformCutAmount": "string",
      "recipientAmount": "string"
    }
  ],
  "feeAsset": "USDC",
  "route": ["USDC", "USDB", "BTC"],
  "source": { "chain": "base", "asset": "USDC", "chainDisplayName": "Base", "chainIcon": "/chain-base.svg", "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "decimals": 6, "chainId": "8453" },
  "destination": { "chain": "spark", "asset": "BTC", "chainDisplayName": "Spark", "chainIcon": "/chain-spark.svg", "contractAddress": null, "decimals": 8, "chainId": null }
}

feeAsset is USDC for most routes, USDB for BTC -> USDB, and BTC for direct Lightning passthrough routes such as lightning:BTC -> spark:BTC.
totalFeeAmount equals feeAmount + roundingFeeAmount + appFeeAmount. Estimate totals never include sweep fees; those appear only on /quote.
estimatedOut reflects the final amount after all fees (platform + app) are deducted.
roundingFeeAmount is stablecoin surplus retained when output is capped to a whole-cent or exact-out target. It appears only when nonzero.
For partner invoice billing, feeAmount can be "0" because the platform fee is billed after settlement instead of deducted from the transaction. Fees owed are visible through GET /v1/partner/dashboard/fee-invoices.
App fees follow the same deduction order as /quote: platform fee first, then app fees, before the swap (buy direction) or after the swap (sell direction).
Fee plans follow the same route scope as /quote: any route with a supported fee settlement. Routes with no resolvable settlement (pure BTC-to-BTC, feeAsset BTC) return 400 unsupported_fee_plan.
The same validation rules apply as /quote: appFees and affiliateId/affiliateIds are mutually exclusive, max 16 entries, sum of bps must be <= 10000.

POST /v1/orchestration/quote

Request a durable quote with deposit instructions. Quotes expire 2 minutes after creation.

/quote is the execution step, not the browsing step. Price with /estimate while the user is deciding; call /quote once, when they commit. Every /quote call persists a quote and allocates a deposit address.

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

Request fields

Field	Type	Required	Notes
`sourceChain`	`Chain`	Yes	Source chain identifier
`sourceAsset`	`Asset`	Yes	Source asset symbol
`destinationChain`	`Chain`	Yes	Destination chain identifier
`destinationAsset`	`Asset`	Yes	Destination asset symbol
`amount`	`string`	Yes	Integer string in smallest units. With `amountMode=exact_out`, this is the destination amount. Stablecoin exact-out amounts must be whole-cent values, for example multiples of `10000` for 6-decimal USDC/USDB.
`recipientAddress`	`string`	Yes	Address on the destination chain. BOLT11 invoice when `destinationChain=lightning`.
`amountMode`	`string`	No	`"exact_in"` (default) or `"exact_out"`. `exact_out` is supported on routes with `exactOutEligible: true` on `/routes` (for example `bitcoin:BTC -> base:USDC`).
`refundAddress`	`string`	Conditional	Required when `amountMode=exact_out` or `destinationChain=lightning`.
`refundChain`	`Chain`	No	Refund chain. When provided without `refundAddress`, the request is rejected.
`deliveryMode`	`string`	No	`"variable"` (default) or `"fixed"`. See Fixed delivery.
`slippageBps`	`number`	No	`0` to `1000`. Default `50` for most routes, `200` for NEAR-ingress sources. On routes that swap through the Flashnet AMM, a runtime floor (default 10 bps, operator-tunable) applies; a below-floor value returns `400 invalid_request`.
`appFees`	`AppFee[]`	No	Inline fee recipients. Each entry: `{ recipient: string, fee: number }`. Max 16 entries. Mutually exclusive with `affiliateId`/`affiliateIds`.
`affiliateId`	`string`	No	Single registered affiliate ID. Requires `Authorization`. Mutually exclusive with `appFees`.
`affiliateIds`	`AffiliateRef[]`	No	Multiple affiliate IDs. Each entry is a plain string or `{ affiliateId: string, feeBps: number }`. Max 16 entries. Requires `Authorization`. Mutually exclusive with `appFees`.

Fixed delivery (deliveryMode)

deliveryMode accepts "variable" (default) or "fixed". Fixed delivery makes the quoted estimatedOut a delivery commitment rather than an estimate: the order delivers the quoted amount.

Requires amountMode=exact_in. Any other mode returns 400 unsupported_delivery_mode.
Only routes with fixedEligible: true on /routes support it, and availability additionally depends on per-partner operator configuration. Cross-chain routes never support it.
When fixed delivery does not apply, /quote and /estimate reject with fixed_delivery_unavailable (the error message states the reason), while /onramp silently proceeds as a normal variable onramp.
The response echoes deliveryMode: "fixed" only when fixed delivery applies. Treat its absence as a variable quote.

/estimate and /onramp accept the same field with the same semantics. Exact-out payment-intent example (bitcoin:BTC -> base:USDC):

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

Exact-out Lightning example (any buy-side source -> lightning:BTC):

{
  "sourceChain": "base",
  "sourceAsset": "USDC",
  "destinationChain": "lightning",
  "destinationAsset": "BTC",
  "amount": "100000",
  "amountMode": "exact_out",
  "recipientAddress": "lnbc1u1...",
  "refundAddress": "0xYourBaseUsdcRefundAddress",
  "slippageBps": 0
}

Exact-in affiliate-fee example (spark:BTC -> solana:USDC):

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

Exact-in affiliate-registry example (spark:BTC -> solana:USDC):

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

Exact-in with multiple affiliates (spark:BTC -> solana:USDC):

{
  "sourceChain": "spark",
  "sourceAsset": "BTC",
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "amount": "100000",
  "recipientAddress": "So1RecipientAddress...",
  "affiliateIds": ["referrer-alice", "platform-fee"]
}

Exact-in with per-quote feeBps override (spark:BTC -> solana:USDC):

{
  "sourceChain": "spark",
  "sourceAsset": "BTC",
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "amount": "100000",
  "recipientAddress": "So1RecipientAddress...",
  "affiliateIds": [
    "referrer-alice",
    { "affiliateId": "platform-fee", "feeBps": 25 }
  ]
}

Entries in affiliateIds can be either plain strings or { affiliateId, feeBps } objects. String entries resolve fee bps from the affiliate’s registered profile. Object entries override the profile’s fee bps for that quote only, without mutating the stored profile. Both forms can be mixed in the same request. Exact-in source-side affiliate-fee example (solana:SOL -> spark:BTC):

{
  "sourceChain": "solana",
  "sourceAsset": "SOL",
  "destinationChain": "spark",
  "destinationAsset": "BTC",
  "amount": "100000000",
  "recipientAddress": "spark1...",
  "appFees": [
    {
      "recipient": "Dtkxt55zEUDj6NTXGRtH8uQsACsTjoSVkXfYBEF8xkkT",
      "fee": 100
    }
  ]
}

Notes:

amountMode defaults to exact_in.
amountMode=exact_out is supported on routes with exactOutEligible: true on /routes.
Stablecoin exact-out amounts must be whole-cent values. A non-cent value returns 400 invalid_request.
refundAddress is required when amountMode=exact_out.
If Authorization is included, send X-Idempotency-Key.
appFees, affiliateId, and affiliateIds are accepted in both amount modes on any route with a supported fee settlement (see the settlement resolution rules under “Affiliate fee models” below). Routes with no resolvable settlement, meaning pure BTC-to-BTC routes such as lightning:BTC -> bitcoin:BTC, reject fee plans with 400 unsupported_fee_plan (“appFees require a route with supported fee settlement”).
appFees max length is 16.
Each appFees[i].fee is fee bps (1..10000).
Sum of all app fee bps must be <= 10000.
affiliateId and affiliateIds must match ^[a-z0-9][a-z0-9_-]{0,63}$ after trimming and lowercasing.
Use either appFees or affiliateId/affiliateIds, not both; sending both returns 400 invalid_request. affiliateId and affiliateIds can both be provided; they are merged (with affiliateId treated as a single-element list).
affiliateIds accepts up to 16 entries per quote. Each entry is either a plain affiliate ID (fee bps comes from the registered profile) or an object { affiliateId, feeBps } that overrides the profile’s fee bps for that quote only. The sum of all effective affiliate fee BPS must be <= 10000.
affiliateId and affiliateIds require authenticated quote requests.
slippageBps defaults to 50 when omitted (200 for NEAR-ingress sources).
ZeroConf offers are not quote response fields. For eligible Bitcoin L1 exact-in orders, a zeroconfOffer may appear on the order after the Bitcoin transaction is detected.
For destinationChain = lightning, recipientAddress must be a BOLT11 invoice. In exact_in mode, the invoice must be amountless (0-amount). In exact_out mode, the invoice can be amountless or encode an amount matching the requested amount in sats.

Affiliate fee models:

Inline recipients:
- appFees: [{ recipient: string, fee: number }]
- fee is fee bps per recipient (1..10000).
Registry by id (single):
- affiliateId: string
- profile is managed through PUT /v1/affiliates/:affiliateId
- quote resolves recipient + fee bps from your partner-scoped profile
Registry by ids (multiple):
- affiliateIds: Array<string | { affiliateId: string, feeBps: number }>
- string entries resolve recipient and fee bps from the registered profile
- object entries resolve recipient from the registered profile but use the per-quote feeBps override instead of the profile’s bps; the stored profile is not mutated
- fees from all affiliates are applied to the order; each affiliate accumulates their share independently and claims separately
Settlement chain and asset are determined by the route via resolveFeeSettlement:
- Settles on solana:USDC when either side is Solana, an EVM/relay chain, or a provider-bridged destination such as TON.
- Settles on spark:USDB when either side is spark:USDB and no chain from the solana:USDC rule is involved.
- Pure BTC-to-BTC routes (e.g. lightning:BTC -> bitcoin:BTC) have no resolvable settlement and reject fee plans with 400 unsupported_fee_plan.
Execution point:
- If the source chain matches the settlement chain (e.g. solana source on solana:USDC settlement), fees are deducted on the source-side stablecoin leg before bridge/swap continuation.
- If the source chain does not match the settlement chain, fees are deducted on whichever stablecoin leg the route exposes: typically the destination-side USDC payout leg for sells, or the bridge leg for supported chain payouts.
For source-native routes like SOL -> BTC and ETH -> BTC, fees are deducted on the stablecoin leg after ingress conversion (SOL|ETH -> USDC).
Quote math order:
- platform fee (feeAmount)
- optional sweep fee (sweepFeeAmount, USDC-source routes only)
- app fee allocation (appFeeAmount, appFees)
- 20% platform cut retained from each app fee (appFeePlatformCutAmount); remaining 80% goes to the fee recipient
- net amount proceeds to route execution
Flashnet retains 20% of each app/affiliate fee. The quote response shows the split per recipient: amount (gross fee charged to the user), platformCutAmount (20% retained by Flashnet), and recipientAmount (80% paid to the fee recipient).
appFees recipients are validated against the settlement-chain address format.
For affiliateId and affiliateIds, the affiliate profile must have a payoutAddress configured (set via PUT /v1/affiliates/:affiliateId). The payout chain/asset can be any destination supported by the live route table, not just base or solana.

Response (exact-out sample):

{
  "quoteId": "q_...",
  "depositAddress": "bc1q...",
  "amountIn": "250000",
  "estimatedOut": "100000000",
  "feeAmount": "100000",
  "totalFeeAmount": "100000",
  "feeAsset": "USDC",
  "feeBps": 5,
  "route": ["BTC", "USDB", "USDC"],
  "expiresAt": "2026-02-04T02:00:00.000Z",
  "amountMode": "exact_out",
  "targetAmountOut": "100000000",
  "requiredAmountIn": "250000",
  "maxAcceptedAmountIn": "250050",
  "inputBufferBps": 2
}

Response (exact-in with appFees sample):

{
  "quoteId": "q_...",
  "depositAddress": "spark1...",
  "amountIn": "100000",
  "estimatedOut": "24825000",
  "feeAmount": "25000",
  "totalFeeAmount": "62125",
  "appFeeAmount": "37125",
  "appFeePlatformCutAmount": "7425",
  "appFees": [
    {
      "affiliateId": "flashpartner",
      "recipient": "So1AffiliateOne...",
      "feeBps": 50,
      "amount": "24750",
      "platformCutAmount": "4950",
      "recipientAmount": "19800"
    },
    {
      "recipient": "So1AffiliateTwo...",
      "feeBps": 50,
      "amount": "12375",
      "platformCutAmount": "2475",
      "recipientAmount": "9900"
    }
  ],
  "feeAsset": "USDC",
  "feeBps": 5,
  "route": ["BTC", "USDB", "USDC"],
  "expiresAt": "2026-02-04T02:00:00.000Z"
}

Response (exact-in source-side appFees sample):

{
  "quoteId": "q_...",
  "depositAddress": "So1DepositAddress...",
  "amountIn": "100000000",
  "estimatedOut": "11643",
  "feeAmount": "7893",
  "totalFeeAmount": "86749",
  "appFeeAmount": "78856",
  "appFeePlatformCutAmount": "15771",
  "appFees": [
    {
      "recipient": "Dtkxt55zEUDj6NTXGRtH8uQsACsTjoSVkXfYBEF8xkkT",
      "feeBps": 50,
      "amount": "78856",
      "platformCutAmount": "15771",
      "recipientAmount": "63085"
    }
  ],
  "feeAsset": "USDC",
  "feeBps": 5,
  "route": ["SOL", "USDC", "USDB", "BTC"],
  "expiresAt": "2026-02-11T23:55:36.296Z"
}

Field notes:

depositAddress depends on sourceChain:
- EVM and Solana sources: chain address that receives the source asset
- spark: Spark address that receives BTC or USDB
- bitcoin: Bitcoin L1 address
- lightning: BOLT11 invoice to pay
totalFeeAmount equals feeAmount + roundingFeeAmount + appFeeAmount + sweepFeeAmount. roundingFeeAmount and sweepFeeAmount appear in the response only when nonzero.
sweepFeeAmount is returned on some USDC-source routes when a sweep fee is configured.
roundingFeeAmount is returned when stablecoin surplus is retained instead of delivered.
appFeeAmount and appFees are returned when appFees or affiliateId was requested.
appFeePlatformCutAmount is the sum of Flashnet’s 20% cut across all app fees.
appFees[*].amount is the gross fee in settlement-chain USDC smallest units (what the user pays).
appFees[*].platformCutAmount is Flashnet’s 20% cut of that fee.
appFees[*].recipientAmount is the 80% paid to the fee recipient.
appFees[*].affiliateId is present when the quote used affiliateId.
lightningReceiveRequestId is only present for sourceChain = lightning quotes.
feeAsset is USDB for BTC -> USDB quotes, BTC for direct Lightning passthrough quotes, and USDC otherwise.
targetAmountOut, requiredAmountIn, maxAcceptedAmountIn, and inputBufferBps are present for exact-out quotes.
inputBufferBps is currently 2 when slippageBps=0, otherwise 0.

POST /v1/orchestration/submit

Create an order from a quote after you have initiated the source deposit.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/submit" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: submit:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "q_...",
    "txHash": "0x..."
  }'

Request fields

Field	Type	Required	Notes
`quoteId`	`string`	Yes	Quote ID (`q_...`)
`txHash`	`string`	Conditional	Required for EVM and Solana sources. Format varies by chain (EVM: `0x`-prefixed 64-char hex; Solana: base58 signature).
`sourceAddress`	`string`	No	Sender address for EVM and Solana sources. Required when depositing to a shared address.
`sparkTxHash`	`string`	Conditional	Required for `sourceChain=spark`. UUID, 32-char hex, or 64-char token tx hash.
`sourceSparkAddress`	`string`	No	Sender Spark address. Required when depositing to a shared Spark address.
`bitcoinTxid`	`string`	Conditional	Required for `sourceChain=bitcoin`. 64-character hex transaction ID.
`bitcoinVout`	`number`	No	Output index. Auto-resolved from transaction outputs when omitted.
`lightningReceiveRequestId`	`string`	No	For `sourceChain=lightning`. Auto-populated from quote when omitted.

The request body shape depends on sourceChain. Each source chain uses a different subset of these fields. See the examples below. Headers:

Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>

Request body shape depends on the quote sourceChain. Base/Solana sources (sourceChain = base|solana):

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

sourceAddress is optional but recommended. It is required when depositing to a shared address. When present, deposit verification requires the sender to match. Spark sources (sourceChain = spark):

{
  "quoteId": "q_...",
  "sparkTxHash": "spark_transfer_id_or_token_tx_hash",
  "sourceSparkAddress": "spark1..."
}

sourceSparkAddress is optional but recommended. It is required when depositing to a shared Spark address. When present, deposit verification requires the sender to match. Bitcoin L1 sources (sourceChain = bitcoin):

{
  "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 if needed. Lightning sources (sourceChain = lightning):

{
  "quoteId": "q_...",
  "lightningReceiveRequestId": "string"
}

lightningReceiveRequestId can be omitted. When omitted, the API uses the value embedded in the quote. The txHash field is validated per source chain:

EVM chains: 0x-prefixed 64-character hex string
Solana: Base58-encoded signature (64-90 characters)
Bitcoin: 64-character hex transaction ID
Spark: UUID format, 32-character hex, or 64-character token transaction hash
Lightning: Automatically populated from the quote’s receive request ID

Response:

{
  "orderId": "ord_...",
  "status": "processing"
}

If an order already exists for the same (sourceChain, sourceTxHash[, sourceTxVout]), submit returns the existing { orderId, status }.

POST /v1/orchestration/onramp

Combined quote and submit for Lightning sell flows. Creates a Lightning invoice and order in a single call. Designed for fiat onramp integrations where the user pays via a Lightning-compatible app. The source is always lightning:BTC. Supported destinations are the lightning:BTC source pairs on GET /v1/orchestration/routes. The amount field is BTC in sats.

curl -sS -X POST "https://orchestration.flashnet.xyz/v1/orchestration/onramp" \
  -H "Authorization: Bearer fn_..." \
  -H "X-Idempotency-Key: onramp:$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "spark",
    "destinationAsset": "USDB",
    "recipientAddress": "spark1...",
    "amount": "100000"
  }'

Headers:

Authorization: Bearer fn_...
X-Idempotency-Key: <unique key>

Request fields

Field	Type	Required	Notes
`destinationChain`	`Chain`	Yes	Target chain
`destinationAsset`	`Asset`	Yes	Target asset
`recipientAddress`	`string`	Yes	Address on the destination chain
`amount`	`string`	Yes	Integer string. With `exact_in`, BTC in sats. With `exact_out`, the destination amount in smallest units. Stablecoin exact-out amounts must be whole-cent values.
`amountMode`	`string`	No	`"exact_in"` (default) or `"exact_out"`. `exact_out` requires the pair to have `exactOutEligible: true` on `/routes`; the direct BTC passthrough destinations do not.
`slippageBps`	`number`	No	Minimum, maximum, and default `1000` (10%). Values below 1000 are clamped up, so the effective value is always 1000.
`deliveryMode`	`string`	No	`"variable"` (default) or `"fixed"`. When fixed delivery does not apply, the onramp proceeds as a normal variable onramp. See Fixed delivery.
`appFees`	`AppFee[]`	No	Inline fee recipients. Not supported on direct BTC passthrough routes.
`affiliateId`	`string`	No	Registered affiliate ID (single). Requires stablecoin settlement path.
`affiliateIds`	`AffiliateRef[]`	No	Registered affiliate IDs (multiple, max 16). Requires stablecoin settlement path.

Request body:

{
  "destinationChain": "solana",
  "destinationAsset": "USDC",
  "recipientAddress": "So1...",
  "amount": "100000",
  "slippageBps": 50
}

Notes:

amountMode=exact_out is supported where the lightning:BTC pair has exactOutEligible: true on /routes. The direct BTC passthrough destinations do not support it.
Stablecoin exact-out amounts must be whole-cent values. For 6-decimal stables, send multiples of 10000, for example "50000000" for $50.00.
Affiliate fees require a stablecoin settlement path and are not supported on the direct BTC passthrough routes.

Response:

{
  "orderId": "ord_...",
  "quoteId": "q_...",
  "depositAddress": "lnbc1000n1pj...",
  "paymentLinks": {
    "cashApp": "https://cash.app/launch/lightning/lnbc1000n1pj...",
    "shortUrl": "https://orchestration.flashnet.xyz/pay/a3xKm2Rq"
  },
  "amountIn": "100000",
  "estimatedOut": "96543210",
  "feeAmount": "38536",
  "feeBps": 40,
  "totalFeeAmount": "38536",
  "feeAsset": "USDC",
  "route": ["BTC", "USDB", "USDC"],
  "expiresAt": "2026-01-15T12:04:00.000Z"
}

The paymentLinks.cashApp URL is a deeplink that opens a Lightning-compatible payment app to pay the invoice. On mobile, redirect the user to this URL. On desktop, display it as a QR code. paymentLinks.shortUrl is a short redirect URL that 302s to the payment deeplink. Use this when sharing payment links in text messages, emails, or other contexts where the full URL is too long. The short URL is always present when PUBLIC_BASE_URL is configured on the server. The Lightning invoice expires at expiresAt: 24 hours from creation for exact-in, 5 minutes for exact-out and for fixed-delivery exact-in. If the user doesn’t pay in time, create a new onramp order. Field notes:

feeBps reflects the platform fee rate for the specific route.
feeAsset is BTC for the direct BTC passthrough routes, USDB for lightning:BTC -> spark:USDB, and the destination-side stable asset for most other routes.
route is the asset path, not the pipeline step list.
For lightning:BTC -> bitcoin:BTC, the final on-chain withdrawal also pays the network withdrawal fee quoted at delivery time. That fee is separate from Flashnet’s platform fee.

For the full integration guide with code examples, see Fiat Onramp.

GET /v1/orchestration/order

Look up a quote and its associated order by quote ID. Designed for submissionless flows where partners poll after creating a quote and directing a user to deposit. Returns the quote state alongside the order. When no order exists yet (deposit not detected), order is null and the quote’s expired field indicates whether the deposit window is still open.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/order?quoteId=q_..." \
  -H "Authorization: Bearer fn_..."

Headers:

Authorization: Bearer fn_...

Query parameters:

Param	Required	Notes
`quoteId`	Yes	Quote id (`q_...`)

Response when no order exists yet:

{
  "quote": {
    "id": "q_...",
    "kind": "sell",
    "sourceChain": "spark",
    "sourceAsset": "BTC",
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "amountIn": "100000",
    "estimatedOut": "96500000",
    "feeBps": 5,
    "feeAmount": "4830",
    "depositAddress": "spark1...",
    "recipientAddress": "So1...",
    "slippageBps": 50,
    "expiresAt": "2026-02-04T02:00:00.000Z",
    "expired": false,
    "createdAt": "2026-02-04T01:58:00.000Z"
  },
  "order": null,
  "stages": []
}

Response when an order has been created:

{
  "quote": {
    "id": "q_...",
    "kind": "sell",
    "sourceChain": "spark",
    "sourceAsset": "BTC",
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "amountIn": "100000",
    "estimatedOut": "96500000",
    "feeBps": 5,
    "feeAmount": "4830",
    "depositAddress": "spark1...",
    "recipientAddress": "So1...",
    "slippageBps": 50,
    "expiresAt": "2026-02-04T02:00:00.000Z",
    "expired": true,
    "createdAt": "2026-02-04T01:58:00.000Z"
  },
  "order": {
    "id": "ord_...",
    "type": "order",
    "status": "swapping",
    "quoteId": "q_...",
    "sourceChain": "spark",
    "sourceAsset": "BTC",
    "destinationChain": "solana",
    "destinationAsset": "USDC",
    "recipientAddress": "So1...",
    "amountIn": "100000",
    "amountOut": null,
    "feeBps": 5,
    "feeAmount": "4830",
    "createdAt": "2026-02-04T02:01:00.000Z"
  },
  "stages": [
    {
      "name": "deposit_confirmed",
      "status": "completed",
      "completedAt": "2026-02-04T02:01:05.000Z"
    }
  ]
}

The order object uses the same shape as GET /v1/orchestration/status, including optional swap, paymentIntent, zeroconfOffer, feePlan, and feePayouts metadata when present. Polling pattern for submissionless flows:

Create a quote via POST /v1/orchestration/quote.
Direct the user to deposit to depositAddress.
Poll GET /v1/orchestration/order?quoteId=q_... until order is non-null.
Once order appears, continue polling or switch to webhooks to track execution.

When quote.expired is true and order is still null, no deposit has been detected yet. Expired quotes that receive a late deposit are always repriced at the live market rate at detection time and create an order; execution is still bounded by the quote’s slippageBps.

GET /v1/orchestration/status

Check an order’s current state. Authentication is optional:

Without Authorization: returns a redacted order record.
With Authorization: returns the full order record for your partner only.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/status?id=ord_..." \
  -H "Authorization: Bearer fn_..."

Provide exactly one query parameter:

Param	Notes
`id`	Order id (`ord_...`)
`quoteId`	Quote id (`q_...`)
`txHash`	Source transaction identifier (see `order.sourceTxHash`)

txHash lookup returns the most recently created order with that sourceTxHash. For Bitcoin L1 deposits where multiple orders can share the same txid, prefer id from webhooks for exact attribution. Possible order.status values:

processing
confirming
bridging
swapping
awaiting_approval
refunding
delivering
completed
failed
expired
unfulfilled
refunded

Internal paused orders are returned as processing on partner-visible status responses. Response (authenticated):

{
  "order": {
    "id": "ord_...",
    "type": "order",
    "status": "refunding",
    "quoteId": "q_...",
    "sourceChain": "bitcoin",
    "sourceAsset": "BTC",
    "sourceAddress": null,
    "sourceTxHash": "<txid>",
    "sourceTxVout": 0,
    "depositAddress": "bc1q...",
    "destinationChain": "base",
    "destinationAsset": "USDC",
    "recipientAddress": "0x...",
    "amountIn": "250000",
    "amountOut": null,
    "feeBps": 5,
    "feeAmount": "100000",
    "slippageBps": 50,
    "errorCode": "slippage_exceeded",
    "errorMessage": "Pool moved past slippage tolerance between deposit and execution",
    "createdAt": "2026-02-04T01:30:00.000Z",
    "updatedAt": "2026-02-04T01:30:10.000Z",
    "completedAt": null,
    "paymentIntent": {
      "version": 1,
      "amountMode": "exact_out",
      "targetAmountOut": "100000000",
      "requiredAmountIn": "250000",
      "maxAcceptedAmountIn": "250050",
      "inputBufferBps": 2,
      "actualAmountIn": "249900",
      "refundAddress": "bc1q...",
      "exactOutExecution": "strict"
    },
    "feePlan": {
      "version": 1,
      "settlementChain": "solana",
      "settlementAsset": "USDC",
      "appFees": [
        {
          "affiliateId": "flashpartner",
          "recipient": "So1AffiliateOne...",
          "feeBps": 50
        },
        {
          "recipient": "So1AffiliateTwo...",
          "feeBps": 50
        }
      ]
    },
    "feePayouts": {
      "version": 1,
      "entries": [
        {
          "idempotencyKey": "order:ord_...:full:appfee:0",
          "leg": "full",
          "chain": "solana",
          "role": "app_fee",
          "affiliateId": "flashpartner",
          "recipient": "So1AffiliateOne...",
          "feeBps": 50,
          "amount": "24750",
          "platformCutAmount": "4950",
          "recipientAmount": "19800",
          "txHash": "5kW...",
          "recordedAt": "2026-02-04T01:35:00.000Z"
        },
        {
          "idempotencyKey": "order:ord_...:full:payout",
          "leg": "full",
          "chain": "solana",
          "role": "recipient_payout",
          "recipient": "So1RecipientAddress...",
          "feeBps": null,
          "amount": "2475000",
          "platformCutAmount": null,
          "recipientAmount": null,
          "txHash": "3hN...",
          "recordedAt": "2026-02-04T01:35:02.000Z"
        }
      ]
    }
  },
  "stages": [
    {
      "name": "deposit_confirmed",
      "status": "completed",
      "completedAt": "2026-02-04T01:30:05.000Z"
    },
    {
      "name": "refund_requested",
      "status": "completed",
      "completedAt": "2026-02-04T01:30:10.000Z"
    }
  ]
}

With Authorization, the order object is the full public operation record. Without it, some fields are omitted. amountIn and feeAmount reflect the actual processed deposit. When the on-chain deposit differs from the original quote, the engine updates these fields before execution. Any positive deposit amount is accepted. The stages array will include amount_reconciled when this adjustment occurred. Depending on route and progress, the order can include:

flashnetRequestId when a Flashnet swap has executed
sparkTxHash when a Spark transfer, withdrawal, or Lightning action is created
swap metadata when a Flashnet swap leg has been recorded
paymentIntent metadata for exact-out orders
zeroconfOffer when a ZeroConf offer has been generated for a Bitcoin L1 deposit (see ZeroConf offer fields)
feePlan when quote-level appFees or affiliateId was requested
feePayouts as affiliate and recipient payout legs are executed
feePayouts.entries[*].role is app_fee, recipient_payout, platform_fee, or fee_custody
feePayouts.entries[*].affiliateId is present for app-fee entries derived from affiliateId
feePayouts.entries[*].leg is full for a completed recipient or fee-custody transfer, holdback for an affiliate fee retained for a later claim, or legacy instant on historical multi-leg records. It is unrelated to ZeroConf.
supersededByOperationId on an order left unfulfilled whose Bitcoin deposit was replaced (e.g. RBF’d) and recovered by a later order — the id of that successor order. See Recovered (superseded) orders.
recoveredFromOperationId on a successor order that recovered a replaced deposit — the id of the original unfulfilled order it took over.

GET /v1/orchestration/history

List your orders filtered by recipientAddress.

curl -sS "https://orchestration.flashnet.xyz/v1/orchestration/history?address=So1RecipientAddress...&limit=50" \
  -H "Authorization: Bearer fn_..."

Headers:

Authorization: Bearer fn_...

Query parameters:

Param	Required	Notes
`address`	Yes	Recipient address on the destination chain (or BOLT11 invoice for Lightning destinations)
`status`	No	Exact match on the order status
`limit`	No	Default `50`, max `200`
`offset`	No	Default `0`

Response:

{
  "orders": [{ "id": "ord_...", "status": "completed" }]
}

History entries use the same order shape as GET /v1/orchestration/status, including optional swap, paymentIntent, and zeroconfOffer metadata when present.

Overview

Concepts

Guides

Reference

Security

Quotes and Orders

GET /v1/orchestration/routes

GET /v1/orchestration/limits

GET /v1/orchestration/estimate

POST /v1/orchestration/quote

Fixed delivery (deliveryMode)

POST /v1/orchestration/submit

POST /v1/orchestration/onramp

GET /v1/orchestration/order

GET /v1/orchestration/status

GET /v1/orchestration/history

​GET /v1/orchestration/routes

​GET /v1/orchestration/limits

​GET /v1/orchestration/estimate

​POST /v1/orchestration/quote

​Fixed delivery (deliveryMode)

​POST /v1/orchestration/submit

​POST /v1/orchestration/onramp

​GET /v1/orchestration/order

​GET /v1/orchestration/status

​GET /v1/orchestration/history

GET /v1/orchestration/routes

GET /v1/orchestration/limits

GET /v1/orchestration/estimate

POST /v1/orchestration/quote

Fixed delivery (deliveryMode)

POST /v1/orchestration/submit

POST /v1/orchestration/onramp

GET /v1/orchestration/order

GET /v1/orchestration/status

GET /v1/orchestration/history