Tools

The full surface, read from the server itself.

Every tool the server exposes, grouped. This list is generated from the same definitions the server answers with, so it cannot describe a tool that is not there or miss one that is.

Each description carries four things a model needs: what it does, when to reach for it, what it cannot do, and what a failure means. The third is the one that saves the most turns, because it stops an agent discovering a limit by hitting it.

Size is in the base asset, not dollars. On PERP_ETH_USDC a quantity of 0.5 is half an ETH, not fifty cents. Convert a dollar figure with markPrice from list_markets, round it to quantityStep, and check it clears minNotional. Getting this wrong places an order orders of magnitude too large.

Symbols are always PERP_<BASE>_USDC. A bare ETH is never accepted. Resolve a name with list_markets before any trading call.

Market data

No credentials. Prices, depth, history, funding and venue health.

list_markets
Every tradable perpetual market with live price, 24h statistics, max leverage, minimum notional and tick sizes.
When to use
Start here for almost anything: discovering what can be traded, resolving a plain name like 'ethereum' to a symbol, or reading a price before quoting it.
Cannot
- Return spot pairs. These are perpetual futures; use get_swap_quote for token swaps.
- Return history. It is a snapshot; use get_candles.
- Return depth. Use get_orderbook.
Use cases
- 'What can I trade?'
- 'How is ETH doing today?' read change24hPct
- Resolving a user's asset name to a symbol before place_order
On failure
- `unavailable`/`timeout`: the venue is unreachable. Retry once, then report it.
Arguments
- searchstringOptionalCase-insensitive filter on symbol and name, e.g. "eth".
get_orderbook
Current bid and ask depth for one market.
When to use
Before sizing a large order, or to judge the spread before choosing market versus limit.
Cannot
- Stream. It is a snapshot; poll for a fresh one.
- Show your own resting orders. Use list_orders.
- Guarantee a fill at any level shown.
Use cases
- 'How much slippage on a large ETH long?'
- Choosing a limit price just inside the touch
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
get_candles
OHLC candle history for one market, oldest first.
When to use
Any question about how a price behaved over time: trend, volatility, or computing an indicator.
Cannot
- Return tick data. 1m is the finest interval.
- Return more than 500 candles per call.
- Compute indicators. It returns raw OHLCV; do the arithmetic yourself.
Use cases
- 'Show ETH over the last week' interval 1h, limit 168
- Computing a moving average before sizing a stop
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
- intervalstringOptionalCandle width. Default 1h.One of 1m · 5m · 15m · 30m · 1h · 4h · 1d · 1w
- limitnumberOptionalDefault 100, maximum 500.
get_recent_trades
Recent public fills on one market: price, size and side.
When to use
To read live tape and judge whether a market is actively quoted.
Cannot
- Identify counterparties.
- Show your own fills. Use list_fills.
Use cases
- 'Is there real activity here right now?'
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
- limitnumberOptionalDefault 50, maximum 200.
get_funding
Current and predicted funding rate, and the next payment time.
When to use
Before holding a perpetual across a funding event, or when asked what carrying a position costs.
Cannot
- Predict beyond the next scheduled payment.
- Show funding you personally paid. Use get_account_summary.
Use cases
- 'What does holding this long overnight cost?' a positive rate means longs pay shorts
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
get_platform_status
Exchange health and any scheduled maintenance window.
When to use
Before a trading session, and after any unexpected failure, to tell a planned outage from a real fault.
Cannot
- Predict unscheduled downtime.
Use cases
- 'Why did my order fail?' check for maintenance first
Arguments
Takes no arguments.

Swaps and rankings

No credentials. Cross-chain quotes and public standings.

get_swap_quote
Price a token swap or bridge and return an UNSIGNED transaction for the user's wallet to sign.
When to use
Whenever a user asks to swap, bridge or convert tokens, or what a conversion would yield.
Cannot
- Execute the swap. It returns calldata only; this server holds no wallet key and never will.
- Hold a price. Quotes expire within about a minute. Re-quote before signing.
- Accept a token by symbol. Pass contract addresses; resolve them with list_swap_tokens.
Use cases
- 'What would 1 ETH get me in USDC on Arbitrum?'
- 'Bridge my USDC to Base' same token, different chain ids
On failure
- `no_route`: nothing prices this pair. Try routing through USDC.
- `amount_too_small`: below the bridge minimum.
Arguments
- fromChainnumberRequiredSource chain id, e.g. 1.
- toChainnumberRequiredDestination chain id.
- fromTokenstringRequiredContract address being sold.
- toTokenstringRequiredContract address being bought.
- amountstringRequiredAmount in the token SMALLEST unit as a decimal string. 1 USDC (6 decimals) is "1000000"; 1 ETH is "1000000000000000000". This is the most common mistake.
- fromAddressstringRequiredWallet that will sign.
get_leaderboard
Top traders by volume, profit or open position size.
When to use
Questions about who is performing well or how large the biggest participants are.
Cannot
- Identify anyone. Addresses are shortened and unlinkable to a person.
- Look up a specific address's rank.
Use cases
- 'Who is up the most this week?' window 7d, sort pnl
Arguments
- windowstringOptionalOne of 24h · 7d · 30d
- sortstringOptionalOne of volume · pnl · notional
- limitnumberOptional

