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, a swap is the committed action, 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 pick the best for every quote.

From your point of view, route selection is opaque: you ask for a quote, you get back the best 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.
  • Carry a quoteId. That is what you pass to POST /v1/swap to commit. After expiry, the quoteId is dead and you must re-quote.

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.

Swaps

A swap is the committed action — once you POST /v1/swap with a live quoteId, we mint a one-time deposit address and start watching for funds. The swap moves through this state machine:

PENDING_DEPOSIT→KNOWN_DEPOSIT_TX→PROCESSING→SUCCESS
terminal alternatives:REFUNDEDFAILED

The states you will encounter:

  • PENDING_DEPOSIT — deposit address is live, waiting on funds. Has an expiresAt after which the swap is auto-cancelled.
  • KNOWN_DEPOSIT_TX — we saw the deposit tx in the mempool. Still needs confirmations.
  • PROCESSING — deposit confirmed, route is executing. Most swaps settle within ~3 minutes from here.
  • SUCCESS — destination funds delivered. Has a settlementTxHash.
  • REFUNDED — something failed mid-flight and we returned the deposit. Has a refundTxHash.
  • FAILED — we accepted the deposit but cannot settle and cannot refund automatically. Rare; contact support with the swapId.

You can either poll GET /v1/swap/:id on a 10–15s interval, or register a webhook URL in your dashboard. Webhooks are at-least-once — make the handler idempotent on swapId.

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 10 bps (0.10%) 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