Crank Protocol

Live reachability probe against the deployed execution sidecar. Thin wrapper around ``sidecar_service.is_configured``/``healthcheck``. Runs the probe from the SERVER's own network path, which a local ``curl $SIDECAR_URL/health`` cannot do: that only proves the caller's own shell can reach a sidecar, never whether the deployed mcp.crank.ing server can. Unconfigured (``SIDECAR_URL`` unset) raises a structured CONFIG_ERROR with NO network attempt -- feature-detected first via ``is_configured``. Configured but unreachable returns an OK envelope with ``reachable: False`` -- distinct from "not configured" -- so a caller can tell "we never tried" apart from "we tried and it's down". FREE read, never gated (never in x402 PAID_TOOLS): booleans/counts/hosts only, no secret ever leaves this tool -- presence-only, never ``config.SIDECAR_AUTH_TOKEN`` itself.

Backtest a strategy with an S/R config block (read-only simulation). Runs the existing backtest engine with strategy_type (default "support_resistance": bounce-long off detected support, exit on a support break or resistance-fail; on spot a SHORT signal is exit-to-flat) and merges the validated sr_config into params["sr"]. asset is a token mint; timeframe one of 1m/5m/15m/1h/4h/1d; start_date/end_date ISO-8601. Returns the standard performance metrics plus persisted SUPPORT_RESISTANCE signals carrying zone metadata. Read-only simulation -- no fee, no on-chain action, not financial advice (DYOR). Workflow: SIMULATE step -- validate an S/R setup on history before risking capital; feeds get_risk_assessment -> sr_configure_strategy. See get_trading_workflow.

Attach an S/R config block to YOUR OWN strategy (ownership-checked). Persists an `sr` param block (SRConfig knobs: sensitivity, sources, lookback, swing_window, zone_width_bps, merge_tolerance_bps, min_touches, min_strength, max_zones_per_side, manual_levels, liquidity_weight_k) onto the caller's own strategy params. The strategy must belong to wallet_address -- configuring someone else's strategy is refused. Strategies without an `sr` block behave exactly as before (back-compat). User/agent-owned configuration only: you own and control the strategy; the platform never exercises discretion (DYOR). No key handling, no fee. Workflow: DECIDE step -- after sr_detect_levels + sr_backtest confirm the level picture, store the tuned config on the strategy. See get_trading_workflow.

Multi-timeframe support/resistance zones + liquidity bands (read-only). Detects S/R zones per timeframe from recent OHLCV (swing highs/lows, floor pivots, Fibonacci retracement, volume-profile clusters, optional manual levels), merges them across timeframes with a confluence multiplier, and weights zone strength by overlapping candle-volume liquidity-band depth. asset is a token mint; timeframes default ["1h","4h","1d"]; lookback candles per timeframe (capped at 500); sources subset of swing / pivot / fibonacci / volume_profile / price_impact / manual; sensitivity 0-1 (higher = more zones); zone_width_bps sets the band half-width; manual_levels adds caller-supplied override prices. Returns zones (supports / resistances / pivots with price, band, strength, touches, sources, timeframes) plus liquidity_bands. Computed reference levels only -- not financial advice, not a trade instruction (DYOR). No wallet, no fee, no on-chain action. Workflow: INTELLIGENCE step -- the level picture behind sr_backtest + sr_configure_strategy; pair with get_indicators + detect_regime. See get_trading_workflow.

Create an arb strategy -- cross-venue price-discrepancy convergence (APPROXIMATE). Reads a live cross-venue spread each tick (task-sourced from the Jupiter quote corpus vs on-chain price) or falls back to a transparent PROXY (deviation below a short EMA) when unavailable. Enters when the spread clears ``entry_spread_pct`` and flat; exits when it reverts to ``exit_spread_pct``. The simultaneous two-venue fill is collapsed to one leg (flagged ``approximate``). Market-neutral: no direction params exposed (regime is read directly, not adapted). ``risk``: see ``strategy_dca_create``.

