Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kash.bot/llms.txt

Use this file to discover all available pages before exploring further.

The webapp at app.kash.bot exposes a /api/* surface that has been around longer than the REST API. It exists primarily for the webapp itself and for Public Embed API consumers — humans, iframes, anonymous traffic. If you’re a programmatic consumer (a trading bot, a market maker, a portfolio tool), you should be on api.kash.bot/v1. The webapp endpoints will continue to work for their intended audience, but they’re not the right surface for you.

​
Why migrate

Concernapp.kash.bot/apiapi.kash.bot/v1
AudienceHumans, embedded UIsProgrammatic consumers (bots, agents, MMs)
AuthenticationAnonymous or Privy sessionAPI key (X-API-Key)
Rate limitingPer-IPPer-key (much higher quotas, attribution, telemetry)
Response shapeUI-shaped (rich; tuned for rendering)Lean wire shape (decimal strings for big numbers)
Trade executionNot exposed — frontend signs directlyFirst-class — POST /v1/trades
WebhooksNonetrade.confirmation-required, .completed, .failed
IdempotencyNoIdempotency-Key + clientRequestId
PaginationOffset (legacy)Cursor (stable under concurrent writes)
Error formatVariousRFC 7807 Problem Details with stable code
ETags / If-None-MatchNoYes — every response, free read quota for unchanged data
VersioningNoneURL-versioned (/v1/) + X-Kash-Api-Version header
Deprecation policyBest-effortRFC 8594 Sunset + Deprecation headers, 12-month notice
The two will coexist indefinitely — the webapp routes serve a real audience. But for any new programmatic integration, start on api.kash.bot/v1.

​
Endpoint mapping

The five endpoints with logical overlap:

​
GET /api/markets → GET /v1/markets

Both list markets, cursor-paginated/offset-paginated respectively. 
- GET https://app.kash.bot/api/markets?status=active&limit=10&offset=20
+ GET https://api.kash.bot/v1/markets?status=active&limit=10&cursor=<opaque>
+ Header: X-API-Key: kash_live_...
Differences:
  • AWS uses cursor not offset. Walk pages by passing the pagination.cursor from the previous response.
  • AWS uses data: [...] consistently; webapp uses markets: [...].
  • AWS response is leaner (no yesPrice/noPrice convenience fields — those are derivable from outcomes[].probability).
  • AWS requires markets:read scope.

​
GET /api/markets/{id} → GET /v1/markets/{id}

Single market detail. Same caveats as above. AWS adds the dual-key data: alias on every single-resource response.

​
GET /api/markets/{id}/quote → GET /v1/markets/{id}/quote

Both fetch on-chain price quotes. The AWS endpoint is the canonical implementation — the webapp’s quote endpoint was the prototype; the AWS one is the production-grade version with stricter precision (decimal-string bigints), explicit units block, and proper kill-switch behaviour during RPC degradation. 
- GET https://app.kash.bot/api/markets/{id}/quote?outcomeIndex=0&action=buy&amount=100
+ GET https://api.kash.bot/v1/markets/{id}/quote?outcomeIndex=0&action=buy&amount=100000000
+ Header: X-API-Key: kash_live_...
Differences:
  • amount on AWS is in atomic units (USDC atomic-6 for buys, token WAD-18 for sells). The webapp accepts decimal USDC. Multiply by 1_000_000 going from one to the other.
  • AWS requires markets:quote scope (separate from markets:read so you can throttle quote traffic independently).
  • AWS returns all bigint fields as decimal strings (tokensOut: "237340124711760000000" instead of a JS number that loses precision).
  • AWS includes a units block ({ usdc: "atomic-6", token: "wad-18" }) so consumers don’t guess.

​
GET /api/portfolio → GET /v1/portfolio

Portfolio summary. 
- GET https://app.kash.bot/api/portfolio
- Header: Authorization: Bearer <privy-jwt>
+ GET https://api.kash.bot/v1/portfolio
+ Header: X-API-Key: kash_live_...
Differences:
  • Auth: Privy session JWT → API key.
  • Response is per-key user, not per-Privy-user. (For most cases these are the same person, but if you have multi-user setups, mind the distinction.)
  • AWS requires portfolio:read scope.

​
POST /api/account/api-keys → (NOT in AWS; webapp is the issuer)

Self-serve API key issuance lives only in the webapp. The AWS API reads from the same api_keys table but doesn’t issue keys — issuance requires a Privy session (the human). If you’re automating key provisioning programmatically, use the admin CLI on a machine with admin credentials: 
kash-admin api-keys issue --tier developer --user <user-id> \
  --scopes markets:read,markets:quote,trades:read,trades:write

​
Endpoints unique to AWS

These have no webapp equivalent — the AWS API introduces them:
  • POST /v1/trades — trade execution. The big one. The webapp doesn’t expose this; all trading happens via direct frontend transactions.
  • POST /v1/trades/{id}/confirm — high-value trade confirmation gate.
  • GET /v1/trades, GET /v1/trades/{id} — your trade history.
  • GET /v1/webhooks/events, POST /v1/webhooks/events/{id}/redeliver — webhook inspection and replay.
  • POST /v1/auth/api-keys/me/webhook-secret/rotate — secret rotation.
  • GET /v1/account/usage — per-key telemetry.
  • GET /v1/traces/{id} — distributed trace by correlation id.

​
Endpoints unique to the webapp

These won’t appear on AWS — they serve UI/embedding workloads:
  • GET /api/markets/trending, GET /api/markets/featured, GET /api/markets/for-you — engagement/personalisation.
  • GET /api/community/leaderboard — global rankings.
  • GET /api/portfolio/analytics, GET /api/portfolio/tx/{hash} — historical breakdowns.
  • All thread/social/embed endpoints — those are the Public Embed API.
  • All ramp/onramp/withdrawal flows — those are user account operations, not programmatic.
If you need any of these from a programmatic context, file an issue — there may be a path to expose a subset on AWS.

​
Migration checklist

For a typical migration from app.kash.bot/api/markets* + app.kash.bot/api/portfolio to api.kash.bot/v1/*:
  • Generate an API key in Settings → API Keys with scopes markets:read, markets:quote, portfolio:read (and trades:read, trades:write if you’ll execute trades).
  • Store the key in your secrets manager / env config. Never commit it.
  • Replace Authorization: Bearer <jwt> headers with X-API-Key: <key>.
  • Replace app.kash.bot/api base URL with api.kash.bot/v1.
  • Update pagination from offset/limit to cursor/limit.
  • Update response field accesses (response.markets → response.data or response.market → response.data).
  • Update bigint handling — quote fields are now decimal strings, not JS numbers. Use BigInt or a decimal lib.
  • Update quote amount to atomic units (* 1_000_000 for USDC).
  • Add error handling — branch on RFC 7807 code field, not status text.
  • Add Idempotency-Key to writes.
  • Pin to X-Kash-Api-Version: 2026-04-29 (or whatever’s current) and detect upgrades.
  • (Optional) Set up webhook receiver — replaces polling.
  • (Optional) Adopt the TypeScript SDK — collapses most of the above into typed method calls.

​
A note on the “prototype” quote endpoint

The webapp’s quote endpoint was the prototype for the AWS one. The AWS version is now the source of truth. If the two diverge in output (rare; we monitor for divergence), the AWS response is canonical. We don’t currently plan to formally deprecate the webapp’s quote endpoint — it serves the embed audience well — but new programmatic code should call AWS.

​
Need help migrating?

Email support

[email protected] — happy to walk through specific migrations.

Discord

#developers channel — fastest for “is this the right endpoint for X?”