Migrating from the Webapp API

Mapping table from app.kash.bot/api endpoints to api.kash.bot/v1.

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

Concern	app.kash.bot/api	api.kash.bot/v1
Audience	Humans, embedded UIs	Programmatic consumers (bots, agents, MMs)
Authentication	Anonymous or Privy session	API key (X-API-Key)
Rate limiting	Per-IP	Per-key (much higher quotas, attribution, telemetry)
Response shape	UI-shaped (rich; tuned for rendering)	Lean wire shape (decimal strings for big numbers)
Trade execution	Not exposed — frontend signs directly	First-class — POST /v1/trades
Webhooks	None	trade.confirmation-required, .completed, .failed, .rejected
Idempotency	No	Idempotency-Key + clientRequestId
Pagination	Offset (legacy)	Cursor (stable under concurrent writes)
Error format	Various	RFC 7807 Problem Details with stable code
ETags / If-None-Match	No	Yes — every response, cheap 304 revalidation (no body transfer; still counts toward quota)
Versioning	None	URL-versioned (/v1/) + X-Kash-Api-Version header
Deprecation policy	Best-effort	RFC 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:

• The REST API uses cursor not offset. Walk pages by passing the pagination.cursor from the previous response.
• The REST API uses data: [...] consistently; webapp uses markets: [...].
• The REST API response is leaner (no yesPrice/noPrice convenience fields — those are derivable from outcomes[].probability).
• The REST API requires the markets:read scope.

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

Single market detail. Same caveats as above. The REST API 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 api.kash.bot endpoint is the canonical implementation — the webapp’s quote endpoint was the prototype; the public REST API’s 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 the REST API 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.
• The REST API requires the markets:quote scope (separate from markets:read so you can throttle quote traffic independently).
• The REST API returns all bigint fields as decimal strings (tokensOut: "237340124711760000000" instead of a JS number that loses precision).
• The REST API 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.)
• The REST API requires the portfolio:read scope.

POST /api/account/api-keys → (not on api.kash.bot; webapp is the issuer)

Self-serve API key issuance lives only in the webapp. The public REST 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 the public REST API

These have no webapp equivalent — api.kash.bot/v1 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 api.kash.bot — 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 the public REST API.

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 api.kash.bot one. The public REST API version is now the source of truth. If the two diverge in output (rare; we monitor for divergence), the api.kash.bot 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 api.kash.bot/v1.

Need help migrating?

Email support

[e-mail] — happy to walk through specific migrations.

Discord

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