Create a basis-trade strategy -- funding-harvest perp SHORT leg (APPROXIMATE). Routes the perp leg through the multi-venue VENUE ADAPTER (hard rule 2). A live delta-neutral basis trade is long spot + short perp harvesting funding; this executor opens/manages only the perp SHORT leg (the spot long that makes the book delta-neutral is held separately by the caller) -- flagged ``approximate`` + ``funding_not_modeled`` (funding PnL itself is not simulated live). While funding is favourable (> ``min_funding``) and flat, opens the short sized ``usd_per_trade`` at ``leverage``; closes when funding decays to <= ``min_funding``. Only an asset with a mapped perp market (currently SOL) can open. A Tier B (custodied) venue needs ``acknowledge_tier_b=true``. ``risk``: see ``strategy_dca_create``.

Stop a strategy (sets status=stopped; it will not be dispatched again).

Create a composite strategy from a validated definition. Same non-custodial create path as the other 16 strategy types: the wallet holds its own keys; a wallet without a Turnkey signer receives an unsigned transaction per tick for the owner to sign. ``mode`` defaults to LIVE (recorded on the config; a paper mode annotation is informational until the managed-signing epic lands). Recommended: run compose_strategy + backtest_strategy on the definition FIRST -- historical results are not predictive; DYOR.

Create a copy-wallet strategy -- mirrors a tracked wallet's entries/exits. ``tracked_wallet`` is the Solana address to mirror (its confirmed on-chain buy/sell actions are sourced each tick); ``usd_per_buy`` is the default mirror size (scaled by ``size_multiplier``) applied when the tracked wallet buys. APPROXIMATE: no full per-fill replication (every execution is flagged ``approximate``). ``risk`` / direction params: see ``strategy_dca_create``.

Create a dollar-cost-average strategy buying ``usd_per_buy`` of target each interval. ``risk`` (optional) overrides the safe-default risk limits: ``max_position_pct`` / ``max_portfolio_exposure_pct`` / ``max_single_loss_pct`` / ``max_drawdown_pct`` / ``max_daily_loss_pct`` (percent; <=0 disables a guard). Direction (optional, all deterministic signals -- DYOR): ``direction_mode`` (auto | long_only | short_only | manual; default auto = follow the market regime, reducing exposure in a bear instead of accumulating), ``allow_short`` (enable real shorts via the configured perps venue), ``regime_override`` (force bull | bear | range | volatile instead of trusting detection). Workflow: EXECUTE step -- stand up a recurring strategy after backtest_strategy validates it and get_risk_assessment sets the guards; track via strategy_status. An agent wallet without a Turnkey signer = paper-trade (unsigned tx per tick). See get_trading_workflow.

Create an equity dollar-cost-average strategy (tokenized equities / xStocks). Shares the DCA executor -- identical mechanics/config to ``strategy_dca_create`` -- tagged ``equity_dca`` because ``target_token`` is expected to be a tokenized-equity mint. SEC posture: DCA is a MECHANICAL, user-configured strategy (not discretionary), so it stays autonomous even on a security target -- the per-execution confirmation gate only applies to the discretionary types (momentum / sentiment). Equity classification still drives geo-gating + disclaimers at execution; call asset_classification / get_disclaimers first. ``risk`` / direction params: see ``strategy_dca_create``.

Create a hedge strategy -- an exit trigger that unwinds a held position. Shares the stop-loss executor -- identical config/mechanics to ``strategy_stoploss_create`` -- framed as an active risk-offset trigger: set ``stop_loss_pct`` / ``trailing`` to shed exposure on an adverse move, or ``take_profit_pct`` to lock in a favourable one. At least one of ``stop_loss_pct`` / ``take_profit_pct`` / ``trailing`` must be set.

List a wallet's strategies (newest first, capped). ``detail``: "concise" (default) trims each row to strategy_id/strategy_type/status -- the IDs needed to chain into strategy_status/strategy_modify/strategy_cancel/strategy_pause/ strategy_resume; "full" also includes schedule/next_execution_at, as before. An unrecognised value falls back to concise (never errors).

Create a market-make strategy -- two-sided spread capture (APPROXIMATE). No live order book -- SYNTHESISES a spread from realised volatility around a rolling mid: a "filled bid" (price a half-spread below mid) buys, a "filled ask" (above mid) sells (up to held inventory). Market-neutral: PAUSES in a trending (bull/bear) regime instead of adapting direction (a maker gets run over by a directional move) -- read directly inside the executor, so no direction params are exposed here. ``risk``: see ``strategy_dca_create``.

