Crank Protocol

place_perp_order

Destructive

Open a leveraged perp position on the best/selected venue (non-custodial).

side is "long" | "short". market e.g. SOL-PERP; size_usd is notional USD. venue optional -- defaults to the configured primary (Jupiter Perps), with health failover to the fallback for new orders. Returns an UNSIGNED tx (Tier A) or a signing payload (Tier B) for your wallet to sign + broadcast, plus venue_name / custody_tier / settlement_token. Tier B (venue-custodied) venues require acknowledge_tier_b=true after reviewing custody_disclosure. Fee charged on size_usd notional past the daily free tier (x402).

jurisdiction: your ISO-3166-1 alpha-2 country code, self-declared -- perps are geo-gated (no US persons, unknown jurisdiction DENIED). Declare once here (or via declare_jurisdiction/trade_equity) and it is remembered 90 days.

Workflow: EXECUTE step (leveraged directional leg) -- after get_venue_health / get_venue_risk_score clear the venue and get_risk_assessment caps the size. Monitor via perp_positions. See get_trading_workflow.

idempotency_key (optional): a client-generated UUID. Retrying with the same key + same args replays the original result instead of re-opening the order. Reuse the SAME key across the build call and its signed_transaction completion call -- the two legs dedupe independently, so this never raises IDEMPOTENCY_CONFLICT; a NEW key means a genuinely new order.

signed_transaction / verify (two-phase execution): re-call this tool with the SIGNED payload and Crank relays it by custody tier -- Tier A to Solana RPC, then awaits on-chain confirmation and re-reads the position on the executing venue; Tier B to the venue's own submit endpoint, which returns a venue order id (reported as venue-acknowledged, since it is not an on-chain signature). Gate follow-on decisions on verification.confirmed, never on tx_signature alone.

venue_action (optional, completion leg only): the value the BUILD leg recorded on extra['venue_action'] -- pass it back alongside signed_transaction so Crank relays the bytes under the venue action the venue itself named (e.g. Jupiter's create-limit-order, for a keeper-co-signed build that can only land via the venue's execute endpoint). Omit it and Crank infers the route from the signed bytes' own message header instead, which is correct but less authoritative.

Input Schema

TableJSON Schema

Name	Required	Default
`ip`	No
`side`	Yes
`venue`	No
`market`	Yes
`verify`	No
`leverage`	Yes
`size_usd`	Yes
`caller_id`	No
`order_type`	No	market
`limit_price`	No
`jurisdiction`	No
`pay_in_crank`	No
`venue_action`	No
`payment_header`	No
`wallet_address`	Yes
`idempotency_key`	No
`stop_loss_price`	No
`take_profit_price`	No
`acknowledge_tier_b`	No
`signed_transaction`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 23, 2026

addedInput schema / properties / venue_action

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed2 schema fields changedAug 12, 2026

addedInput schema / properties / ip

Added value: +{
+  "default": "",
+  "type": "string"
+}

addedInput schema / properties / jurisdiction

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

Changed2 schema fields changedAug 11, 2026

addedInput schema / properties / signed_transaction

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / verify

Added value: +{
+  "default": true,
+  "type": "boolean"
+}

First observedJul 27, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description discloses extensive behavior beyond the annotations: two-phase execution via signed_transaction/verify, Tier A vs Tier B custody differences, requirement for acknowledge_tier_b, fee structure, jurisdiction gating with denial on unknown country, and idempotency_key replay semantics. These are exactly the non-obvious traits an agent needs, and none contradict the annotations.

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

Conciseness4/5

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

The description is long but intentionally organized into topical paragraphs, front-loading the core purpose and then covering returns, fees, jurisdiction, workflow, idempotency, and two-phase execution. Every paragraph adds functional value, though it is slightly verbose and could be tightened without loss.

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

Completeness4/5

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

The description is remarkably complete for a complex tool: it covers prerequisites, workflow ordering, two-phase relay, geo-gating, fees, and custody tiers, and an output schema exists so return values are already specified. Missing details include the semantics of verify=false, order_type/limit_price behavior, and the purpose of pay_in_crank/payment_header, which leaves some edge cases uncovered.

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?

With 0% schema description coverage, the description must compensate, and it does for critical params: side, market, size_usd, venue, jurisdiction, idempotency_key, signed_transaction, verify, venue_action, and acknowledge_tier_b. However, several params—order_type, limit_price, stop_loss_price, take_profit_price, pay_in_crank, payment_header, caller_id, ip—are left unexplained, which is a notable gap for a 20-parameter tool.

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?

The description opens with a specific, actionable statement: 'Open a leveraged perp position on the best/selected venue (non-custodial).' It names the resource (perp position), the action (open), and the non-custodial nature, and clarifies the return type (unsigned tx or signing payload). This distinguishes it clearly from simpler sibling tools like perp_open_long/short and leverage_long.

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

Usage Guidelines4/5

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

The description gives explicit workflow context: it is the EXECUTE step that should follow venue health/risk checks and risk assessment, and it tells the agent to monitor via perp_positions and see get_trading_workflow. It does not explicitly name alternative tools or state when NOT to use this tool, so it lacks formal exclusions but provides clear situational guidance.

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

All Crank Protocol 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?