TradeHub

Preview a perpetual futures order

preview_perp_order

Read-only

Check a perpetual futures order with its stop-loss (optional take-profit) against this agent's permissions, the person's limits and the price band, sending nothing. Use before every new position, also one that waits for a price (trigger_price) or is split over 2-5 limit prices (ladder_prices). Not for closing (use close_perp_position_reduce_only). size_base (base coin): from size_position_by_risk; stop: stop_loss (USD) or stop_pct. Returns preview_id (30 s), notional, risk, margin and every check; a rejection names the failing check. Next: execute_previewed_order(preview_id).

Input Schema

Name	Required	Description	Default
`side`	Yes	buy = open or add to a long, sell = open or add to a short
`price`	No	Limit price, USD per coin (limit orders only)
`venue`	No	Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox; or "best": the cheapest all-in venue (price plus fee) you may use and have the margin for	hyperliquid
`reason`	No	Optional: why, in your words (up to 500 characters). The person sees it on the approval card and in history; other agents never do
`symbol`	Yes	Base coin, e.g. BTC
`leverage`	No	Leverage, e.g. 5
`stop_pct`	No	Or the stop as a distance from the entry (trigger price, limit price or mark), 0.02 = 2%
`size_base`	Yes	Size in the base coin (BTC, not USD); rounded down to the venue step. Get it from size_position_by_risk
`stop_loss`	No	Required stop-loss, USD per coin: below entry for buys, above for sells. Or give stop_pct
`hold_hours`	No	Optional: how long you expect to hold, in hours, to see funding and the round trip's cost (and, with venue "best", to choose by them)
`order_type`	No		market
`take_profit`	No	Optional take-profit, USD per coin
`ladder_prices`	No	Optional ladder entry: 2-5 limit prices, size_base split evenly across them, one stop-loss beyond all of them (stop_pct counts from the farthest price); order_type limit, no price
`trigger_price`	No	Optional: hold the order and open it at market only when the mark reaches this price (a breakout or a pullback), re-checked then; market orders only. Risk is computed from this price
`trigger_valid_hours`	No	With trigger_price: hours it waits before lapsing, 1-168 (default 24)

Output Schema

Name	Required	Description
`ok`	Yes	True: every check passed
`legs`	No	A ladder entry: [{price, size_base}] per limit leg, USD per coin and in the base coin (e.g. BTC), not USD
`side`	Yes	buy or sell
`size`	Yes	Size after rounding down to the venue step, in the base coin (e.g. BTC), not USD
`venue`	Yes	Venue name
`checks`	Yes	Every check that ran, all pass
`symbol`	Yes	Base coin
`risk_usd`	Yes	Loss if the stop fills, USD
`expires_at`	Yes	ISO 8601 UTC
`fee_source`	No	account (your own rate), published (the base rate) or none (sandbox)
`margin_usd`	Yes	Margin needed, USD
`mark_price`	Yes	Mark at preview time, USD per coin
`preview_id`	Yes	Pass to execute_previewed_order within 30 seconds
`deprecation`	No	Present only while this tool is deprecated: replacement, removal_date, changelog
`est_fee_usd`	No	Trading fee for this order, USD: taker rate for market orders, maker for limit; the exit pays a fee too
`fee_rate_bps`	No	The rate used, basis points of notional
`notional_usd`	Yes	size x entry, USD
`venue_choice`	No	With venue "best": why this venue (all-in price and the alternatives)
`trigger_price`	No	A trigger entry: opens at market only when the mark reaches this, USD per coin
`est_fill_price`	No	Market orders: average fill if executed now against the book, USD per coin; null for limit orders or when the book is too thin to say
`est_funding_usd`	No	With hold_hours: funding over that time at today's rate, USD; negative = received
`est_slippage_bps`	No	est_fill_price against mark_price in basis points, positive = worse; a market order never fills beyond the price band
`requires_approval`	Yes	True: execute_previewed_order will wait for a person's approval
`trigger_valid_hours`	No	A trigger entry: hours it waits before lapsing
`est_round_trip_cost_usd`	No	With hold_hours: entry fee, exit fee at the taker rate and that funding, USD

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 29, 2026

