web3-swap

name	web3-swap
description	Use when: swap tokens, trade, exchange, buy tokens, sell tokens, convert crypto, get swap quote, best swap route, DEX aggregation (same-chain only). NOT for cross-chain or bridge transfers. 中文: 兑换, 交易, 换币, swap, 买卖, 币币兑换, 最优路径, 报价（仅限同链，不含跨链）.
license	MIT
metadata	{"author":"blocksecteam","version":"1.0.0"}

Web3 Swap — Aggregated DEX

Tag semantics (<NEVER> / <MUST> / <SHOULD>): see ~/.claude/skills/_shared/tags.md.

Supported chains are determined by the deployment configuration — run web3 chain list for the current set. Do not hardcode chain names in this skill.

Supported protocols are dynamic — run web3 swap protocols to get the current list. Live quote and execute support depends on each adapter; unimplemented adapters return explicit errors and are excluded from best-route selection.

Step 0 — Re-route check

• Cross-chain bridge transfer — HARD BLOCK: route to web3-bridge.
• Token transfer (same-chain native or ERC-20) — HARD BLOCK: route to web3-chain.
• Portfolio / balance / USD value — HARD BLOCK: route to web3-portfolio.
• Token search / metadata / price — HARD BLOCK: route to web3-token.
• Pre-execution security check or override — HARD BLOCK: route to web3-security.
• Sign transaction / EIP-7702 delegation / account status — HARD BLOCK: route to web3-ssm.
• Wallet create / delete / export → guide the user to the Wallets page.
• Signing policies management → guide the user to the Signing Policies page.
• SSM audit log review → guide the user to the SSM Audit page.
• Same-chain token swap (DEX) → stay in this skill.

Pre-flight Checks

