Crank Protocol

jupiter_swap

Destructive

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

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`ip`	No
`amount`	Yes
`verify`	No
`caller_id`	No
`venue_hint`	No
`input_token`	Yes
`jurisdiction`	No
`output_token`	Yes
`pay_in_crank`	No
`slippage_bps`	No
`payment_header`	No
`wallet_address`	Yes
`idempotency_key`	No
`allow_unverified`	No
`signed_transaction`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

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

Behavior5/5

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

The description goes far beyond the four annotations, disclosing fees collected on-chain via platformFeeBps and deducted from swap output, the no-op payment_header due to x402 exclusion, idempotent replay semantics, the verification block returned when verify=true (gate on verification.confirmed), hard geo-gating (Reg S, OFAC) for tokenized securities, and honest slippage reporting via applied_source='platform_default'. The destructiveHint=true annotation is corroborated, not contradicted, by the swap-execution semantics.

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 for a 15-parameter swap tool covering fees, security, idempotency, verification, and geo-gating, the density is justified and structurally front-loaded — the core purpose and dual-mode operation lead, followed by logical sections. Minor redundancy exists ('non-custodial' appears twice, 'unchanged from before' twice) but doesn't materially bloat it.

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 the tool's complexity — 15 parameters, no schema descriptions, output schema present — the description covers every behavioral area an agent needs: modes of operation, fee mechanics, security checks, workflow integration, idempotency, verification semantics, and geo-gating. Since an output schema exists, the absence of a return-value explanation is appropriate, and references to get_quotes and get_trading_workflow close the remaining workflow loop.

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?

With 0% schema description coverage, the description carries the full parameter-documentation burden and does so almost completely: amount ('in base units of input_token'), slippage_bps (default 50 bps), allow_unverified (risk override with hard scam signals never overridable), venue_hint (advisory, unknown hint raises), idempotency_key (UUID, replay/dedupe semantics, reuse across build and broadcast), verify (confirmation block), jurisdiction (persisted declaration), ip (Reg-S layer), pay_in_crank (discount schedule), signed_transaction (dual-mode), and payment_header (no-op). Only caller_id goes unexplained, and the required tokens/wallet are evident from context.

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 pairing — 'Execute a token swap via Jupiter (non-custodial)' — and immediately clarifies the two operational modes (returning an unsigned tx vs. broadcasting a signed one). The Jupiter naming differentiates it from swap siblings like evm_swap and lst_swap in the sibling list, and the non-custodial qualifier pins down the execution model.

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?

Provides explicit workflow placement: 'Get a price first with get_quotes' and 'EXECUTE step -- deploy the directional/allocation leg after the risk phase capped the size', plus a pointer to get_trading_workflow. It also routes later verification to verify_transaction and notes the geo-gate mirrors trade_equity's control. It doesn't contrast directly with evm_swap/lst_swap, but the workflow and prerequisite references give strong when-to-use 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?