Trade prediction markets non-custodially via the official KashDAO CLI (@kashdao/cli) — markets list/get, quotes, trade buy/sell with idempotency + high-value...
---
name: kashdao-cli
description: Trade prediction markets non-custodially via the official KashDAO CLI (@kashdao/cli) — markets list/get, quotes, trade buy/sell with idempotency + high-value confirmation, portfolio + webhooks management, and request tracing. Both Kash-orchestrated (REST API) and self-orchestrated (direct-to-chain via @kashdao/protocol-sdk) modes from a single binary.
version: 0.1.0
metadata:
openclaw:
requires:
env: [KASH_API_KEY]
bins: [kash]
primaryEnv: KASH_API_KEY
envVars:
- name: KASH_API_KEY
required: true
description: Kash API key. `kash_test_*` prefix auto-routes to the staging environment (api-staging.kash.bot); `kash_live_*` routes to production (lands at v1.0). Request one by emailing `engineering@kash.bot` with your intended use case.
- name: KASH_BASE_URL
required: false
description: Override the auto-routed API base URL. Use only when you want to pin a specific environment regardless of the key's prefix.
- name: KASH_PROFILE
required: false
description: Select a named CLI profile from `~/.kash/config.json`. Defaults to `default`.
install:
node: '@kashdao/cli@latest'
emoji: '🎯'
homepage: https://github.com/KashDAO/cli
os: [macos, linux, windows]
---
# Kash — Prediction Markets CLI
Official command-line interface for the [Kash](https://kash.bot)
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](https://github.com/KashDAO/cli/blob/main/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](https://docs.kash.bot/developer-docs/api-errors)).
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
| Flag | Purpose |
| ------------------------ | ----------------------------------------------------------------- |
| `--json` | Stable machine-readable output. Always use in agent flows. |
| `--quiet` | Suppress progress logs; only the final JSON object on stdout. |
| `--auto-idempotency-key` | Auto-generate `Idempotency-Key`. Mandatory for trade write paths. |
| `--wait` | Block 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`
don't have the plugin yet? install it then click "run inline in claude" again.
added structured intent, inputs with setup guidance, decision points for idempotency/high-value flows/error recovery/profiles, explicit output contract for each command, and outcome signals for verification, preserving all original procedure steps and non-custodial trust model.
use the kash CLI to execute non-custodial prediction market trades, read market data, manage positions, and handle webhooks. trades never touch Kash servers with your funds; the API key is a scoped delegation against your own Privy-managed smart account. use this skill when you need to browse markets, place or close trades with atomicity guarantees, get real-time quotes, check your portfolio, or manage webhook subscriptions. the CLI supports both Kash-orchestrated REST mode and fully self-orchestrated direct-to-chain mode via @kashdao/protocol-sdk.
node --version.kash auth set-key. stores API key at mode 0600 and named profiles. can be manually edited to add protocol-mode fields (rpcUrl, smartAccount, bundlerUrl, signerKeyRef).kash markets list.kash markets get.install the CLI. run npm install -g @kashdao/cli@latest. verify with kash --version. requires Node.js 22+.
authenticate once. run kash auth set-key kash_test_… (staging) or kash auth set-key kash_live_… (production). the key is written to ~/.kash/config.json at mode 0600. alternatively, set KASH_API_KEY in the environment to override per-shell without persisting.
list active markets (optional, for discovery). run kash markets list --status ACTIVE --limit 20 --json to see market summaries. output includes market-id, outcome labels, current odds, and liquidity. default limit is 10; raise --limit to fetch more.
get a single market's full state (optional, for detailed inspection). run kash markets get <market-id> --json. output includes all outcomes, order book snapshot, settlement rules, and market-specific metadata. use when evaluating a specific market before trading.
quote the trade before executing (mandatory for production trades). run kash quote buy <market-id> --outcome 0 --amount 10 --json to see how many tokens you'll receive, or kash quote sell <market-id> --outcome 0 --tokens 5 --json to see how much USDC you'll get back. quotes simulate price impact without moving funds. always check the quote's slippage and effective price against your risk tolerance.
buy outcome tokens. run kash trade buy <market-id> --outcome 0 --amount 10 --auto-idempotency-key --wait --json. the --auto-idempotency-key flag auto-generates a stable request ID; the --wait flag blocks until the trade reaches a terminal status (executed, failed, or rejected). output includes trade-id, filled amount, actual price, and final status. store the trade-id for later inspection or reconciliation.
poll a trade's status (if not using --wait). run kash trade status <trade-id> --json to check execution status. returns the trade's current state, filled amount, and any rejection reason. terminal states are executed, failed, and rejected.
list recent trades (optional, for portfolio review). run kash trade list --limit 50 --filter status=executed --json to fetch trades matching a filter. default limit is 20. filters include status (executed, failed, rejected, pending) and market-id.
close a position (sell outcome tokens). run kash trade sell <market-id> --outcome 0 --tokens 5 --auto-idempotency-key --wait --json. output includes sale proceeds in USDC and realized P&L. use --tokens to specify the number of tokens to sell, or omit to close the entire position.
handle high-value confirmation (if applicable). if the trade amount exceeds your account's high_value_threshold_usdc, the response includes a pending_confirmation status and a one-time confirmation token (valid 60 seconds). extract the token with echo "$RESP" | jq -r '.confirmation.token' and the trade-id with echo "$RESP" | jq -r '.id'. then run kash trade confirm <trade-id> --token <TOKEN> --json to finalize the trade. if the 60-second window expires, the trade is auto-rejected and you must retry.
check your portfolio state. run kash portfolio show --json to get your smart-account state, USDC balance, and position summary. run kash portfolio positions --json to list all open positions across markets, including outcome, token count, entry price, and current mark price.
manage webhooks (optional, for real-time event delivery). run kash webhooks list --limit 10 --json to list recent webhook deliveries. run kash webhooks redeliver <event-id> --json to manually redeliver a specific event. run kash webhooks rotate-secret --json to rotate the webhook signing secret (60-second cooldown between rotations).
trace a request (optional, for debugging). run kash trace <correlation-id> --json to walk the end-to-end event chain across services. every API response includes a requestId; use it as the correlation-id argument.
self-orchestrated direct-to-chain mode (optional, advanced). populate rpcUrl, smartAccount, and optional bundlerUrl/signerKeyRef fields in a named profile in ~/.kash/config.json. then run kash protocol market <market-address> --json to read on-chain market state, or kash protocol quote <market-address> --side buy --outcome 0 --amount 10 --json to quote on-chain. the Kash backend is not in the path; you bring your own RPC and signer.
if using agent flows (bots, scheduled tasks, etc.): always add --auto-idempotency-key to trade buy/sell/confirm commands. this makes the request safe to retry; replays return the cached response, preventing double-execution on network retries.
if trade amount exceeds high_value_threshold_usdc: the trade returns pending_confirmation status instead of immediately executing. extract the confirmation.token and trade-id, then call kash trade confirm within 60 seconds with the token. if the window expires, the trade is rejected and must be re-submitted.
if quote or trade fails with a recoverable error (e.g., RATE_LIMITED, GATEWAY_TIMEOUT, INSUFFICIENT_LIQUIDITY): check the error envelope's actions array. if actions[0].type is wait_and_retry, sleep for retryAfterMs and retry the same request (with the same idempotency key if it's a write). if the action is run_command or set_env, follow the suggestion. for non-recoverable errors (INVALID_MARKET_ID, INSUFFICIENT_BALANCE), do not retry; fix the input and resubmit.
if you need to switch accounts or environments: create a named profile in ~/.kash/config.json with separate API keys, RPC URLs, and smart-account addresses. then use --profile
if direct-to-chain (protocol) mode is needed: add rpcUrl, smartAccount, bundlerUrl (optional), and signerKeyRef (file:
if the API key has been compromised: run kash auth revoke immediately and request a fresh key. revoked keys are deactivated server-side within 1-2 minutes.
if the webhook signing secret must be rotated: run kash webhooks rotate-secret --json. a 60-second cooldown applies between rotations. new deliveries use the rotated secret; old events may still carry the previous secret for up to 5 minutes.
markets list: array of market objects, each with id, title, outcome_labels (array), current_odds (array of floats), total_liquidity_usdc, status (ACTIVE, CLOSED, SETTLED), and market_type.
markets get: single market object with all fields above plus order_book (bids and asks per outcome), settlement_rules, created_at, and market-specific metadata.
quote buy/sell: object with input_amount, output_amount, price_per_token, slippage_percentage, and effective_price.
trade buy/sell/confirm: object with id (trade-id), market_id, outcome, filled_amount, actual_price, status (executed, failed, rejected, pending_confirmation), confirmation (if pending_confirmation, includes token), timestamp, and requestId.
trade status: single trade object with the same fields as trade buy/sell.
trade list: array of trade objects matching the filter, each with id, market_id, outcome, filled_amount, status, and timestamp. sorted by timestamp descending.
portfolio show: object with smart_account_address, usdc_balance_usdc, total_positions_count, and positions_summary (array).
portfolio positions: array of position objects, each with market_id, outcome, token_count, entry_price, current_mark_price, and unrealized_pnl_usdc.
webhooks list: array of delivery objects, each with event_id, event_type, market_id, timestamp, status (delivered, failed, pending_retry), and http_status.
webhooks redeliver: object with event_id, status (queued_for_redelivery), and scheduled_at.
webhooks rotate-secret: object with new_secret_hint (first 8 chars only), rotated_at, and cooldown_remaining_ms.
trace: object with correlation_id, events (array of timestamped service events), and end_to_end_duration_ms.
protocol market: on-chain market state object with contract_address, outcomes (array), order_book, and liquidity_pools.
protocol quote: object with input_amount, output_amount, gas_estimate_wei, slippage_percentage.
error envelope (all commands): object with ok (false), error (code, message, recoverable boolean, suggestion, retryAfterMs, actions array, requestId, docsUrl).
all JSON output is a single object or array on stdout; errors and logs go to stderr. use --quiet to suppress logs.
kash --version: prints the installed CLI version. confirms the binary is in PATH and Node.js 22+ is available.
kash markets list --json: returns a non-empty array of market objects within 3 seconds. confirms API key is valid and staging/production routing is working.
kash quote buy|sell: returns a quote object with non-zero filled_amount and a well-defined price. confirms the market exists, is liquid, and you can submit a trade.
kash trade buy|sell --wait: command blocks until status is executed, failed, or rejected. trade-id is present in the response. confirms the trade was submitted and reached a terminal state.
kash trade status: returns a trade object with the trade-id and current status. status changes from pending to executed (or failed/rejected) within 5-30 seconds for normal market conditions.
kash trade confirm: if the high-value confirmation flow was triggered, the confirm command returns status executed (or failed if the token expired or was invalid). confirms the two-phase flow completed successfully.
kash portfolio show: returns a non-null usdc_balance_usdc and smart_account_address. confirms your account is readable and the smart account is active.
kash portfolio positions: returns an array of open positions. each position has a positive token_count and a current_mark_price. confirms all holdings are visible and marked to market.
kash webhooks list: returns an array of recent deliveries with timestamps and statuses. confirms webhooks are configured and firing.
kash webhooks rotate-secret: returns a new_secret_hint and rotated_at timestamp. confirms the webhook signing secret was rotated server-side.
kash trace: returns an events array with service-to-service timings and no null values. confirms end-to-end tracing is enabled and request-id was found.