addedInput schema / properties / ladder_prices

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "exclusiveMinimum": 0,
+        "type": "number"
+      },
+      "maxItems": 5,
+      "minItems": 2,
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional ladder entry: 2-5 limit prices, size_base split evenly across them, one stop-loss beyond all of them (stop_pct counts from the farthest price); order_type limit, no price",
+  "title": "Ladder Prices"
+}

addedOutput schema / properties / legs

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "A ladder entry: [{price, size_base}] per limit leg, USD per coin and in the base coin (e.g. BTC), not USD",
+  "title": "Legs"
+}

Changed3 schema fields changedOct 27, 2026

addedInput schema / properties / hold_hours

Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "maximum": 2160,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional: how long you expect to hold, in hours, to see funding and the round trip's cost (and, with venue \"best\", to choose by them)",
+  "title": "Hold Hours"
+}

addedOutput schema / properties / est_funding_usd

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With hold_hours: funding over that time at today's rate, USD; negative = received",
+  "title": "Est Funding Usd"
+}

addedOutput schema / properties / est_round_trip_cost_usd

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With hold_hours: entry fee, exit fee at the taker rate and that funding, USD",
+  "title": "Est Round Trip Cost Usd"
+}

Changed5 schema fields changedOct 27, 2026

changedInput schema / properties / venue / description

Previous value: -"Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox"New value: +"Venue: sandbox, hyperliquid, okx, bybit or binance. Omitted: the agent's only venue, else hyperliquid, else your only connected venue, else sandbox; or \"best\": the cheapest all-in venue (price plus fee) you may use and have the margin for"

addedOutput schema / properties / est_fee_usd

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Trading fee for this order, USD: taker rate for market orders, maker for limit; the exit pays a fee too",
+  "title": "Est Fee Usd"
+}

addedOutput schema / properties / fee_rate_bps

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "The rate used, basis points of notional",
+  "title": "Fee Rate Bps"
+}

addedOutput schema / properties / fee_source

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "account (your own rate), published (the base rate) or none (sandbox)",
+  "title": "Fee Source"
+}

addedOutput schema / properties / venue_choice

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "With venue \"best\": why this venue (all-in price and the alternatives)",
+  "title": "Venue Choice"
+}

First observedOct 27, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint/openWorldHint, but the description adds real value beyond them: the preview_id expires in 30 seconds, what the response contains (notional, risk, margin, every check), and that a rejection names the failing check. The 30s TTL is the key operational fact and explains the non-idempotent hint. It stops short of stating rate limits or whether a preview reserves anything.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core definition, then usage, then inputs, then outputs, then the next step. Dense but every clause carries a distinct fact; nothing is redundant with the title or the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A 15-parameter, multi-mode tool (market/limit/trigger/ladder) with an output schema and strong annotations. The description covers purpose, exclusions, the non-obvious input sources, the return contract and the chaining target — an agent has everything needed to call it correctly without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 93%, so the schema already carries most parameter meaning; the description earns extra credit by adding cross-tool provenance (size_base comes from size_position_by_risk) and clarifying the stop choice (stop_loss in USD vs stop_pct). It restates the trigger_price/ladder_prices purpose at a high level without duplicating the schema's constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (preview/check a perpetual futures order) and immediately scopes it: validated against agent permissions, person limits and price band, 'sending nothing'. That last clause alone separates it from any real order tool. It also names the sibling it is not for (close_perp_position_reduce_only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ('before every new position'), covers the non-obvious variants (trigger_price waiting orders, 2-5 price ladders), and gives an explicit exclusion with the correct alternative. The closing 'Next: execute_previewed_order(preview_id)' routes the agent to the correct follow-up step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All TradeHub tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?