Authentication & x402

Crank has no API keys and no accounts to create before you start. Authentication is about two things:

1. Wallet binding — proving which public wallet an action belongs to.
2. Payment — settling the technology service fee for value-bearing actions via the x402 payment rail.

Reads need neither. You can call every free read tool anonymously.

Wallet binding

Crank is non-custodial. It only ever handles public keys. No code path transmits, persists, or logs a private key or seed phrase.

• The wallet a value-bearing action belongs to is taken from the top-level wallet_address argument, never inferred from inside a tool's other arguments.
• wallet_address is always a public key you supply.
• Value-bearing tools return an unsigned transaction (or, for venue-custodied Tier-B perps venues, a signing payload). You sign it with your own key, in your own process, and broadcast it. Crank never signs for you.

That is the whole binding model: you assert the public key, you keep the private key, you sign locally.

Free tier vs. paid

Each caller gets a daily free-tier allowance of value-bearing calls before the payment gate activates. The gate classifies every tool:

• Free tools — all reads (quotes, balances, market data, discovery, classification, usage reports). Always $0, no payment ever required.
• Paid tools — value-bearing actions (swaps, perps, lending, staking, shorting, equity trades, fiat on/off-ramp, premium intelligence tiers).

When you call a paid tool, the gate returns one of three outcomes:

Reason	Meaning
disabled	Billing is off for this deployment; call proceeds free.
free_tier	Within your daily allowance; call proceeds free. The response reports free_tier_remaining.
paid	Allowance exhausted; the technology service fee applies.

The x402 payment flow

When a fee is owed and no valid payment is attached, the call fails with a PAYMENT_REQUIRED envelope (an HTTP 402-style result):

{
  "ok": false,
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Payment required for jupiter_swap",
    "fee_usd": 0.18,
    "facilitator": "https://facilitator.example/...",
    "accepts": [ { "scheme": "exact", "network": "solana", "asset": "USDC", "amount": "..." } ]
  }
}

Steps:

1. Quote. Read fee_usd and the accepts payment requirements from the PAYMENT_REQUIRED envelope.
2. Pay. Construct an x402 payment for that amount in USDC on Solana.
3. Retry. Call the tool again with the payment_header argument set to your x402 payment payload.
4. Verify & settle. Crank verifies the payment through the Coinbase CDP facilitator. The facilitator moves the USDC straight to the Crank treasury — Crank never holds your funds in between. The verified call then executes and returns the unsigned transaction.

The fee is a technology service fee, charged as a percentage of the action's notional value, with a per-action floor. Exact rates, tiers, and discounts: Fee schedule.

Pay in $CRANK for a discount

Value-bearing tools accept pay_in_crank=true. Paying the technology service fee in $CRANK applies an additional discount that stacks multiplicatively with any staker discount. See the Fee schedule.

Premium feature billing

Some intelligence tools (get_market_briefing pro/platinum tiers, get_consensus, get_contrarian_signals) are flat per-call premium features rather than percentage-of-notional. They are covered by an active $CRANK-staker subscription, or you pay the per-call x402 fee with payment_header. The billing outcome is reported in the response billing field. Pricing model and cost basis: see docs/X402_COSTING.md.

Agent wallet provisioning (managed wallets)

For autonomous agents you can provision a managed wallet: a non-custodial control plane that applies policy guardrails to an agent's public wallet. This does not give Crank custody — it governs what actions the policy gate will allow.

Tool	Purpose
create_agent_wallet	Provision a managed wallet for an agent_id, optionally with a policy preset (conservative / balanced / aggressive). Supply the agent's public key, or omit it to create a pending record.
set_wallet_policy	Set trading limits: max_trade_size, daily_limit, approved_tokens, banned_tokens, position_limit, kill_switch, drawdown_limit.
wallet_status	Current state, policy summary, recent activity, total volume, and fee tier.
kill_wallet	Emergency freeze: the policy gate then refuses every value-bearing action for that wallet.

The policy gate runs before the x402 fee is ever charged, so an agent is never billed for a trade that policy will refuse. Hosted scoped-key signing (Turnkey) is provisioned separately; until then a managed strategy returns an unsigned transaction per due tick for the owner to sign.

create_agent_wallet puts that choice explicitly in your hands via the wallet_address argument. Omit it and Crank provisions a Turnkey TEE-managed signer: the agent can trade autonomously between due-tick windows with no owner present, but the key is generated and held inside Turnkey's enclave and is not exportable by design — not a current limitation, but a deliberate security posture (the platform cannot get the key out even if asked). Supply wallet_address and you keep self-custody instead: the key is fully portable and stays wherever you generated it, but every transaction still needs the owner to sign it, so there is no unattended autonomous ticking. Choose TEE-managed signing when autonomy matters more than key portability, and self-signing when portability matters more than autonomy. Full security rationale for the non-exportability posture: Key & recovery security.

Error codes you will see

Code	Meaning
PAYMENT_REQUIRED	Fee owed; attach payment_header and retry.
POLICY_VIOLATION	A managed-wallet policy limit was breached.
KILL_SWITCH_ACTIVE	Platform-wide emergency stop engaged.
SOFT_LAUNCH_BLOCKED	Pre-mainnet rollout control blocked the action.
UNVERIFIED_TOKEN	Target token failed authenticity checks (override with allow_unverified=true where offered; hard scam signals are never overridable).
UNSAFE_TRANSACTION	Constructed transaction touched a program outside the known-good allow-list.
CONFIG_ERROR	The payment facilitator is not configured for this deployment.