Edit a running strategy's parameters IN PLACE -- no cancel + recreate. React to a fresh signal by retuning the strategy you already own: the execution history, cost-basis ledger and position state all survive, and there is no window where the strategy is gone. The live executor picks the new config up on its NEXT tick; a tick already in flight finishes against the config it loaded (it writes only runtime state, never config, so the two can never clobber each other). Scoped to the caller's own wallet (hard rule 1 -- non-custodial: this edits a row the owner already controls; nothing here holds keys, signs or moves funds). Args (all optional -- supply at least one): ``config_updates``: strategy-config keys to set, merged over the existing config (e.g. ``{"usd_per_buy": 25, "stop_loss_pct": 0.08}``). ``remove_keys``: config keys to drop back to the executor's default. ``risk``: retune the risk limits -- ``max_position_pct`` / ``max_portfolio_exposure_pct`` / ``max_single_loss_pct`` / ``max_drawdown_pct`` / ``max_daily_loss_pct`` (percent; <=0 disables a single guard). ``direction_mode`` / ``allow_short`` / ``regime_override``: the direction controls from the create tools (deterministic signals -- DYOR). ``target_allocation``: new mint->weight basket (rebalance / vault / yield_farm). ``interval_seconds``: new tick interval, used from the next tick on. ``reason``: free text recorded on the strategy's audit log. REFUSED (returns ``immutable_config_key``): ``target_token`` / ``source_token`` / ``tracked_wallet`` / ``venue`` / composite ``definition``. These define WHAT the strategy trades -- editing them in place would desync the executor's position bookkeeping or strand an open perp leg on the venue it was opened against. Cancel and create a new strategy for those. A STOPPED strategy is final and cannot be modified; a paused one can (the edit does not resume it -- use strategy_resume). The merged config is dry-run through the st…

Create a momentum strategy -- fast/slow SMA crossover entry/exit. Buys on a bullish cross (fast SMA > slow SMA), sells on a bearish cross. DISCRETIONARY (SEC framework): the model interprets a signal and converts it to a trade, so targeting a tokenized SECURITY forces per-execution user confirmation before the scheduled dispatcher will run a tick (``strategies.tasks.execute_strategy`` requires ``user_confirmed=True``; crypto targets stay fully autonomous). Call asset_classification first. ``risk`` / direction params: see ``strategy_dca_create``.

Manually pause a strategy (status=paused_manual; stops dispatch).

Create a perp-grid strategy -- a ladder of perp LONGS accumulated on dips. Routes through the multi-venue perps VENUE ADAPTER (hard rule 2; Jupiter Perps primary). Around a rolling center price (SMA, or an explicit ``center_price``), each ``grid_spacing_pct`` move below center is one rung; crossing a deeper rung opens a perp long sized ``usd_per_level`` at ``leverage``. PAUSES new rungs in a trending (bull/bear) regime and closes the ladder in a bear (stop the bleed); tightens spacing in range, widens when volatile. Only an asset with a mapped perp market (currently SOL) can open -- see get_venue_status for routable markets. ``venue`` optional (defaults to the configured primary); a Tier B (custodied) venue needs ``acknowledge_tier_b=true`` after reviewing its ``custody_disclosure``. ``risk``: see ``strategy_dca_create``.

Create a downside-protection monitor on a held position. Shares the stop-loss executor -- identical config/mechanics to ``strategy_stoploss_create`` -- framed as a pure downside guard. At least one of ``stop_loss_pct`` / ``take_profit_pct`` / ``trailing`` must be set.

Create a portfolio-rebalance strategy toward ``target_allocation`` (mint->weight). Direction (optional, deterministic signal): ``direction_mode`` / ``allow_short`` / ``regime_override`` -- see ``strategy_dca_create``.

Re-enable a paused strategy (manual re-enable after a drawdown pause). The drawdown kill switch latches a strategy to ``paused_drawdown`` and requires this explicit owner action to resume; the equity high-water mark is reset so it does not immediately re-trip.

Create a sentiment strategy -- trades an aggregate sentiment score. Buys when the score is >= ``bull_threshold`` (flat), sells when it is <= ``bear_threshold`` (holding); the neutral band holds. The score is sourced live from market intelligence each tick, or pinned via ``sentiment_score``. DISCRETIONARY (SEC framework): targeting a tokenized SECURITY forces per-execution ``user_confirmed`` at execution (crypto stays fully autonomous). Call asset_classification first. ``risk`` / direction params: see ``strategy_dca_create``.

