Trade / Swap Tokens

Exchange one token for another on Starknet via Fibrous trade aggregation. The CLI finds the best route across multiple DEXs, simulates the swap, and executes. All transactions are routed through the Paymaster by default (gas paid in STRK or configured token).

Prerequisites

• Active session required.
• Sufficient balance of the source token + gas fees.

Rules

1. BEFORE any trade, you MUST run npx starkfi@latest status and npx starkfi@latest balance to verify connectivity and source token balance.
2. Default slippage is 1%. To change, use --slippage <percent>.
3. Suggest using --simulate first for large trades so the user can review the estimated fee and expected output before committing.
4. AFTER a successful trade, you MUST verify the transaction using npx starkfi@latest tx-status <hash>.
5. For multiple swaps in one transaction, use the multi-swap skill instead.

Commands

npx starkfi@latest trade <amount> <from> <to> [--slippage <percent>] [--simulate] [--json]

Parameters

Parameter	Type	Description	Required
amount	number	Amount of source token to swap	Yes
from	string	Source token symbol (e.g. ETH, USDC)	Yes
to	string	Target token symbol (e.g. STRK, DAI)	Yes
--slippage	number	Slippage tolerance in % (default: 1)	No
--simulate	flag	Estimate fees without broadcasting	No
--json	flag	Output as JSON	No

Examples

User: "Swap 100 USDC for ETH"

npx starkfi@latest status
npx starkfi@latest balance --token USDC
npx starkfi@latest trade 100 USDC ETH
npx starkfi@latest tx-status <hash>

User: "How much ETH would I get for 500 USDC?"

npx starkfi@latest trade 500 USDC ETH --simulate

User: "Convert 0.5 ETH to STRK with 2% slippage"

npx starkfi@latest status
npx starkfi@latest balance --token ETH
npx starkfi@latest trade 0.5 ETH STRK --slippage 2
npx starkfi@latest tx-status <hash>

Error Handling

Error	Action
No route found	Liquidity may be too low or pair doesn't exist.
Insufficient balance	Check balance and suggest a smaller amount.
Simulation failed	Route is invalid or would revert. Do not retry blindly.
Not authenticated	Run authenticate-wallet skill first.

Related Skills

• Use balance to check available tokens before trading.
• Use multi-swap for executing 2-3 swaps in a single transaction.
• Use batch for combining a swap with other operations (stake, supply, send).
• Use config to set a custom RPC if experiencing rate limits.