jupiter_swap
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.
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
| 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
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||