Asset Hub Swap API
Broker as a Service (BaaS) swaps DOT and the listed tokens on Polkadot Asset Hub to and from every other supported chain, through the REST API and the MCP server. This page collects what is specific to Polkadot Asset Hub: minimums, addresses, deposits and refunds, and pitfalls. For the general flow, start with Starting a Swap and View Available Assets.
Assets and minimums
| Asset | id | Decimals | Minimum | Native minimum | Contract |
|---|---|---|---|---|---|
| DOT | dot.hub | 10 | 4 DOT | 40000000000 | — |
| USDC | usdc.hub | 6 | 20 USDC | 20000000 | 1337 |
| USDT | usdt.hub | 6 | 20 USDT | 20000000 | 1984 |
Snapshot captured on 2026-11-17 from the production /assets endpoint. Minimums are Chainflip's current source (ingress) minimum deposit amounts; query /assets for live values. Destination-side egress minimums depend on fees and are not in /assets; see Error Codes for egress_below_minimum and egress_fee_not_covered. minimalAmountNative is in the asset's smallest unit (planck for DOT). Assets disabled upstream are omitted.
The BaaS asset ids are dot.hub, usdc.hub and usdt.hub. For USDC and USDT, the Contract column shows the Asset Hub on-chain asset identifier (1337 and 1984), which /assets reports in its contractAddress field. Those numbers identify the tokens on Asset Hub; they are not BaaS asset ids.
Addresses
BaaS accepts an Asset Hub address in either of two forms:
- The 32-byte account public key as 64 hexadecimal characters, with or without a
0xprefix. - An SS58 address with the Polkadot network prefix (
0, addresses starting with1). SS58 addresses with another network prefix, such as Kusama or generic Substrate addresses, are rejected.
/swap converts an SS58 destination or refund address to its hex public key before opening the channel and echoes the address back as you sent it; hex input passes through unchanged. A destination address is checked with the destination asset's rules and a refund address with the source asset's, so an Asset Hub refundAddress is required when the source asset is on Asset Hub.
Deposits and refunds
A /swap call opens a deposit channel and returns the address the user sends the source asset to. This is the only way to swap from Asset Hub.
- Deposit channels close after 24 hours. Open a new channel for every deposit-channel swap and send the deposit immediately (Chainflip: closure of deposit channels).
minimumPriceandrefundAddressare required.retryDurationInBlocksis optional: omitted or negative, it is the 150-block (15-minute) default, and a value above Chainflip's current runtime limit is lowered to that limit. Use the quote'srecommendedRetryDurationInBlocks.- If the minimum price or live price protection is not met within the retry window, the source asset is refunded to
refundAddress. For DCA, only unexecuted chunks are refunded; executed chunks still pay out to the destination.
See Starting a Swap and Chainflip's Swapping Basics.
Polkadot has deterministic finality, so Chainflip's ingress table needs no confirmations beyond inclusion in a block. Show users the quote's estimatedDurationSeconds rather than a fixed number.
Vault swaps
Vault swaps are not supported for Asset Hub source assets: Chainflip has no vault swaps on Polkadot (Vault Swaps). A /tx-payload/* request with an Asset Hub sourceAsset answers 400 (Unknown Source Asset.); use a /swap deposit channel instead. Asset Hub assets can still be the destination of a vault swap from another chain. A vault payload passes the destination address on as given, without the SS58-to-hex conversion /swap does.
Boost is documented for Bitcoin deposits; see the Bitcoin page.
Known pitfalls
- No vault swaps. Swaps from Asset Hub always go through a deposit channel.
- Use
dot.hub, neverdot. The legacy Polkadot relay-chain assetdot.dotis disabled and absent from/assets, and the bare aliasdotresolves to it, so a request withdotfails. Passdot.hub(aliashubdot). - SS58 prefix. Only Polkadot-prefix SS58 addresses are accepted; convert other formats to the Polkadot prefix or pass the hex public key.
- Token identifiers.
1337and1984are Asset Hub's on-chain ids for USDC and USDT; passusdc.hubandusdt.hubto BaaS. - Account minimums. Asset Hub enforces its own minimum account balances (existential deposits); BaaS does not check them. See the Polkadot documentation for the chain's rules.