Crank Protocol

jupiter_swap

Destructive

Execute a token swap via Jupiter (non-custodial).

submit_mode (optional): your execution preference. Omitted/"public" = public-RPC broadcast (default, unchanged). "mev_protected" = the tx is built with a Jito tip you pay (jito_tip_lamports, default 10,000) and relayed to the Jito block engine as a bundle. Use the same mode on build and broadcast. A failed protected submit returns an error and is NOT sent publicly unless you set mev_fallback_public=true. The response execution block names the mode and tip. Mainnet only. Never selected for you.

Without signed_transaction: returns an UNSIGNED base64 transaction for your wallet to sign + broadcast. With signed_transaction: broadcasts the caller-signed tx and returns tx_signature. amount is in base units of input_token. Includes the Crank technology service fee when a referral fee account is configured -- collected ON-CHAIN via Jupiter's platformFeeBps, deducted from swap output. Swaps are NOT additionally gated by x402 (that would double-charge the same fee), so payment_header stays a no-op here (jupiter_swap is not in x402 PAID_TOOLS). pay_in_crank is NO LONGER a no-op: the on-chain rate is now derived from this wallet's volume tier and $CRANK staker / pay-in-$CRANK / Crank Score discounts, so a discounted wallet is quoted a lower platformFeeBps -- the same schedule x402 applies to perps/lend/stake.

slippage_bps omitted (None) resolves to the published platform default of 50 bps -- unchanged from before; the returned envelope's slippage.applied_source honestly reports "platform_default" in that case rather than falsely claiming "caller".

SECURITY: the output_token is run through multi-layer authenticity verification before any tx is built; an unverified/suspicious/fake token is blocked (UNVERIFIED_TOKEN). Set allow_unverified=true to trade an unverified token at your own risk (hard scam signals are never overridable).

venue_hint is ADVISORY, never required -- spot routes via Jupiter aggregation (the only spot venue today); an unknown hint raises, omitting it is unchanged from before.

Workflow: EXECUTE step -- deploy the directional/allocation leg after the risk phase capped the size. Non-custodial. Get a price first with get_quotes. See get_trading_workflow.

idempotency_key (optional): a client-generated UUID. Retrying the SAME call (build or broadcast) with the same key + same args replays the original result instead of re-executing -- guards against a timeout-then-retry double-swap. Reuse the SAME key across the build call and its signed_transaction broadcast retry (they dedupe independently); a NEW key means a genuinely new swap.

verify (default True): when broadcasting (signed_transaction supplied), await on-chain confirmation and re-read the output_token balance -- the response gains a verification block ({confirmed, slot, post_state, expected_vs_actual}). Gate follow-on decisions on verification.confirmed, never on tx_signature alone. Set False to skip for latency-sensitive callers. Verify any prior signature later with the standalone verify_transaction tool.

GEO GATE: when either leg is a tokenized security this call is geo-gated (Reg S = no US persons) and OFAC-screened, same control trade_equity enforces -- jurisdiction declares the caller's jurisdiction once (persisted for next time), ip is the caller's origin IP for the additional Reg-S IP layer. Non-security swaps are unaffected.

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": {
      "input_token": "<input_token>",
      "output_token": "<output_token>",
      "amount": "<amount>",
      "wallet_address": "<wallet_address>"
    },
    "name": "jupiter_swap"
  }
}

Input Schema

Name	Required	Description	Default
`ip`	No
`amount`	Yes
`verify`	No
`simulate`	No
`caller_id`	No
`venue_hint`	No
`input_token`	Yes
`submit_mode`	No
`jurisdiction`	No
`output_token`	Yes
`pay_in_crank`	No
`slippage_bps`	No
`payment_header`	No
`wallet_address`	Yes
`idempotency_key`	No
`allow_unverified`	No
`jito_tip_lamports`	No
`signed_transaction`	No
`mev_fallback_public`	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 9, 2026

addedInput schema / properties / jito_tip_lamports

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

addedInput schema / properties / mev_fallback_public

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

addedInput schema / properties / submit_mode

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

Changed3 schema fields changedSep 19, 2026
- addedInput schema / properties / slippage_bps / anyOf
```
Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
```
- changedInput schema / properties / slippage_bps / default
```
Previous value: -50New value: +null
```
- removedInput schema / properties / slippage_bps / type
```
Removed value: -"integer"
```

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
+}

Changed1 schema field changedJul 28, 2026
- addedInput schema / properties / verify
```
Added value: +{
+  "default": true,
+  "type": "boolean"
+}
```
First observedJul 27, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only flag write/destructive/open-world; the description goes well beyond them, disclosing that a failed MEV-protected submit is NOT sent publicly, that fees are deducted on-chain from swap output, that payment_header is a no-op, that unverified tokens are blocked with UNVERIFIED_TOKEN unless overridden, and that verification.confirmed should gate follow-on decisions.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is bloated with changelog-style notes ('unchanged from before', 'is NO LONGER a no-op', 'not in x402 PAID_TOOLS') that describe product history rather than how to call the tool. Several sentences earn their place (idempotency, MEV fallback), but the historical framing adds noise for an agent.

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?

For a 19-parameter, destructive, open-world tool with an output schema, the description covers the full execution envelope: build vs broadcast paths, return fields (execution, verification, slippage.applied_source), gating (geo/OFAC, token authenticity), and simulation. An output schema exists, so return-value detail is appropriately not over-explained.

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

Parameters5/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 the full burden and does so for nearly every parameter: submit_mode semantics, jito_tip_lamports default, mev_fallback_public, slippage_bps None→50bps default with honest applied_source, amount in base units, idempotency_key retry/dedupe semantics, verify, simulate, allow_unverified, jurisdiction/ip. Only caller_id is left unexplained.

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?

Opens with a specific verb+resource+chain: 'Execute a token swap via Jupiter (non-custodial).' The scope (Solana/Jupiter, non-custodial, spot-only venue) is clear enough to separate it from evm_swap and lst_swap without opening any schema.

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?

Explicitly routes the agent: 'Get a price first with get_quotes. See get_trading_workflow,' and positions the call as the EXECUTE step after the risk phase capped size. It also gives per-mode guidance (same submit_mode on build and broadcast, when to set simulate, when to use verify) rather than leaving it to inference.

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?