Skip to main content
Every amount in the Orchestra API is an integer string in the asset’s smallest units. "50000000" is $50.00 of 6-decimal USDC. "100000" is 0.001 BTC in sats. There are no floats and no decimal points anywhere in the API. Decimals per asset come from the source and destination detail objects on GET /v1/orchestration/routes. Read them from there; never hardcode decimals in your integration.

​
amountMode

One field, amount, interpreted by amountMode. The mode answers which side of the swap the user is fixing. exact_in (the default): the user knows their budget. amount is what the user sends; estimatedOut is what arrives after fees and execution. Use this for “swap $50 of USDC” flows. exact_out: the recipient must receive an exact amount. amount is what the recipient gets, and the API computes requiredAmountIn (what the user must deposit) and maxAcceptedAmountIn (the ceiling above which the deposit refunds). Use this for payment intents: “the merchant needs exactly 100 USDC.” Exact-out constraints:
  • It is per-route. Check exactOutEligible on GET /v1/orchestration/routes before offering it.
  • Stablecoin exact-out amounts must be whole-cent values: multiples of 10000 for 6-decimal stables. A non-cent value returns 400 invalid_request.
  • refundAddress is required for exact_out, and for any Lightning destination in either mode.

​
amountFiatUsd

amountFiatUsd pins the sender’s USD figure instead of a crypto amount. It is available on /onramp and pay links only, and is mutually exclusive with amount. The server converts USD to sats at request time using a Coinbase and Kraken spot oracle. When the spot price is stale, the request fails closed with 503 spot_unavailable rather than pinning a wrong dollar figure. The accepted range is 1.00to1.00 to 50,000.00. amountFiatUsd runs as exact_in. Combining it with amountMode: "exact_out" is gated to USD-stablecoin destinations and invoice-billing partners, and rejects app and affiliate fees. See USD-pinned mode for the full contract.

​
Limits

GET /v1/orchestration/limits is the authoritative per-route min/max source. The bounds are operator-tuned and change without notice, so query the endpoint instead of hardcoding numbers. A few constraints are static and enforced in code: BTC swap inputs need at least 5,000 sats from Bitcoin L1 and 1,200 sats from Spark, and Bitcoin L1 delivery needs at least 10,000 sats after route fees. /limits reports these alongside the runtime bounds, typed per constraint.

​
When the deposit differs from the quote

Deposits do not need to match the quoted amount exactly, and the rules differ by amountMode. Order Lifecycle owns the full behavior: underpayment, overpayment, and the exact-out refund conditions.

​
Where to go next

  • Pricing for estimates, quotes, and fixed delivery
  • Fees for what gets deducted before delivery
  • Quotes and Orders for request and response shapes