Multi-Swap

Execute 2-3 independent token swaps in a single Starknet transaction via Fibrous (default). Other providers can be selected with --provider, or use --provider auto to race all providers per pair. All swaps are bundled into one multicall, saving gas compared to executing them individually.

Prerequisites

• Active session required.
• Sufficient balance for ALL source tokens + gas fees.

Rules

1. BEFORE any multi-swap, you MUST run npx starkfi@latest status and npx starkfi@latest balance to verify connectivity and source token balances for ALL pairs.
2. Minimum 2 and maximum 3 swap pairs per multi-swap. Single swaps should use the trade skill instead.
3. The pairs string MUST be wrapped in double quotes and each pair separated by a comma.
4. Each pair follows the format: <amount> <FROM>><TO> (no spaces around >).
5. Default slippage is 1%. To change, use --slippage <percent>.
6. Suggest using --simulate first so the user can confirm gas cost.
7. AFTER a successful multi-swap, you MUST verify using npx starkfi@latest tx-status <hash>.

Commands

npx starkfi@latest multi-swap "<pairs>" [--provider <fibrous|avnu|ekubo|auto>] [--slippage <percent>] [--simulate] [--json]

Parameters

Parameter	Type	Description	Required
pairs	string	Swap pairs: "100 USDC>ETH, 50 USDT>STRK" (2-3 pairs)	Yes
--provider	string	Provider: fibrous (default), avnu, ekubo, auto (race all)	No
--slippage	number	Slippage tolerance in % (default: 1)	No
--simulate	flag	Estimate fees without broadcasting	No
--json	flag	Output as JSON	No

Pair Format

"<amount> <FROM>><TO>, <amount> <FROM>><TO>"

Examples:

• "100 USDC>ETH, 200 USDT>STRK" — two pairs
• "50 DAI>ETH, 100 USDC>STRK, 0.1 ETH>USDT" — three pairs (maximum)

Examples

User: "Swap 100 USDC to ETH and 200 USDT to STRK in one transaction"

npx starkfi@latest status
npx starkfi@latest balance
npx starkfi@latest multi-swap "100 USDC>ETH, 200 USDT>STRK"
npx starkfi@latest tx-status <hash>

User: "Simulate swapping 50 DAI, 100 USDC, and 0.1 ETH"

npx starkfi@latest multi-swap "50 DAI>ETH, 100 USDC>STRK, 0.1 ETH>USDT" --simulate

Error Handling

Error	Action
Too few pairs	Multi-swap requires at least 2 pairs. Use trade for singles.
Too many pairs	Maximum 3 pairs. Split into multiple calls.
No route found	One or more pairs lack liquidity.
Insufficient balance	Check balance — user may lack one of the source tokens.
Provider unavailable	Specified provider is invalid. Valid: fibrous, avnu, ekubo.
All providers failed	All providers timed out or errored. Retry later.
Simulation failed	One of the routes is invalid or would revert.
Not authenticated	Run authenticate-wallet skill first.

Related Skills

• Use trade for a single swap (simpler syntax).
• Use batch for combining swaps with other operations (stake, supply, send).
• Use balance to verify you have enough of all source tokens.