intent

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.

inputs

• KASH_API_KEY (required, string): staging key (kash_test_*) or production key (kash_live_*). email engineering@kash.bot to request. keys are scoped and revocable; never grant more permissions than needed.
• Node.js 22+ (required): kash CLI requires Node.js 22 or later. verify with node --version.
• ~/.kash/config.json (optional, file): persistent config file auto-created after first 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_BASE_URL (optional, string): environment variable to override the auto-routed base URL. use only if pinning a specific API endpoint.
• KASH_PROFILE (optional, string): environment variable or --profile flag to select a named profile from config.json. enables multi-account / multi-environment workflows.
• Market ID (required for trade/quote commands, string): stable identifier of the market you want to trade. obtained from kash markets list.
• Outcome index (required for trade/quote commands, integer): 0 for YES, 1 for NO (or market-specific outcome labels). check market details with kash markets get.
• Amount / token count (required for trade/quote commands, decimal): amount of USDC to spend (--amount) or number of outcome tokens to sell (--tokens).
• Idempotency key (required for agent flows, string): unique request identifier. use --auto-idempotency-key to auto-generate.
• High-value confirmation token (conditional, string): one-time token returned by high-value trades (> key's high_value_threshold_usdc). valid for 60 seconds.
• Protocol-mode fields (conditional for direct-to-chain, string): rpcUrl, smartAccount address, optional bundlerUrl/bundlerProvider, signerKeyRef (file: or env:). stored in ~/.kash/config.json under a named profile.

procedure

1. install the CLI. run npm install -g @kashdao/cli@latest. verify with kash --version. requires Node.js 22+.

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

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

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

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

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

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

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

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

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

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

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

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

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

decision points

• 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 or set KASH_PROFILE to select the profile.

• if direct-to-chain (protocol) mode is needed: add rpcUrl, smartAccount, bundlerUrl (optional), and signerKeyRef (file: or env:) to your profile in ~/.kash/config.json. use kash protocol commands instead of kash trade; the Kash backend is bypassed entirely.

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

output contract

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

outcome signal

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