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

# 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](/developer-docs/public-embed-api/overview) 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.

```diff theme={null}
- 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.

```diff theme={null}
- 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.

```diff theme={null}
- 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:

```bash theme={null}
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](/developer-docs/public-embed-api/overview).
* 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](/developer-docs/rest-api/sdks/typescript) — 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?

<CardGroup cols={2}>
  <Card title="Email support" icon="envelope">
    [dev@kash.bot](mailto:dev@kash.bot) — happy to walk through specific migrations.
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.com/invite/n9eumqjMPb">
    `#developers` channel — fastest for "is this the right endpoint for X?"
  </Card>
</CardGroup>