> For the complete documentation index, see [llms.txt](https://docs.cybercookie.party/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybercookie.party/api.md).

# Public API Reference

CyberCookie exposes a few **public, read-only** JSON endpoints you can call from your own app, bot, or website — no authentication required. All responses are JSON.

**Base URL:** `https://app.cybercookie.party`

> These endpoints are rate-limited per IP. Cache results on your side (a few seconds is plenty) rather than hammering them. The write/account endpoints are **not** public and require an authenticated session or signed token.

***

## GET `/api/leaderboard`

Top players or guilds.

**Query params**

| Param  | Values                | Default   | Meaning                                |
| ------ | --------------------- | --------- | -------------------------------------- |
| `type` | `players` \| `guilds` | `players` | which board                            |
| `full` | `1` \| `true`         | off       | return the top 50 instead of the top 5 |

**Example**

```bash
curl "https://app.cybercookie.party/api/leaderboard?type=players&full=1"
```

**Response (players)**

```json
{
  "type": "players",
  "online": 128,
  "entries": [
    {
      "id": "665f...",
      "rank": 1,
      "name": "EnderMythex",
      "username": "endermythex",
      "photoUrl": "https://...",
      "level": 13,
      "points": 2705887,
      "pph": 258640,
      "discordBadge": "team"
    }
  ]
}
```

* `points` is the player's live balance (including offline passive income projected to now).
* `online` is the current count of online players.
* For `type=guilds`, each entry has `{ id, rank, name, tag, imageUrl, points, pph, members }`.

**Integrate it in JS:**

```js
const res = await fetch('https://app.cybercookie.party/api/leaderboard?type=players&full=1');
const { entries, online } = await res.json();
entries.forEach(e => console.log(`#${e.rank} ${e.name} — ${e.points.toLocaleString()} 🍪`));
```

***

## GET `/api/global-stats`

Aggregate stats across all players (cached \~30s).

```json
{ "coins": 0, "clicks": 0, "pph": 0, "playMs": 0, "players": 0 }
```

| Field     | Meaning                                        |
| --------- | ---------------------------------------------- |
| `coins`   | total balance held by all players              |
| `clicks`  | total lifetime taps across all players         |
| `pph`     | sum of everyone's profit/hour                  |
| `playMs`  | total active play time (ms) across all players |
| `players` | total number of accounts                       |

***

## GET `/api/gamble/stats`

Live casino aggregates (shared jackpot + totals).

```json
{ "totalWon": 0, "totalLost": 0, "topWin": 0, "topWinner": "" }
```

`topWin`/`topWinner` = the biggest single payout ever and who won it. `totalWon`/`totalLost` = net coins won/lost by players across all casino games.

***

## GET `/api/profile?id=<id>`

A single player's public profile card. `id` can be a Mongo id or a `username`.

```bash
curl "https://app.cybercookie.party/api/profile?id=endermythex"
```

Returns identity + (if the profile isn't private) stats: `score`, `profitPerHour`, `totalTaps`, `upgradesCount`, `boostsGiven`, `tasksCompleted`, `friendsCount`, `playTimeMs`, `walletSolana`, `walletTon`, `guildName`, `online`, `level`, `discordBadge`. Private profiles return only the identity card.

***

## GET `/api/version`

Current deployed build — handy for a status page or to detect updates.

```json
{ "version": "1.x.x", "build": "abc1234", "commit": "abc1234" }
```

***

## Notes for integrators

* **CORS:** these read endpoints return JSON; call them server-side or from your own backend if you hit CORS in the browser.
* **Stability:** field names here are stable, but new fields may be added over time — read defensively (don't assume a fixed key set).
* **Rate limits:** \~1000 requests / 15 min per IP for general endpoints. Cache aggressively.

Next: [Security & Anti-Cheat →](/security.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybercookie.party/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.