Trade Tools

Prerequisite: All trade tools require an active authenticated session. Call get_auth_status first to verify.

Recommended Flow

Always follow the quote → confirm → execute pattern:

1. get_swap_quote       →  Show quote to user
2. User confirms        →  Proceed to execute
3. swap_tokens          →  Execute the swap
4. get_tx_status        →  Verify confirmation

get_swap_quote

Get a price quote for a swap without executing. Always call this before swap_tokens so the user can review the expected output.

Param	Type	Required	Description
`amount`	string	Yes	Amount to swap (e.g., `0.1`, `100`)
`from_token`	string	Yes	Source token symbol (e.g., `ETH`, `USDC`)
`to_token`	string	Yes	Destination token symbol (e.g., `STRK`, `DAI`)
`provider`	string	No	`fibrous` (default), `avnu`, `ekubo`, or `auto` (race all)

This is a read-only tool — safe to call without user confirmation. Returns expected output amount, estimated gas cost, and route details.

swap_tokens

Execute a token swap on Starknet using Fibrous DEX aggregation.

Param	Type	Required	Description
`amount`	string	Yes	Amount to swap (e.g., `0.1`, `100`)
`from_token`	string	Yes	Source token to sell (e.g., `ETH`, `STRK`)
`to_token`	string	Yes	Destination token to buy (e.g., `USDC`, `DAI`)
`slippage`	number	No	Slippage tolerance in % (default: `1`)
`simulate`	boolean	No	Set `true` to estimate fees without executing
`provider`	string	No	`fibrous` (default), `avnu`, `ekubo`, or `auto` (race all)

Important: Always call get_swap_quote first and confirm with the user before executing.

get_multi_swap_quote

Get quotes for 2–3 swap pairs at once using Fibrous batch routing.

Param	Type	Required	Description
`swaps`	array	Yes	Array of 2–3 swap objects
`provider`	string	No	`fibrous` (default), `avnu`, `ekubo`, or `auto` (race all)

Each swap object: { amount, from_token, to_token }

This is a read-only tool — safe to call without user confirmation.

multi_swap

Execute 2–3 swaps in a single multicall transaction. Call get_multi_swap_quote first to preview.

Param	Type	Required	Description
`swaps`	array	Yes	Array of 2–3 swap objects
`slippage`	number	No	Slippage tolerance in % (default: `1`)
`simulate`	boolean	No	Set `true` to estimate fees without executing
`provider`	string	No	`fibrous` (default), `avnu`, `ekubo`, or `auto` (race all)

Each swap object: { amount, from_token, to_token }

Note: Minimum 2, maximum 3 swap pairs per transaction.

batch_execute

Execute a batch of mixed operations (swap, stake, supply, send, borrow, repay, withdraw, dca-create, dca-cancel, troves-deposit, troves-withdraw) atomically in a single Starknet multicall.

Param	Type	Required	Description
`operations`	array	Yes	Array of operation objects (minimum 2)
`simulate`	boolean	No	Set `true` to estimate fees without executing

Each operation has a type and params:

Type	Params	Example
`swap`	`amount`, `from_token`, `to_token`	`{ "type": "swap", "params": { "amount": "100", "from_token": "USDC", "to_token": "ETH" } }`
`stake`	`amount`, `token`, `pool` or `validator`	`{ "type": "stake", "params": { "amount": "50", "token": "STRK", "validator": "karnot" } }`
`supply`	`amount`, `token`, `pool`	`{ "type": "supply", "params": { "amount": "200", "token": "USDC", "pool": "Prime" } }`
`send`	`amount`, `token`, `to`	`{ "type": "send", "params": { "amount": "10", "token": "STRK", "to": "0x04a3..." } }`
`borrow`	`collateral_amount`, `collateral_token`, `borrow_amount`, `borrow_token`, `pool`	`{ "type": "borrow", "params": { "collateral_amount": "0.5", "collateral_token": "ETH", "borrow_amount": "500", "borrow_token": "USDC", "pool": "Prime" } }`
`repay`	`amount`, `token`, `collateral_token`, `pool`	`{ "type": "repay", "params": { "amount": "100", "token": "USDC", "collateral_token": "ETH", "pool": "Prime" } }`
`withdraw`	`amount`, `token`, `pool`	`{ "type": "withdraw", "params": { "amount": "200", "token": "USDC", "pool": "Prime" } }`
`dca-create`	`sell_amount`, `sell_token`, `buy_token`, `amount_per_cycle`, `frequency?`	`{ "type": "dca-create", "params": { "sell_amount": "1000", "sell_token": "USDC", "buy_token": "ETH", "amount_per_cycle": "10" } }`
`dca-cancel`	`order_id`, `provider?`	`{ "type": "dca-cancel", "params": { "order_id": "abc123" } }`
`troves-deposit`	`amount`, `strategy_id`, `token?`	`{ "type": "troves-deposit", "params": { "amount": "100", "strategy_id": "evergreen_strk" } }`
`troves-withdraw`	`amount`, `strategy_id`, `token?`	`{ "type": "troves-withdraw", "params": { "amount": "50", "strategy_id": "evergreen_strk" } }`

Note: Minimum 2 operations required per batch. Each operation is executed atomically — if any fails, the entire batch reverts.

CLI equivalent: Trading Commands and Batch Command