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 is the committed action — once you POST /v1/order with the accepted quote parameters and provider, we mint a one-time deposit address and start watching for funds. The order moves through this state machine:

PENDING→PROCESSING→SUCCESS
terminal alternatives:REFUNDEDFAILED

The states you will encounter:

  • PENDING — deposit address is live, waiting on funds. Some providers also return a deadline after which the order is cancelled.
  • PROCESSING — deposit detected or confirmed, route is executing. Most orders settle within a few minutes from here.
  • SUCCESS — destination funds delivered. Has a settlementTxHash.
  • REFUNDED — something failed mid-flight and refund handling completed. Has a refundTxHash.
  • FAILED — we accepted the deposit but cannot settle through the normal route or complete refund handling without support review. Rare; contact support with the orderId.

You can either poll GET /v1/order/:id on a 10–15s interval, or consume partner webhooks when enabled. Webhooks are at-least-once — make the handler idempotent on orderId.

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