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 reads the signed bytes' own message header: caller-completable bytes go to Solana RPC, but keeper-co-signed bytes need a venue action, which is then derived from order_type alone (limit -> create-limit-order, market -> increase-position). On the completion leg order_type is therefore load-bearing and is NEVER defaulted: omit both it and venue_action on keeper-co-signed bytes and the call is refused with a re-build instruction rather than relayed under a guessed action. Always round-trip the build response's extra['venue_action'].

order_type: "market" | "limit". Omitted on the BUILD leg it defaults to "market" (unchanged); omitted on the completion leg it stays unset (see venue_action above).

simulate (optional): true = rehearse this call. The full gate stack (capability, kill switch, session signer, wallet policy, permission mode, soft launch, venue / compliance / token checks, fee quote) is evaluated read-only and returned as verdicts + would_execute, with a paper fill where one applies. Nothing is built, signed, broadcast or charged. Omitted = your wallet's default_simulate setting; false = execute.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "wallet_address": "<wallet_address>",
      "market": "<market>",
      "side": "<side>",
      "size_usd": "<size_usd>",
      "leverage": "<leverage>"
    },
    "name": "place_perp_order"
  }
}

Input Schema

Name	Required	Description	Default
`ip`	No
`side`	Yes
`venue`	No
`market`	Yes
`verify`	No
`leverage`	Yes
`simulate`	No
`size_usd`	Yes
`caller_id`	No
`order_type`	No
`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

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 15, 2026

addedInput schema / properties / simulate

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

Changed3 schema fields changedOct 5, 2026
- addedInput schema / properties / order_type / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / order_type / default
```
Previous value: -"market"New value: +null
```
- removedInput schema / properties / order_type / type
```
Removed value: -"string"
```

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.3/5.0

Behavior5/5

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

Annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false) are heavily supplemented: it discloses the non-custodial Tier A/Tier B custody split, that it returns an unsigned tx or signing payload, the notional fee/x402 charge, geo-gating with jurisdiction DENIED, two-phase signed_transaction/verify completion, idempotency_key replay semantics, and simulate's read-only gate stack. This is far more than the annotations convey.

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 core purpose and side/market/size/venue basics are front-loaded before the dense parameter and workflow detail. It is long and heavily formatted, and could likely be trimmed, but the added detail is mostly load-bearing for a two-phase, custody-aware execution tool rather than filler.

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?

Output schema exists, yet the description still surfaces the essential return shape (unsigned tx vs signing payload, venue_name/custody_tier/settlement_token) and covers the full lifecycle—build, sign, complete, monitor—plus geo-gating, fees, and idempotency. Nothing an agent needs to call it correctly is obviously missing.

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 across 21 params, the description carries the full burden and documents the most load-bearing ones (side, market, size_usd, venue, jurisdiction, idempotency_key, venue_action, order_type, verify, signed_transaction, simulate, acknowledge_tier_b). It leaves limit_price, stop_loss_price, take_profit_price, leverage, pay_in_crank, payment_header, ip, and caller_id undocumented, so coverage is good but incomplete.

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

Purpose4/5

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

States a specific verb+resource clearly: 'Open a leveraged perp position on the best/selected venue (non-custodial).' An agent can immediately tell what it does. However, close siblings like perp_open_long, perp_open_short, leverage_long, and short_open overlap heavily and the description never distinguishes this unified tool from them.

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?

Gives real workflow guidance: names it as the 'EXECUTE step' with prerequisites (get_venue_health / get_venue_risk_score clearing, get_risk_assessment capping size), points to get_trading_workflow, and names perp_positions for monitoring. It lacks any explicit routing rule for when to choose this over perp_open_long/perp_open_short, so guidance is clear but not exclusionary.

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?