Crank Protocol

Write a new version of the wallet's portfolio charter (free control-plane write). Creates a new active version -- the prior version stays in history, never deleted (versioned mandate, not an in-place overwrite). risk_band is one of conservative|balanced|aggressive. banned_tokens merge into AgentWallet.evaluate_trade as an ADDITIONAL deny source alongside WalletPolicy.banned_tokens -- an active WalletPolicy always wins when it is the stricter rule; a charter can never loosen an existing policy, and a conflict comes back in the response's `warnings` (logged server-side, never silently dropped). target_allocations is {token: percent}, must sum to <=100. objectives/cadence are free-form parameters -- never phrase them as return promises (hard rules 5-8). Setting an escalation_webhook mints a platform-generated escalation_webhook_secret used to HMAC-SHA256-sign every escalation POST (X-Crank-Signature over "{timestamp}.{body}"). The RAW secret is returned exactly once -- in this write's response -- so the receiver can be configured; every later read returns it masked. It is carried forward unchanged when the URL is unchanged, rotated automatically when the URL changes, and rotated on demand with rotate_escalation_secret=true. It is a receiver-authentication credential, never wallet key or seed material (hard rule 1). Workflow: ORIENT step 0 -- set once at the start of a relationship with an agent/wallet; strategies read it on every execute_strategy tick (see get_trading_workflow). Permission mode: a configuration write -- allowed in every permission_mode, observe included; the ladder gates value-bearing actions, not config.

Configure per-token trading caps (TradingLimit) on the caller's agent wallet. limits: a list of {token_address, max_position_size?, max_single_trade?, daily_volume_limit?} objects, USD amounts (> 0, up to 6 decimals). Upserts by token_address; only the cap keys you include are written -- an omitted key keeps its stored value, an explicit null clears it (uncapped). Returns the full updated set read back from the server, plus ``enforcement`` (which rails read each column today). Pure Django write: unlike set_wallet_policy there is no Turnkey enclave re-push. On a Lane 2 wallet, raising or clearing an existing cap is refused (POLICY_VIOLATION) -- the owner loosens it from their authenticated session. Tightening always applies. Permission mode: a configuration write -- allowed in every permission_mode, observe included (same class as set_wallet_policy).

Configure the caller's own trading limits and rules on an agent wallet. policies: a list of {policy_type, value, enabled?} objects. policy_type is one of max_trade_size {"usd"} | daily_limit {"usd"} | approved_tokens {"tokens"} | banned_tokens {"tokens"} | position_limit {"usd"} | kill_switch {"active"} | drawdown_limit {"max_pct"} | max_daily_loss {"usd"} | trade_velocity {"max_per_hour", "max_per_day"} | venue_allowlist {"venues"}. Upserts by policy_type; returns the full updated policy set. perp_leverage_limit {"max_leverage": "5"} (caps the leverage a perp open may request, >= 1; above it is rejected, never clamped -- "no perps" is disabled_actions ["perp_open"]). On a Lane 2 wallet, a change that would LOOSEN a server-enforced default raises BROWSER_CONFIRMATION_REQUIRED -- call request_wallet_policy_loosening instead. Permission mode: a configuration write -- allowed in every permission_mode, observe included; the ladder gates value-bearing actions, not config.

Pre-filled post for a journal card, ready to publish (free read). Returns the same card as get_journal_card plus a platform-shaped share payload: post text within the platform's character limit, the public card URL, and a compose-intent URL. ``platform`` is x | farcaster | generic. The copy is about YOUR process -- what your agent decided, that the rationale was written down before the outcome, and that the record is checkable on-chain. It never states or implies a return. THIS CALL PUBLISHES THE DECISION. Your journal is private by default; calling this marks THIS decision publicly readable at its card URL so the link in the post resolves for anyone (and for answer engines). Nothing else is published -- not your other decisions, not amounts, not your journal body unless include_rationale=true. Reviewing with get_journal_card publishes nothing. Workflow: SHARE step -- get_journal_card to review, this to publish.

Close a tracked short: buy token -> repay loan -> withdraw collateral. Returns an ORDERED STEP PLAN + exit price. short_id from short_open. Past the daily free tier an x402 payment_header is required. ``jurisdiction``: closes are geo-gated too -- see short_open. ``idempotency_key`` (optional): a client-generated UUID. Retrying with the same key + same args replays the original result instead of re-closing the short.

Open a lending-based short: deposit collateral -> borrow token -> sell. Returns an ORDERED STEP PLAN of UNSIGNED base64 txs to sign + broadcast in sequence, plus entry price + health factor + a short_id for tracking. All amounts in base units. The shorted token is authenticity-verified first; set allow_unverified=true to short an unverified mint at your own risk. Past the daily free tier an x402 payment_header is required. ``jurisdiction``: your ISO-3166-1 alpha-2 country code, self-declared -- synthetic shorting is geo-gated (no US persons, unknown jurisdiction DENIED). Declare once here (or via ``declare_jurisdiction``/``trade_equity``/perps tools) and it is remembered 90 days. ``idempotency_key`` (optional): a client-generated UUID. Retrying with the same key + same args replays the original result instead of re-opening the short.

List open shorts for a wallet with entry price + health factor.

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. (spec s7.1): resuming a PERPS-CAPABLE strategy (perp_grid / basis_trade / allow_short / short_only) re-runs the perps jurisdiction gate first -- a wallet whose jurisdiction no longer passes (US / unknown / expired / OFAC / AU) cannot re-engage a paused perps strategy.

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

Submit the OWNER-SIGNED ``register_identity`` transaction and complete the binding. Submits the transaction, then VERIFIES on chain before stamping anything: the account at ``identity_pda`` must be OWNED by the AGNTA agent-registry program, carry the AgentIdentity discriminator, AND carry this wallet's own authority pubkey. Only then does the wallet move ``pending`` -> ``registered``. A signature string is never treated as proof, and an agent can never self-assert its own binding. A duplicate submit is not an error -- the on-chain check decides; when the account is not yet visible the wallet stays ``pending`` and the caller polls poll_agnta_identity_registration. Non-custodial (hard rule 1): ``signed_transaction_base64`` is the owner's PUBLIC signed artefact -- Crank never sees, stores or logs a key or seed.

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).