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.

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
`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

TDQS

A4.7/5.0

Behavior5/5

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

The description richly discloses behaviors beyond the annotations: returns an UNSIGNED tx vs signing payload, Tier A/Tier B custody distinctions, fee-on-notional mechanics, geo-gating with 90-day jurisdiction memory, idempotency replay behavior, two-phase signed_transaction/verify execution, and the requirement to gate on verification.confirmed. The only mild wrinkle is the initial 'non-custodial' qualifier versus the later 'venue-custodied' Tier B, but the custody split is explicitly explained, so the agent is not misled overall.

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?

The description is long but every paragraph earns its place: summary, venue/custody returns, jurisdiction, workflow, idempotency, and two-phase execution. It is front-loaded with the core summary and then expands into purpose-specific details, making dense complexity navigable. No filler or tautological sentences are present.

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?

Given an output schema exists and the operation is complex (custody tiers, jurisdiction gates, two-phase signing, venue failover, idempotency), the description covers all major behavioral and invocational context. It even points to supplementary workflow tools and positions users on what must happen before and after the call. Nothing essential to making a correct call seems 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?

Schema description coverage is 0%, so the description carries most of the burden. It does add real value: explains side, market example, size_usd notional USD, venue defaulting/failover, jurisdiction format/self-declaration, idempotency_key semantics, signed_transaction/verify two-phase behavior, and acknowledge_tier_b requirement. However, a 19-parameter schema with several meaningful fields (leverage, order_type, limit_price, stop_loss_price, take_profit_price, pay_in_crank, etc.) is only partially elaborated, relying on parameter names to infer meaning.

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 begins with a specific verb and resource: 'Open a leveraged perp position on the best/selected venue.' It clearly states the side, market, size, venue, and return type, and distinguishes itself from close/cancel/modify siblings by focusing on opening new positions. The inclusion of 'best/selected venue' plus custody tiers also sets it apart from simpler perp_open_long/perp_open_short siblings.

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 after get_venue_health / get_venue_risk_score clear the venue and after get_risk_assessment caps size; positions are monitored via perp_positions; and the full workflow pointer to get_trading_workflow is provided. It does not explicitly say when not to use the tool (e.g., 'use perp_open_long instead when...'), so it misses the 'when-not/alternatives' level, but the workflow usage is otherwise clear.

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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

B3.2/5.0

Disambiguation2/5

Multiple tools overlap significantly: close_perp_position vs perp_close, get_leaderboard vs get_score_leaderboard vs get_strategy_leaderboard, get_venue_status vs get_all_venues_status, send_token_social vs bulk_send_social, and get_crank_score vs get_score. Several read-only tools have nearly identical purposes, and the descriptions do not always clarify boundaries.

Naming Consistency4/5

Most tools follow a consistent verb_noun snake_case pattern (get_balances, create_strategy, set_alert, list_webhooks). However, there are deviations like 'lst_swap', 'jupiter_swap', 'flash_loan', 'sr_backtest', and the use of both 'get_' and 'list_' for reads, plus category prefixes like 'perp_' and 'strategy_' that vary in order. Overall still readable and predictable.

Tool Count1/5

177 tools is an extreme count for any server, far exceeding the 25+ threshold for 'too many'. Even a full DeFi platform does not need this many separate operations; the surface is overwhelming and clearly not well-scoped.

Completeness3/5

The domain (Solana DeFi trading) is covered extensively across swaps, perps, lending, staking, strategies, signals, and support. However, there are notable gaps: no lend_withdraw, no direct way to close a lending position, no spot order cancellation (though aggregator-based swaps may not need it), and a general lack of tiered account management. The huge number of tools makes it hard to identify missing lifecycle steps.

Resources

Need Help?