Create a snipe/scalping strategy -- dip-buy with a fast take-profit/stop exit. Flat: buys ``usd_per_buy`` when price is ``entry_dip_pct`` below the close ``lookback`` ticks ago. Holding: exits on a tight ``take_profit_pct`` OR ``stop_loss_pct`` -- many small round-trips. Runs on a short interval (default 60s) since it reads a per-tick rolling price window that must accumulate ``lookback`` + 1 observations before it can enter. ``risk`` / direction params: see ``strategy_dca_create``.

Status + last execution of one strategy (scoped to the caller's wallet).

Create a stop-loss / take-profit / trailing-stop monitor on a held position. ``position_amount`` is base units of ``target_token`` to liquidate on trigger. At least one of ``stop_loss_pct`` / ``take_profit_pct`` / a trailing config should be set (fractions, e.g. 0.15 == 15%). Direction (optional, deterministic signal): ``direction_mode`` / ``allow_short`` / ``regime_override`` -- see ``strategy_dca_create``.

Create a vault strategy -- a target-allocation basket held via rebalancing. Shares the rebalance executor -- identical config/mechanics to ``strategy_rebalance_create`` (``target_allocation`` mint->weight, ``drift_threshold_pct``) -- framed as a passive basket rather than an active rebalance loop. No external vault/LP deposit (hard rule 1): the non-custodial swap pipeline only rotates spot holdings toward the target weights. Direction (optional, deterministic signal): ``direction_mode`` / ``allow_short`` / ``regime_override`` -- see ``strategy_dca_create``.

Create a yield-farm strategy -- maintains a target basket allocation. Shares the rebalance executor (config identical to ``strategy_rebalance_create``): depositing into an external yield protocol / LP position has no faithful swap-pipeline analogue, so this models a yield farm as keeping a target allocation across the basket via converging rebalance swaps (hard rule 1: the non-custodial pipeline only rotates spot holdings, never deposits externally). Direction (optional, deterministic signal): ``direction_mode`` / ``allow_short`` / ``regime_override`` -- see ``strategy_dca_create``.

Historical parameter observations for one of YOUR strategies (free read). Compares the strategy's realised outcomes against your other strategies of the same type that ran different parameter values, and returns the observed differences ranked by realised P&L -- historical performance data only, never advice, and nothing is changed by this call (PROPOSE flow: acting on an observation is your call via the strategy tools, where every policy/risk gate still applies). Workflow: ORIENT -> DECIDE step -- review observations, then adjust via strategy tools if YOU decide to.

Token metadata, price, liquidity, volume, holder count. Provide token_address (mint) or a known symbol. Merges Helius (metadata) with Birdeye (market data). Free (no technology service fee) -- a read with no transaction notional.

Spot-trade a tokenized equity (xStocks / Ondo) via Jupiter, non-custodial. side: buy | sell. amount is in base units of the INPUT token (USDC 6dp for a buy, the equity token for a sell). These are tokenized SECURITIES: the call is geo-gated (Reg S = no US persons; declare jurisdiction once via the jurisdiction arg) and OFAC-screened, and requires per-execution confirmation -- WITHOUT confirm=true it returns a quote + disclaimer and does NOT execute (no autonomous equity execution). With confirm=true it returns an UNSIGNED base64 tx to sign + broadcast; pass signed_transaction to broadcast a caller-signed tx. Value-bearing: past the daily free tier an x402 payment_header is required. ip = caller origin IP for the Reg S geo gate (US IP -> refused even with an attestation; an agent's Railway Singapore egress resolves to SG and passes). ``venue_hint`` is ADVISORY, never required -- equity routes via the issuer registry (one surface today); an unknown hint raises. ``idempotency_key`` (optional): see jupiter_swap -- same replay-on-retry semantics, same key reused across build + broadcast. ``verify`` (extending default True): when broadcasting (signed_transaction supplied), await on-chain confirmation and re-read the equity mint 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.

Withdraw a published journal card (free write). Publishing a decision with share_journal_card is an explicit act by the owner; this is the equally explicit act of taking it back. After this call, the public card at its card_url and the OG-image asset both 404 immediately -- the row is private again, exactly as it was before the first publish. Wallet-scoped like every other Layer 1 tool: you can only unpublish a decision your own wallet owns. Calling this on a decision that is already private (or was never published) is a safe no-op, not an error -- ``unpublished`` in the response tells you whether a withdrawal actually happened. The cached OG image, if one was generated, is left on disk (not deleted) -- the public routes gate on publication state, not file presence, so the takedown is immediate either way, and a later re-publish of the same decision reuses the image instead of paying to regenerate it. Workflow: the symmetric undo of share_journal_card.

Unstake an LST back to SOL (non-custodial). lst_token is a mint (mSOL/jitoSOL/bSOL); amount in base units. mSOL routes via Marinade, others via the Sanctum router. Returns an UNSIGNED base64 tx. The technology service fee is charged on the unstaked-LST notional past the daily free tier (x402 payment_header). ``idempotency_key`` (optional): a client-generated UUID. Retrying with the same key + same args replays the original result instead of re-unstaking. Reuse the SAME key across the build call and its ``signed_transaction`` completion call -- see liquid_stake; the two legs dedupe independently, so this never raises IDEMPOTENCY_CONFLICT. ``signed_transaction`` / ``verify`` (two-phase execution): see liquid_stake -- re-call with the signed tx and Crank broadcasts it, confirms it on-chain, and re-reads the LST + SOL balances.

Patch an agent profile's metadata (display_name, capabilities, endpoints). metadata is a dict of writable fields; capabilities are validated if present.

Side-by-side risk comparison of two venues for a routing decision. Read-only. Returns each venue's full risk record, the safer venue, and the composite-score delta. e.g. compare "jupiter" vs "pacifica" before routing.

Multi-layer authenticity check for a token mint (read-only, no execution). Runs the same five-layer verification the swap/trade tools enforce before building a transaction: registry allow-list, Jupiter verified list, Metaplex metadata authority, minimum liquidity, and token age + holder count. Returns verification_status (verified | unverified | suspicious | blocked), the reasons, non-blocking warnings, and the per-layer findings. Call this before swapping into an unfamiliar token.

Verify any prior transaction signature on demand (FREE read). Post-trade verification (harness spec R13): awaits on-chain confirmation of ``tx_signature`` at ``commitment`` level (up to ``timeout_s``) and, when a state hint is supplied, re-reads the relevant state to compare against what was expected: - ``mint`` (+ ``wallet_address``): re-reads that SPL/SOL token balance. - ``market`` (+ ``wallet_address``): re-reads the Drift perp position. - ``protocol`` (+ ``wallet_address``, optional ``market`` / ``marginfi_account``): re-reads the lending obligation health. Returns ``{confirmed, slot, commitment, post_state, expected_vs_actual, retry_guidance}``. ``confirmed`` is False (never True) on a timeout -- NEVER treat an unconfirmed/timed-out result as success; ``retry_guidance`` names the next step. Use this after signing + broadcasting a transaction yourself (place_perp_order, lend_deposit/borrow/repay, and every other unsigned-tx tool never broadcast server-side) to confirm it actually landed before treating the position/balance as changed.

On-chain proof the treasury actually received settled x402 USDC. Wires ``services.x402_settlement.verify_treasury_settlement`` ( real on-chain proof: treasury USDC ATA balance read as the primary signal, plus settle-tx signature confirmation) up to an MCP tool -- the follow-up to which intentionally split the on-chain proof logic from this wiring to avoid file collisions across parallel sessions. ``signatures`` is optional: when omitted, this tool pulls recent settled ``X402PaymentRecord.tx_signature`` values itself (via ``django_bridge.recent_x402_signatures``, same window shape as ``reconcile_x402_settlement``) over the last ``since_iso`` window (or all time), capped at ``signature_limit`` to bound RPC round trips -- so a caller does not have to hand-assemble signatures to get a real proof. Pass an explicit ``signatures`` list to check specific settle-tx hashes instead (bypasses the DB lookup entirely). ``verified`` is True only when every checked signature confirms on-chain AND (if ``expected_usd`` is given) the treasury balance covers it -- see the service docstring for the full non-falsely-asserting contract. Raises CONFIG_ERROR if no treasury wallet is configured, UPSTREAM_ERROR (retryable) on an RPC failure -- never a silent ``verified=False``. FREE read (never gated, never in x402 PAID_TOOLS): public addresses/ signatures/balances only, never a key (hard rule 1).

Current state, policy summary, recent activity, total volume, and tier.