---
name: allways
description: Swap or bridge any listed asset across chains with Allways. Use when the user wants to swap, bridge or convert crypto between chains, get TAO or Bittensor subnet alpha, or pay a swap deposit from an agent wallet. No account and no API key.
---

# Allways swap

Allways swaps any listed asset for any other across chains, including Bittensor subnet alpha. You get a quote, open a swap, send the deposit from your own wallet, and the received asset is paid to the payout address. Allways never holds keys and never signs.

## When to use

- The user wants to swap, bridge or convert an asset from one chain to another.
- The user wants TAO or Allways Alpha, or any other subnet alpha, paid to a Bittensor address.
- An agent wallet must pay a swap deposit and track the swap to its end.

## Connect

Prefer the MCP server. If MCP is not available, call the HTTP API. Both need no auth.

```bash
claude mcp add --transport http allways https://all-ways.io/mcp
```

## MCP server

- Endpoint: `https://all-ways.io/mcp` (Streamable HTTP, stateless, POST only, no auth).
- Server card: `https://all-ways.io/.well-known/mcp.json`. Official MCP registry name: `io.all-ways/allways`.
- Swap tools: `find_asset`, `get_quote`, `create_swap`, `get_swap`, `wait_for_swap`, `build_deposit_tx`, `report_swap_problem`.
- Prompt: `swap {from, to, amount}` renders the complete safe swap flow.
- Referral tools: `start_referral_sign_in`, `finish_referral_sign_in`, `create_referral_code`, `get_my_referrals`. The leaderboard and the payout log are HTTP only.
- Client config, for clients that take a JSON server list:

```json
{ "mcpServers": { "allways": { "type": "http", "url": "https://all-ways.io/mcp" } } }
```

## HTTP API