At the start of every swap conversation, run: ``` web3 chain list web3 swap protocols ``` The output goes into your context for later token / protocol resolution — do not dump it to the user. Only surface it when relevant: if the user picks a chain not in the list, tell them "Supported chains are: [list]." (Respond in the user's language.) If the user asks what swap protocols are available, list them then.

Then follow ~/.claude/skills/_shared/preflight.md for delegation check, portfolio, balance, and gas verification before executing.

Required Parameters

See ~/.claude/skills/_shared/preflight.md § Required Parameters. The table below lists this skill's six parameters.

Parameter	Rule
--chain	Must be confirmed by the user; the CLI has no default.
--from	Must be confirmed. Contract address, or native for the chain's native token. Never a bare symbol — see Token Resolution below.
--to	Must be confirmed. Contract address, or native for the chain's native token. Never a bare symbol — see Token Resolution below.
--amount	Must be confirmed. Human-readable token quantity.
--from-address	Required for quote only. build does not accept this flag — the wallet's address is resolved from --wallet.
--wallet	Must be confirmed for build. Wallet ID used to sign the transaction.

Token Resolution

Follow ~/.claude/skills/_shared/token-resolution.md for symbol → address resolution, decimals handling, and native usage.

Amount Resolution

Follow ~/.claude/skills/_shared/amount-resolution.md.

MUST read that file before issuing the CLI command when the user's request matches any of:

• "all" / "max" / "全部" / "the whole balance" / "drain it" / equivalents meaning the entire token balance
• A fiat amount (USD / $ / CNY / ¥ / EUR, etc.)
• A bare number with no unit on a non-stablecoin token

Each case has a specific procedure in the shared doc (full-balance trim recipe and gas reserve, fiat conversion, ambiguity handling). Skipping the shared doc is what triggers the "I thought I had enough balance" simulation reverts.

Only exact-amount-in is supported. There is no exact-amount-out. When the user expresses a desired output amount (e.g. "get 10 AAVE") or an output fiat value (e.g. "receive $5 of AAVE"), convert to the equivalent input token quantity and confirm with the user.

Never pass an output token quantity as --amount (exact-amount-out is not supported).

Getting a Quote

web3 swap quote --chain ethereum --from-address 0xabc... --from native --to 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 --amount 1

If the user doesn't specify a protocol, the system fans out to all compatible adapters and returns the successful quotes in protocols[] (sorted best first). If every adapter fails, the response is HTTP 503 with error.code = "no_quote" and the per-adapter errors under all_results — there is no all_results field on the success path. Unimplemented or failing adapters never appear in protocols[] and must not be presented as usable routes.

--from-address is required for quote. build does not accept this flag — the wallet's address is resolved from --wallet. --amount is human-readable (see _shared/token-resolution.md).

Slippage

Follow ~/.claude/skills/_shared/slippage.md for the default-announcement script, supports_slippage decision tree, and suggested ranges.

Displaying the Quote

Present the quote with only the fields the response actually returns. Format `in_amount` and `out_amount` to human units using the source/target token decimals. Do not invent price impact, gas estimate, or route — the quote response does not include them.

Best route: <protocol>

Detail	Value
Swap	<from_amount> <from_symbol> → ~<to_amount> <to_symbol>
Slippage	<slippage>%

Would you like to proceed?

When multiple protocols return quotes

Give the user context: name the winning protocol + which others also returned a quote and which had no route. Example shape (translate to user's language): "`` has the best rate. `` also returned a quote. The others had no route or are not implemented for this pair."

Build, Security Review, Sign, Broadcast

After the user confirms the quote, create the transaction intent with:

web3 swap build --wallet <wallet_id> --chain <chain> --from <from_address> --to <to_address> --amount <amount> --protocol <chosen_protocol> [--slippage <percent>]

--slippage defaults to 0.5%. Override per _shared/slippage.md.

web3 swap build only creates the transaction intent. It does not run security checks, sign, or broadcast.

Follow ~/.claude/skills/_shared/security-handling.md for the security check → decision → sign → broadcast flow. After broadcast returns submitted, also follow ~/.claude/skills/_shared/broadcast-output.md for the rendering rules, then apply the swap-specific field table in Execution Output below.

Swap-specific build summary fields

When you pull fields for the broadcast output, source them from the earlier web3 swap build response's summary:

• From / To: format summary.input_amount and summary.output_amount (raw integer wei) into human units using the source/target token decimals, then label with the token symbol. Resolve summary.source_asset and summary.target_asset addresses; for "native", look up the chain's native_symbol from web3 chain list.
• Protocol: summary.protocol verbatim.
• Tx hash / Explorer: from the broadcast response.

Show only the fields you actually have. Never invent amounts or token symbols.

Never manually reconstruct swap transactions from `to/value/data`. `web3 swap build` returns a `transaction_id` and everything downstream (sign, broadcast) keys off that id.

Execution Output

Follow ~/.claude/skills/_shared/broadcast-output.md for rendering rules (no fenced block, hash truncation, explorer table, status wording). Use this swap-specific field table:

Swap broadcast — <chain>

Field	Value
From	<from_amount> <from_symbol>
To	~<to_amount> <to_symbol>
Protocol	<protocol>
Tx hash	0xabc1234…<last8>
Explorer	<chain explorer name>

Substitute <chain explorer name> and <base-url> from the chain → explorer table in _shared/broadcast-output.md; never hardcode etherscan.io for non-Ethereum chains.

- Never auto-confirm without showing the quote first - Never execute without explicit user confirmation

Intent Expiry

If any command (security check, sign, broadcast) returns HTTP 410 with transaction_intent_expired, read ~/.claude/skills/_shared/intent-expiry.md and follow the swap recovery path.

Other Error Codes

For any other error.code returned by quote/build/sign/broadcast (unsupported_chain, unknown_protocol, quote_failed, build_failed, not_delegated, pending_delegation, policy_rejected, invalid_amount, decimals_unresolvable, etc.) consult ~/.claude/skills/_shared/error-codes.md. no_quote is handled inline in the Getting a Quote section.

Risk Controls

When any of the conditions below triggers, stop and wait for explicit user confirmation before continuing — even if the user has previously said "just quote and build" or similar. These are user-facing reminders, not programmatic gates.

Situation	What to tell the user
Every adapter returned no quote (all_results all error)	"No route available for this pair right now. Want to try a smaller amount or a different pair?" Do not retry build automatically.
Insufficient source balance for the amount, or zero native for gas	"You have <balance> <symbol> but trying to swap <amount>." Show the gap explicitly; wait for user instruction.
Operation USD value is large (>$1K notional)	"This swap moves ~$<X>. Confirm the size before I quote."

Slippage ranges live in ~/.claude/skills/_shared/slippage.md.

Post-Swap Suggestions

After a swap, suggest:

• Check new balance: "Want to verify your new balance?"
• Track the tx: "I can check when the transaction confirms."
• Another swap: "Need to swap anything else?"