Account

Credentials required. Reads your own account and nothing else.

get_account_summaryCredentials
Account equity, free collateral, unrealised profit and margin ratio.
When to use
Before sizing anything, and whenever asked how the account is doing. The first call of any trading session.
Cannot
- Show positions individually. Use list_positions.
- Show wallet balances outside the exchange; collateral must be deposited first.
Use cases
- 'How much can I trade with?' read freeCollateral
- 'Am I near liquidation?' compare marginRatio against maintenance
On failure
- `unauthorized`: no credentials, or a key that expired. Keys last at most 365 days.
Arguments
Takes no arguments.
list_positionsCredentials
Open positions with side, size, entry, mark, unrealised profit and estimated liquidation price.
When to use
Before opening or closing anything, and whenever asked what is held.
Cannot
- Close a position. Use close_position.
- Show closed positions. This is what is open now.
- Guarantee the liquidation price, which moves with funding and collateral.
Use cases
- 'What am I holding?'
- Checking for existing exposure before adding to it
Arguments
Takes no arguments.
list_ordersCredentials
Resting and recently completed orders.
When to use
To check whether a limit is still working, or to find an order id before cancelling.
Cannot
- Cancel anything. Use cancel_order.
- Show positions.
Use cases
- 'Did my limit fill?'
- 'What is still open?'
Arguments
- statusstringOptionalOne of INCOMPLETE · COMPLETED
get_referral_statusCredentials
Your referral links, invitee count and fees earned.
When to use
When asked about referrals, an invite link, or referral earnings.
Cannot
- Create a link. Use create_referral_link.
- Identify who used the link; referees are counted, never named.
- Change the rebate split, which the operator fixes.
Use cases
- 'What is my invite link?'
- 'How much have I earned?'
Arguments
Takes no arguments.

Trading

Credentials required. These act on real funds at real leverage.

place_orderCredentialsReal funds
Open or add to a position: market or limit, long or short.
When to use
Only after the user explicitly asked to trade AND you confirmed market, direction, size and type back to them. Never exploratory.
Cannot
- Be undone. A filled market order can only be reversed by trading back out at whatever the market is then.
- Set leverage. Size against the collateral to commit instead.
- Accept a dollar notional. `quantity` is in the BASE asset: 0.5 means half an ETH. Convert with markPrice, then check minNotional and round to quantityStep.
- Place below the market minimum notional or off its quantity step.
- Withdraw funds. No order type here moves money off the exchange.
Use cases
- 'Go long 0.5 ETH at market' PERP_ETH_USDC, BUY, MARKET, 0.5
- 'Buy ETH if it drops to 2400' LIMIT with price 2400
On failure
- `insufficient_balance`: size down after get_account_summary.
- `amount_too_small`: below minNotional from list_markets.
- `invalid_request`: usually a quantity off quantityStep.
- NEVER blindly retry. Call list_positions first: a retry after a partial fill doubles the position.
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
- sidestringRequiredBUY opens or increases a long. SELL a short.One of BUY · SELL
- typestringRequiredOne of MARKET · LIMIT
- quantitynumberRequiredSize in the BASE asset, not dollars. Must be a multiple of quantityStep and worth at least minNotional.
- pricenumberOptionalRequired when type is LIMIT.
- reduceOnlybooleanOptionalWhen true the order can only shrink an existing position.
close_positionCredentialsReal funds
Close all or part of an open position at market, reduce-only.
When to use
When the user asks to exit, take profit or cut a loss.
Cannot
- Choose the exit price; it closes at market. For a target, place a reduce-only LIMIT with place_order.
- Close a position that does not exist. Call list_positions first.
- Cancel resting orders on that market, which may re-open exposure. Cancel them separately.
Use cases
- 'Close my ETH position'
- 'Take half off' pass half the size
Arguments
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.
- quantitynumberOptionalBase-asset amount to close. Omit to close all of it.
cancel_orderCredentialsReal funds
Cancel one resting order by id.
When to use
When a limit order is no longer wanted, or before replacing its price.
Cannot
- Cancel an order that already filled.
- Close a position. Cancelling removes an instruction, not exposure.
Use cases
- 'Cancel my ETH limit' find the id with list_orders first
Arguments
- orderIdstring or numberRequired
- symbolstringRequiredMarket symbol as PERP_<BASE>_USDC, for example "PERP_ETH_USDC". A bare "ETH" is not accepted; resolve names with list_markets first.