- [OpenAPI spec](https://all-ways.io/openapi.json): every route, field and error.
- API catalog (RFC 9727): `https://all-ways.io/.well-known/api-catalog` links the spec, the docs and the MCP server card.
- `GET /api/assets?q=usdc+arbitrum`: find asset ids, best match first. `/api/catalog` lists everything but is large.
- `POST /api/quotes` `{from, to, amount, side?}`: `side` is `send` (default) or `receive`. Rates float: the payout follows the market when the deposit arrives.
- `POST /api/swaps` `{from, to, amount, expectedOut, payout, refund, referralCode?}` with an `Idempotency-Key` header: opens the swap and returns the deposit address.
- `GET /api/swaps/{id}`: read the current status. Over MCP, prefer `wait_for_swap`, which returns on a status change or timeout.
- `POST /api/swaps/{id}/deposit-tx` `{from?, version?}`: Solana and TAO only. Solana returns `transaction`, the deposit as a base64 unsigned transaction for the `from` wallet to sign and send. `version` is `"legacy"` (default) or `0`; send `0` for a wallet that only sends version 0 transactions, such as Trust Wallet. TAO takes an empty body `{}` and returns `call` and `node`: see "Send TAO".
- `POST /api/swaps/{id}/report` `{category, message, contact?, depositTx?, amountDelivered?}`: report a problem. Categories: `not_received`, `wrong_amount`, `refund`, `slow`, `stats_wrong`, `other`. `depositTx` (your deposit transaction) goes only with `not_received`; `amountDelivered` (what arrived, a decimal) only with `wrong_amount`.
- Swap page for a human: `https://all-ways.io/swap/{id}`.

## Swap flow

1. Find the asset ids for both sides. An id names the chain and the token, e.g. USDC on Arbitrum is a different id from USDC on Solana. Always confirm the chain with the user.
2. Quote. Amounts are exact decimal strings in whole units ("0.5", not lamports or wei). Respect `min` and `max`. Quotes explain the chosen route with the provider display name.
3. Open the swap with the quote's `amountIn`, as `expectedOut` the `amountOut` of `best`, and a `refund` address. It never opens for less; a `409 rate_changed` carries the new `amountOut` to re-confirm.
4. Send exactly `amountIn` of the `from` asset to `deposit.address`, on the `from` asset's chain, before `expiresAt`.
   - EVM: `deposit.tx` is that payment as an unsigned transaction `{chainId, to, value, data}`. Hand it to the wallet unchanged; the wallet adds nonce and gas. `value` is wei as a 0x hex quantity. For a token, `to` is the token contract and `data` is the ERC-20 transfer to the deposit address.
   - Solana: `POST /api/swaps/{id}/deposit-tx` (MCP `build_deposit_tx`) with the paying address builds the unsigned transaction: a SOL transfer or an SPL `transferChecked`, plus the memo if the deposit has one. Sign and send it within about a minute, or build a new one.
   - TAO: see "Send TAO" below.
   - `deposit.uri` is the same payment as a link, for wallets that read one: BIP21 on Bitcoin, Solana Pay on Solana, EIP-681 on EVM. Other networks have no `uri`: send by hand.
   - `tx` and `uri` are present only while the status is `awaiting_deposit` and before `expiresAt`. Allways never signs or sends: your wallet does.
5. Wait for the swap. Terminal statuses: `finished`, `refunded`, `failed`, `expired`. `payoutTx` / `refundTx` hold the on-chain transactions. Swap responses include the provider display name, but never provider order ids or internal client references.

### Send TAO

A TAO deposit is a plain transfer from a Bittensor coldkey. `amountIn` is already whole TAO: pass it as it is, never as rao.

- btcli: `btcli tx transfer --dest <deposit.address> --amount-tao <amountIn> -w <wallet>`. Run it with `--dry-run` first to preview.
- bittensor Python SDK: `sub = bt.Subtensor(); intent = bt.Transfer(dest_ss58="<deposit.address>", amount_tao=<amountIn>); sub.plan(intent, wallet); sub.execute(intent, wallet)`.
- Your own Substrate signer: `POST /api/swaps/{id}/deposit-tx` (MCP `build_deposit_tx`) returns `call` `{method, args, callHex}` and `node`. `callHex` is the SCALE-encoded `Balances.transfer_keep_alive` call, not a signed extrinsic: check `args` (`dest` is the deposit address, `value` is `amountIn` in rao), sign it with the paying coldkey and submit it to `node`.
- Both tools keep the paying account alive by default. Send once, by one of these.
- Bittensor's own agent docs: [llms.txt](https://www.bittensor.com/llms.txt), [agents](https://www.bittensor.com/docs/agents).

## Rules that protect the user's funds

- Send on the exact chain of the `from` asset id. A deposit on another chain can be lost.
- If `deposit.memo` is set, the transfer must carry that memo or destination tag. Without it the deposit cannot be matched.
- Send once, by one method: `deposit.tx`, the built Solana transaction, the TAO command or call, `deposit.uri` or a manual send. Never two of them. A second send to the same deposit address is outside the quote and may need support to recover.
- Give a `refund` address on the send chain when you open the swap; it is where funds return if the swap cannot complete. It is set once, at open, and never changed later. Use an address the user controls.
- Generate one `Idempotency-Key` (MCP `idempotencyKey`, required) per intended swap and reuse it on every retry of that create, so a retry never opens a second swap.
- Do not send after the swap expired. Open a new one.
- Never ask the user for a seed phrase or private key. Allways never needs one.
- `notices` on a swap flag `under_deposit`, `stuck`, `aml_hold` or `price_moved`: report them to the user.

## When something goes wrong

- Report every swap problem through Allways itself: MCP `report_swap_problem`, `POST /api/swaps/{id}/report`, or "Report a problem" on the swap page. This is the support channel. A report reaches the team with the swap's diagnosis.
- Report once for `stuck`, `under_deposit`, or `aml_hold`, or anything else wrong with a swap. Send the category, a 10–500 character message, and an optional reply email.
- The team receives the report together with the swap's diagnosis. A repeat adds to the same case; after five entries, wait for the team instead of retrying.
- Without a reply email there is no written reply. Watch the swap with `get_swap`: `status`, `refundTx`, and `reported`, which turns false when the team closes the case.
- A successful report makes `reported: true` on `get_swap` while the case is open. `price_moved` does not need a report; tell the user the payout follows the market.

## Gas

- Keep a little native gas on the send chain: ETH on Ethereum and Base, SOL on Solana, and so on.
- Allways never pays gas. The deposit is a normal transfer from the sender's wallet, and the sender pays its network fee.

## Limits

- Selling subnet alpha and native TAO staking need a wallet signature and are not offered over MCP or the API yet.
- Not available in sanctioned jurisdictions. Requests are rate limited per IP.

## More detail

- [llms.txt](https://all-ways.io/llms.txt): the source of the sections above, plus Get TAO, referrals and wallet providers.
- [llms-full.txt](https://all-ways.io/llms-full.txt): llms.txt plus setup for each client and an HTTP quickstart.
- Support: report swap problems with `report_swap_problem` (see When something goes wrong), never by email.
