AllSwap

Core concepts

The AllSwap API has four nouns you will deal with again and again: a route is a path through liquidity, a quote is a price preview on that path, an order is the committed deposit-address swap, and fees are how it costs. This page is the mental model behind the endpoints.

Routes

A route is one way to move value from a source asset on chain A to a destination asset on chain B. We integrate multiple aggregated routes upstream — internally referred to as route_A, route_B, etc. — and select a provider route for each quote.

From your point of view, route selection is opaque: you ask for a quote, you get back the selected amount_out with a string label. You never have to think about which one was used unless you want to log it.

Why we hide it: upstream routes change. Pricing models shift, schemas evolve, new ones come online and old ones get deprecated. We absorb all of that behind a single stable contract so your integration does not need to be rewritten every quarter.

Quotes

A quote is a non-binding price preview. It tells you, right now, what amount your user would receive on the destination chain for a given input. Quotes:

  • Expire in ~30 seconds. The market moves; we will not honor a stale price.
  • Cost nothing. Quotes are free, and only count against the quotes/month bucket on your tier — not against any swap cap.
  • Return provider candidates. A dry quote gives you the available provider routes plus the selected best label. Commit by sending the accepted quote parameters and providerId to POST /v1/order.

For a swap UI, fetch a new quote every ~10 seconds while the user is on the review screen. We rate-limit quote requests per key, but a 10s refresh is comfortably under the limit on every tier.

Orders

An order commits the selected route. POST /v1/order returns its payment instructions. Before payment the source wallet or payment account controls the funds; after payment, funds enter the settlement route and normally cannot be recalled. AllSwap does not maintain a user-balance account. The diagram shows the normal flow and other possible states, not a guarantee of delivery or recovery:

PENDING→PROCESSING→SUCCESS
other reported states:REFUNDEDFAILEDEXPIRED

The states you will encounter:

  • PENDING — waiting for payment. Respect the returned deadline; do not pay an expired order.
  • PROCESSING — deposit detected or confirmed, route is executing. Most orders settle within a few minutes from here.
  • SUCCESS — the route reports delivery. Verify the asset, recipient and transaction on the destination network; the recipient controls delivered assets.
  • REFUNDED — the route reports a return to its refund destination. Verify the actual address and receipt. A return to an AllSwap-controlled fallback still requires support review and onward payment to the user.
  • FAILED / EXPIRED — settlement did not complete as expected or the payment window ended. Neither proves that payment was received or a refund completed. Continue checking funded orders and contact support before paying again.

Poll GET /v1/order/:id every 10–15 seconds, or consume partner webhooks when enabled. Webhooks are at-least-once: handle them idempotently by orderId. Supply a usable source-chain refundTo controlled by the intended beneficiary. Do not assume omission means return to sender: a configured fallback may require manual review, and recovery is not guaranteed on every network. Refund timing and amount depend on the route, network costs and actual deposit. Use the transaction records returned by the API; dedicated settlementTxHash or refundTxHash fields are not guaranteed.

Fees

The quote response breaks the cost down into two buckets:

  • fee.platformBps — our take, in basis points off the input. Already deducted from amount_out; never an extra charge on top. Defaults to 25 bps (0.25%) and is negotiable on Enterprise.
  • fee.networkUsd — gas + settlement cost, normalized to USD for display. Paid out of liquidity, not out of your user's wallet on top.

What we don't do: we never bill you per swap. Your monthly invoice is purely the platform tier. The platform bps is collected from the swap flow itself, not from your account.

Next