Kash — Prediction Markets CLI#

Official command-line interface for the Kash prediction-market protocol. This skill teaches you how to drive the kash binary against real markets — placing trades, reading positions, and managing webhook deliveries — all from a single CLI.

🧪 Staging release. Today only kash_test_* keys work; the CLI auto-routes them to https://api-staging.kash.bot/v1. Production endpoints and self-service key issuance land with v1.0. Request a staging key by emailing engineering@kash.bot with your use case.

Trust model — non-custodial by construction#

Every Kash path is non-custodial: Kash never holds funds, never moves funds, never holds keys, and never signs anything. User funds always live in Privy-managed MPC smart accounts the user controls. The CLI holds zero balances; the API key is a scoped, revocable delegation the user issues against their own account. See SECURITY.md § Non-custodial design for the full statement.

Install#

sh

npm install -g @kashdao/cli@latest

Requires Node.js 22+. Verify:

sh

kash --version

Authenticate#

Store the API key once:

sh

kash auth set-key kash_test_…

Persisted to ~/.kash/config.json at mode 0600. The CLI never writes the raw key to disk in any other location. To override per-shell without persisting, set KASH_API_KEY in the environment.

Core commands#

Every command supports --json for stable machine-readable output (single object on stdout; errors on stderr with the documented Kash error envelope). Pin to --json --quiet for AI-agent flows.

Browse markets#

sh

# List active markets
kash markets list --status ACTIVE --limit 20 --json

# Get one market's full state
kash markets get <market-id> --json

Quote before trading#

Quotes simulate price impact without moving funds:

sh

# How much YES will $10 USDC buy?
kash quote buy <market-id> --outcome 0 --amount 10 --json

# How much USDC do I get for 5 outcome tokens?
kash quote sell <market-id> --outcome 0 --tokens 5 --json

Trade lifecycle#

sh

# Buy and wait for terminal status (executed | failed | rejected)
kash trade buy <market-id> --outcome 0 --amount 10 --wait \
  --auto-idempotency-key --json

# Inspect a trade
kash trade status <trade-id> --json

# List recent trades
kash trade list --limit 50 --filter status=executed --json

# Close a position
kash trade sell <market-id> --outcome 0 --amount 5 --wait \
  --auto-idempotency-key --json

--auto-idempotency-key is mandatory in agent flows — it makes the request safe to retry; replays return the cached response, so network blips never double-execute a trade.

High-value confirmation#

Trades above the key's high_value_threshold_usdc return a two-phase response:

sh

# 1. Submit (returns pending_confirmation + a one-time token)
RESP=$(kash trade buy <market-id> --outcome 0 --amount 5000 --json)
TOKEN=$(echo "$RESP" | jq -r '.confirmation.token')
TRADE_ID=$(echo "$RESP" | jq -r '.id')

# 2. Confirm with the token (60s window)
kash trade confirm "$TRADE_ID" --token "$TOKEN" --json

Portfolio#

sh

# Smart-account state, USDC balance, position summary
kash portfolio show --json

# Open positions across markets
kash portfolio positions --json

Webhooks#

sh

# List recent deliveries
kash webhooks list --limit 10 --json

# Redeliver a specific event
kash webhooks redeliver <event-id> --json

# Rotate the webhook signing secret (60s cooldown)
kash webhooks rotate-secret --json

Request tracing#

Every API response carries a requestId. Use it to walk the end-to-end event chain across services:

sh

kash trace <correlation-id> --json

Self-orchestrated direct-to-chain mode#

The CLI also wraps @kashdao/protocol-sdk for fully self-orchestrated trading — bring your own RPC, signer, and (optionally) bundler; the Kash backend isn't in the path at all.

sh

# Read the on-chain market state via your RPC
kash protocol market <market-address> --json

# Quote on-chain
kash protocol quote <market-address> --side buy --outcome 0 \
  --amount 10 --json

Profile fields needed for protocol mode: rpcUrl, smartAccount, optionally bundlerUrl/ bundlerProvider, and signerKeyRef ( file:<path> or env:<NAME> — the raw key never persists).

Error handling#

Every error envelope follows the same shape:

json

{
  "ok": false,
  "error": {
    "code": "STABLE_ERROR_CODE",
    "message": "Human-readable summary",
    "recoverable": true,
    "suggestion": "Concrete next step",
    "retryAfterMs": 5000,
    "actions": [{ "type": "wait_and_retry", "delayMs": 5000, "description": "…" }],
    "requestId": "uuid",
    "docsUrl": "https://docs.kash.bot/developer-docs/api-errors/…"
  }
}

Branch on actions[0].type for machine-readable recovery: wait_and_retry, run_command, set_env, open_url, check_input. Or look up kash explain <CODE> for a structured catalog entry.

Useful flags for agent flows#

FlagPurpose--jsonStable machine-readable output. Always use in agent flows.--quietSuppress progress logs; only the final JSON object on stdout.--auto-idempotency-keyAuto-generate Idempotency-Key. Mandatory for trade write paths.--waitBlock until terminal status. Pairs with --wait-timeout-ms.--profile <name>Select a named profile (multi-account / multi-env workflows).--base-url <url>Override the auto-routed base URL.--timeout-ms <n>Override the per-request timeout (default 30s).

Reference#

• Full command reference: kash docs --json (returns the full command tree as machine-readable JSON) or the Mintlify-rendered pages at https://docs.kash.bot/developer-docs/cli.
• REST API reference: https://docs.kash.bot/developer-docs/rest-api/overview
• Error catalog: https://docs.kash.bot/developer-docs/api-errors
• GitHub: https://github.com/KashDAO/cli
• npm: https://www.npmjs.com/package/@kashdao/cli
• Support / staging-key requests: engineering@kash.bot