### Start Development Server (Bash)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Starts the development server for the API. Requires a .env file with DATABASE_URL.

```bash
pnpm dev
```

--------------------------------

### API .env Configuration Example

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example environment file for API configuration, including database connection and optional settings.

```env
DATABASE_URL="postgresql://user:password@localhost:5432/summit"
# optional
# DATABASE_SSL="false"
# DB_POOL_MAX="15"
# PORT="3001"
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Installs project dependencies using pnpm. Assumes the user is in the 'api' directory.

```bash
cd api
pnpm install
```

--------------------------------

### GET /diplomacy/all

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves all beasts that have a diplomacy upgrade, suitable for building leaderboards.

```APIDOC
## GET /diplomacy/all

### Description
Returns all beasts with diplomacy upgrade for building leaderboards.

### Method
GET

### Endpoint
`/diplomacy/all`

### Parameters
None

### Request Example
```bash
curl "http://localhost:3001/diplomacy/all"
```

### Response
#### Success Response (200)
- **token_id** (integer) - The unique identifier for the beast token.
- **beast_id** (integer) - The identifier for the beast type.
- **prefix** (integer) - The ID of the diplomacy prefix.
- **suffix** (integer) - The ID of the diplomacy suffix.
- **level** (integer) - The current level of the beast.
- **bonus_xp** (integer) - Bonus experience points from upgrades.

#### Response Example
```json
[
  { "token_id": 1234, "beast_id": 45, "prefix": 12, "suffix": 8, "level": 15, "bonus_xp": 500 },
  { "token_id": 5678, "beast_id": 23, "prefix": 12, "suffix": 8, "level": 20, "bonus_xp": 800 }
]
```
```

--------------------------------

### GET /leaderboard

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves the rewards leaderboard, aggregated by owner address.

```APIDOC
## GET /leaderboard

### Description
Returns rewards leaderboard grouped by owner address.

### Method
GET

### Endpoint
`/leaderboard`

### Parameters
None

### Request Example
```bash
curl "http://localhost:3001/leaderboard"
```

### Response
#### Success Response (200)
- **owner** (string) - The wallet address of the player.
- **amount** (number) - The total rewards amount for the owner.

#### Response Example
```json
[
  { "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1", "amount": 15000.5 },
  { "owner": "0x02c9f8e6d7b5a4e3c2d1f0e9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4e3d2c1b0a9", "amount": 12500.25 }
]
```
```

--------------------------------

### Get Activity Logs

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves paginated summit activity logs with optional filtering.

```APIDOC
## GET /logs

### Description
Retrieves paginated summit activity logs with optional filtering by category, sub_category, or player.

### Method
GET

### Endpoint
/logs

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of logs to return.
- **offset** (integer) - Optional - The number of logs to skip before returning results.
- **category** (string) - Optional - Filter by log category (e.g., `Battle`, `Upgrade`). Can be a comma-separated list.
- **sub_category** (string) - Optional - Filter by log sub-category (e.g., `attack`, `specials`). Can be a comma-separated list.
- **player** (string) - Optional - Filter by player's address.

#### Request Body
None

### Response
#### Success Response (200)
- Returns an array of activity log objects. The structure of each log object may vary based on the event type.

#### Response Example
```json
{
  "data": [
    {
      "timestamp": "2024-01-15T10:35:00.000Z",
      "event": "Battle",
      "details": {
        "attacker": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
        "defender": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
        "outcome": "defender_wins",
        "damage_dealt": 50
      }
    },
    {
      "timestamp": "2024-01-15T10:32:00.000Z",
      "event": "Upgrade",
      "details": {
        "player": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
        "upgrade_type": "specials",
        "level_increase": 1
      }
    }
  ],
  "pagination": {"limit": 50, "offset": 0, "total": 1000, "has_more": true}
}
```
```

--------------------------------

### GET /diplomacy

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves beasts with a specific diplomacy upgrade prefix and suffix combination.

```APIDOC
## GET /diplomacy

### Description
Returns beasts with diplomacy upgrade matching specific prefix/suffix combination.

### Method
GET

### Endpoint
`/diplomacy?prefix={prefix_id}&suffix={suffix_id}`

### Parameters
#### Query Parameters
- **prefix** (string) - Required - The prefix ID for the diplomacy upgrade.
- **suffix** (string) - Required - The suffix ID for the diplomacy upgrade.

### Request Example
```bash
curl "http://localhost:3001/diplomacy?prefix=12&suffix=8"
```

### Response
#### Success Response (200)
- **token_id** (integer) - The unique identifier for the beast token.
- **beast_id** (integer) - The identifier for the beast type.
- **name** (string) - The name of the beast.
- **prefix** (string) - The name of the diplomacy prefix.
- **suffix** (string) - The name of the diplomacy suffix.
- **prefix_id** (integer) - The ID of the diplomacy prefix.
- **suffix_id** (integer) - The ID of the diplomacy suffix.
- **full_name** (string) - The combined full name of the beast.
- **level** (integer) - The current level of the beast.
- **current_level** (integer) - The beast's level after upgrades.
- **health** (integer) - The base health of the beast.
- **current_health** (integer) - The current health of the beast.
- **bonus_health** (integer) - Bonus health provided by upgrades.
- **bonus_xp** (integer) - Bonus experience points from upgrades.
- **summit_held_seconds** (integer) - Duration in seconds the beast has held a summit.
- **spirit** (integer) - The spirit stat of the beast.
- **luck** (integer) - The luck stat of the beast.
- **owner** (string) - The wallet address of the beast's owner.

#### Response Example
```json
[
  {
    "token_id": 1234,
    "beast_id": 45,
    "name": "Dragon",
    "prefix": "Agony",
    "suffix": "Bane",
    "prefix_id": 12,
    "suffix_id": 8,
    "full_name": "\"Agony Bane\" Dragon",
    "level": 15,
    "current_level": 22,
    "health": 250,
    "current_health": 350,
    "bonus_health": 100,
    "bonus_xp": 500,
    "summit_held_seconds": 86400,
    "spirit": 25,
    "luck": 30,
    "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1"
  }
]
```
```

--------------------------------

### Get All Beasts (Paginated)

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves a paginated list of all beasts with optional filtering and sorting.

```APIDOC
## GET /beasts/all

### Description
Retrieves a paginated list of all beasts with optional filtering by prefix, suffix, beast_id, name, or owner. Supports sorting by summit hold time or level.

### Method
GET

### Endpoint
/beasts/all

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of beasts to return.
- **offset** (integer) - Optional - The number of beasts to skip before returning results.
- **sort** (string) - Optional - The field to sort by (e.g., `summit_held_seconds`, `level`).
- **prefix** (string) - Optional - Filter by beast prefix.
- **suffix** (string) - Optional - Filter by beast suffix.
- **beast_id** (integer) - Optional - Filter by beast ID.
- **name** (string) - Optional - Filter by beast name.
- **owner** (string) - Optional - Filter by owner's address.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (array) - An array of beast objects.
  - **token_id** (integer) - The unique token ID of the beast.
  - **beast_id** (integer) - The game's internal ID for the beast.
  - **prefix** (integer) - The prefix value of the beast.
  - **suffix** (integer) - The suffix value of the beast.
  - **level** (integer) - The current level of the beast.
  - **health** (integer) - The base health of the beast.
  - **bonus_health** (integer) - Bonus health points.
  - **bonus_xp** (integer) - Bonus experience points.
  - **summit_held_seconds** (integer) - Total seconds the beast has held the summit.
  - **spirit** (integer) - Spirit stat.
  - **luck** (integer) - Luck stat.
  - **specials** (boolean) - Indicates if the beast has special traits.
  - **wisdom** (boolean) - Indicates if the beast has wisdom trait.
  - **diplomacy** (boolean) - Indicates if the beast has diplomacy trait.
  - **extra_lives** (integer) - Number of extra lives.
  - **owner** (string) - The address of the beast's owner.
  - **shiny** (integer) - Shiny variant indicator.
  - **animated** (integer) - Animated variant indicator.
- **pagination** (object) - Pagination details.
  - **limit** (integer) - The limit used for the current request.
  - **offset** (integer) - The offset used for the current request.
  - **total** (integer) - The total number of beasts available.
  - **has_more** (boolean) - Indicates if there are more results.

#### Response Example
```json
{
  "data": [
    {
      "token_id": 1234,
      "beast_id": 45,
      "prefix": 12,
      "suffix": 8,
      "level": 15,
      "health": 250,
      "bonus_health": 100,
      "bonus_xp": 500,
      "summit_held_seconds": 86400,
      "spirit": 25,
      "luck": 30,
      "specials": true,
      "wisdom": true,
      "diplomacy": false,
      "extra_lives": 10,
      "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
      "shiny": 0,
      "animated": 1
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1500, "has_more": true }
}
```
```

--------------------------------

### Get Beast Statistics

Source: https://context7.com/provable-games/summit/llms.txt

Returns total, alive, and dead beast counts.

```APIDOC
## GET /beasts/stats/counts

### Description
Returns total, alive, and dead beast counts. Alive is defined as beasts whose last death was more than 24 hours ago.

### Method
GET

### Endpoint
/beasts/stats/counts

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **total** (integer) - The total number of beasts.
- **alive** (integer) - The number of currently alive beasts.
- **dead** (integer) - The number of dead beasts.

#### Response Example
```json
{
  "total": 5000,
  "alive": 4200,
  "dead": 800
}
```
```

--------------------------------

### Get Diplomacy Beasts by Prefix and Suffix (Bash)

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves beasts with a diplomacy upgrade matching a specific prefix and suffix combination. Requires a running local server and specifies the API endpoint and query parameters.

```bash
curl "http://localhost:3001/diplomacy?prefix=12&suffix=8"
```

--------------------------------

### Get Top Beasts

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves top beasts ranked by summit hold time with full metadata.

```APIDOC
## GET /beasts/stats/top

### Description
Retrieves top beasts ranked by summit hold time with full metadata.

### Method
GET

### Endpoint
/beasts/stats/top

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of beasts to return.
- **offset** (integer) - Optional - The number of beasts to skip before returning results.

#### Request Body
None

### Response
#### Success Response (200)
- **data** (array) - An array of top beast objects.
  - **token_id** (integer) - The unique token ID of the beast.
  - **summit_held_seconds** (integer) - Total seconds the beast has held the summit.
  - **bonus_xp** (integer) - Bonus experience points.
  - **last_death_timestamp** (integer) - Timestamp of the last death.
  - **owner** (string) - The address of the beast's owner.
  - **beast_name** (string) - The name of the beast.
  - **prefix** (string) - The prefix of the beast's name.
  - **suffix** (string) - The suffix of the beast's name.
  - **full_name** (string) - The full name of the beast (prefix + suffix + name).
- **pagination** (object) - Pagination details.
  - **limit** (integer) - The limit used for the current request.
  - **offset** (integer) - The offset used for the current request.
  - **total** (integer) - The total number of beasts available.
  - **has_more** (boolean) - Indicates if there are more results.

#### Response Example
```json
{
  "data": [
    {
      "token_id": 1234,
      "summit_held_seconds": 259200,
      "bonus_xp": 1500,
      "last_death_timestamp": 1705312800,
      "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
      "beast_name": "Dragon",
      "prefix": "Agony",
      "suffix": "Bane",
      "full_name": "\"Agony Bane\" Dragon"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 500, "has_more": true }
}
```
```

--------------------------------

### Get Rewards Leaderboard (Bash)

Source: https://context7.com/provable-games/summit/llms.txt

Fetches the rewards leaderboard, which is grouped by owner address. This endpoint provides a summary of rewards distributed to different players.

```bash
curl "http://localhost:3001/leaderboard"
```

--------------------------------

### REST API Get Activity Logs

Source: https://context7.com/provable-games/summit/llms.txt

Fetches paginated logs of summit activities in Savage Summit. Allows filtering by category (e.g., Battle, Upgrade), sub-category, or specific player addresses. Provides insights into game events and player actions.

```bash
# Get recent activity
curl "http://localhost:3001/logs?limit=50"

# Filter by battle events
curl "http://localhost:3001/logs?category=Battle&limit=25"

# Filter by multiple categories (comma-separated)
curl "http://localhost:3001/logs?category=Battle,Upgrade&sub_category=attack,specials"

# Filter by player
curl "http://localhost:3001/logs?player=0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1"

```

--------------------------------

### REST API Get Beasts by Owner

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves detailed information for all beasts owned by a specific Ethereum address. Includes full stats, reward data, and Loot Survivor details. Essential for checking a player's collection.

```bash
curl "http://localhost:3001/beasts/0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1"

# Response:
[
  {
    "id": 45,
    "token_id": 1234,
    "name": "Dragon",
    "prefix": "Agony",
    "suffix": "Bane",
    "tier": 1,
    "type": "Magic",
    "power": 75,
    "level": 15,
    "health": 250,
    "current_level": 22,
    "current_health": 350,
    "revival_time": 57600000,
    "bonus_health": 100,
    "bonus_xp": 500,
    "attack_streak": 5,
    "last_death_timestamp": 1705312800,
    "revival_count": 3,
    "extra_lives": 10,
    "captured_summit": true,
    "summit_held_seconds": 86400,
    "spirit": 25,
    "luck": 30,
    "specials": true,
    "wisdom": true,
    "diplomacy": false,
    "rewards_earned": 15000,
    "rewards_claimed": 10000,
    "kills_claimed": 50,
    "quest_rewards_claimed": 25,
    "adventurers_killed": 120
  }
]
```

--------------------------------

### REST API Get Top Beasts

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves a list of top-ranked beasts based on their summit hold time. Includes essential metadata and pagination controls. Useful for identifying the most dominant beasts in the game.

```bash
curl http://localhost:3001/beasts/stats/top?limit=10&offset=0

# Response:
{
  "data": [
    {
      "token_id": 1234,
      "summit_held_seconds": 259200,
      "bonus_xp": 1500,
      "last_death_timestamp": 1705312800,
      "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
      "beast_name": "Dragon",
      "prefix": "Agony",
      "suffix": "Bane",
      "full_name": "\"Agony Bane\" Dragon"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 500, "has_more": true }
}
```

--------------------------------

### Get Beasts by Owner

Source: https://context7.com/provable-games/summit/llms.txt

Returns all beasts owned by a specific address with full stats, rewards, and Loot Survivor data.

```APIDOC
## GET /beasts/{ownerAddress}

### Description
Returns all beasts owned by a specific address with full stats, rewards, and Loot Survivor data.

### Method
GET

### Endpoint
/beasts/{ownerAddress}

### Parameters
#### Path Parameters
- **ownerAddress** (string) - Required - The wallet address of the beast owner.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- Returns an array of beast objects, each containing detailed statistics and reward information.
  - **id** (integer) - Unique identifier for the beast.
  - **token_id** (integer) - The unique token ID of the beast.
  - **name** (string) - The name of the beast.
  - **prefix** (string) - The prefix of the beast's name.
  - **suffix** (string) - The suffix of the beast's name.
  - **tier** (integer) - The tier of the beast.
  - **type** (string) - The type of the beast.
  - **power** (integer) - The power level of the beast.
  - **level** (integer) - The current level of the beast.
  - **health** (integer) - The base health of the beast.
  - **current_level** (integer) - The current level including bonuses.
  - **current_health** (integer) - The current health including bonuses.
  - **revival_time** (integer) - Time in milliseconds until revival is available.
  - **bonus_health** (integer) - Bonus health points.
  - **bonus_xp** (integer) - Bonus experience points.
  - **attack_streak** (integer) - Current attack streak.
  - **last_death_timestamp** (integer) - Timestamp of the last death.
  - **revival_count** (integer) - Number of times revived.
  - **extra_lives** (integer) - Number of extra lives.
  - **captured_summit** (boolean) - Indicates if the beast has captured the summit.
  - **summit_held_seconds** (integer) - Total seconds the beast has held the summit.
  - **spirit** (integer) - Spirit stat.
  - **luck** (integer) - Luck stat.
  - **specials** (boolean) - Indicates if the beast has special traits.
  - **wisdom** (boolean) - Indicates if the beast has wisdom trait.
  - **diplomacy** (boolean) - Indicates if the beast has diplomacy trait.
  - **rewards_earned** (integer) - Total rewards earned.
  - **rewards_claimed** (integer) - Total rewards claimed.
  - **kills_claimed** (integer) - Total claimed kills.
  - **quest_rewards_claimed** (integer) - Total quest rewards claimed.
  - **adventurers_killed** (integer) - Number of adventurers killed.

#### Response Example
```json
[
  {
    "id": 45,
    "token_id": 1234,
    "name": "Dragon",
    "prefix": "Agony",
    "suffix": "Bane",
    "tier": 1,
    "type": "Magic",
    "power": 75,
    "level": 15,
    "health": 250,
    "current_level": 22,
    "current_health": 350,
    "revival_time": 57600000,
    "bonus_health": 100,
    "bonus_xp": 500,
    "attack_streak": 5,
    "last_death_timestamp": 1705312800,
    "revival_count": 3,
    "extra_lives": 10,
    "captured_summit": true,
    "summit_held_seconds": 86400,
    "spirit": 25,
    "luck": 30,
    "specials": true,
    "wisdom": true,
    "diplomacy": false,
    "rewards_earned": 15000,
    "rewards_claimed": 10000,
    "kills_claimed": 50,
    "quest_rewards_claimed": 25,
    "adventurers_killed": 120
  }
]
```
```

--------------------------------

### Get All Diplomacy Beasts (Bash)

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves all beasts that have a diplomacy upgrade, intended for building leaderboards. This endpoint aggregates diplomacy data across all applicable beasts.

```bash
curl "http://localhost:3001/diplomacy/all"
```

--------------------------------

### WebSocket Unsubscribed Response (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON response from the server indicating successful unsubscription from specified channels.

```json
{"type":"unsubscribed","channels":[...]}
```

--------------------------------

### REST API Get All Beasts (Paginated)

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves a paginated list of all beasts in Savage Summit. Supports filtering by various attributes like prefix, suffix, beast_id, name, or owner, and sorting by summit hold time or level. Useful for browsing and analyzing the beast population.

```bash
# Get top 25 beasts by summit hold time
curl "http://localhost:3001/beasts/all?limit=25&offset=0&sort=summit_held_seconds"

# Filter by owner address
curl "http://localhost:3001/beasts/all?owner=0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1&limit=10"

# Filter by beast name
curl "http://localhost:3001/beasts/all?name=dragon&sort=level"

# Response:
{
  "data": [
    {
      "token_id": 1234,
      "beast_id": 45,
      "prefix": 12,
      "suffix": 8,
      "level": 15,
      "health": 250,
      "bonus_health": 100,
      "bonus_xp": 500,
      "summit_held_seconds": 86400,
      "spirit": 25,
      "luck": 30,
      "specials": true,
      "wisdom": true,
      "diplomacy": false,
      "extra_lives": 10,
      "owner": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
      "shiny": 0,
      "animated": 1
    }
  ],
  "pagination": { "limit": 25, "offset": 0, "total": 1500, "has_more": true }
}
```

--------------------------------

### Get Total Quest Rewards (Bash)

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves the total sum of quest rewards claimed across all beasts in the game. This provides an aggregate view of questing activity.

```bash
curl "http://localhost:3001/quest-rewards/total"
```

--------------------------------

### Get Live Beast Statistics (Cairo)

Source: https://context7.com/provable-games/summit/llms.txt

Fetches the live statistics for specified beasts. The returned `LiveBeastStats` struct contains detailed, up-to-date information including health, experience, attack streaks, status effects, stat points, and quest progress. This data is crucial for understanding a beast's current condition and capabilities.

```cairo
// ISummitSystem::get_live_stats
fn get_live_stats(self: @ContractState, beast_token_ids: Span<u32>) -> Span<LiveBeastStats>;

// LiveBeastStats packed structure (251 bits in single felt252):
struct LiveBeastStats {
    token_id: u32,
    current_health: u16,
    bonus_health: u16,
    bonus_xp: u16,
    attack_streak: u8,
    last_death_timestamp: u64,
    revival_count: u8,
    extra_lives: u16,
    summit_held_seconds: u32,
    stats: Stats,           // spirit, luck, specials, wisdom, diplomacy
    rewards_earned: u32,
    rewards_claimed: u32,
    quest: Quest,           // captured_summit, used_revival_potion, used_attack_potion, max_attack_streak
}
```

--------------------------------

### WebSocket API Connection and Subscription (JavaScript)

Source: https://context7.com/provable-games/summit/llms.txt

Demonstrates how to establish a WebSocket connection to the server and subscribe to real-time updates for beast statistics and activity feed events. Includes handling messages and unsubscribing.

```javascript
// Connect to WebSocket
const ws = new WebSocket("ws://localhost:3001/ws");

// Subscribe to channels
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    channels: ["summit", "event"]
  }));
};

// Handle messages
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === "subscribed") {
    console.log("Subscribed to:", message.channels);
  }

  if (message.type === "summit") {
    // Beast stats update
    const stats = message.data;
    console.log(`Beast ${stats.token_id} health: ${stats.current_health}`);
  }

  if (message.type === "event") {
    // Activity feed event
    const event = message.data;
    console.log(`${event.category}: ${event.sub_category}`);
  }
};

// Unsubscribe from channel
ws.send(JSON.stringify({
  type: "unsubscribe",
  channels: ["event"]
}));

// Keep-alive ping
ws.send(JSON.stringify({ type: "ping" }));
// Receives: { "type": "pong" }
```

--------------------------------

### Build, Format, and Test Cairo Contracts

Source: https://github.com/provable-games/summit/blob/main/contracts/README.md

Commands to build, format check, and run tests for Cairo smart contracts using Scarb. These commands are essential for maintaining code quality and verifying contract functionality.

```bash
cd contracts
scarb build
scarb fmt --check
scarb test
```

--------------------------------

### GET /consumables/supply

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves the total circulating supply for each type of consumable token.

```APIDOC
## GET /consumables/supply

### Description
Returns total circulating supply of consumable tokens.

### Method
GET

### Endpoint
`/consumables/supply`

### Parameters
None

### Request Example
```bash
curl "http://localhost:3001/consumables/supply"
```

### Response
#### Success Response (200)
- **xlife** (integer) - The circulating supply of Xlife consumables.
- **attack** (integer) - The circulating supply of Attack consumables.
- **revive** (integer) - The circulating supply of Revive consumables.
- **poison** (integer) - The circulating supply of Poison consumables.

#### Response Example
```json
{
  "xlife": 50000,
  "attack": 75000,
  "revive": 30000,
  "poison": 25000
}
```
```

--------------------------------

### Running Unit Tests in Snforge

Source: https://github.com/provable-games/summit/blob/main/contracts/README.md

Demonstrates how to execute only the unit tests for the project using the snforge test command. It specifically shows how to skip the fork test module to isolate unit test execution.

```bash
snforge test --skip test_summit
```

--------------------------------

### GET /quest-rewards/total

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves the total quest rewards claimed across all beasts.

```APIDOC
## GET /quest-rewards/total

### Description
Returns total quest rewards claimed across all beasts.

### Method
GET

### Endpoint
`/quest-rewards/total`

### Parameters
None

### Request Example
```bash
curl "http://localhost:3001/quest-rewards/total"
```

### Response
#### Success Response (200)
- **total** (number) - The total amount of quest rewards claimed.

#### Response Example
```json
{ "total": 5000.5 }
```
```

--------------------------------

### Root Discovery API

Source: https://github.com/provable-games/summit/blob/main/api/AGENTS.md

Provides root discovery information, including debug hints in development mode.

```APIDOC
## GET /

### Description
Root discovery route. Includes debug endpoint hints in development mode.

### Method
GET

### Endpoint
/

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - A welcome message.
- **endpoints** (object) - Optional - Hints to available endpoints (present in development mode).

#### Response Example
```json
{
  "message": "Welcome to the Summit API!",
  "endpoints": {
    "health": "/health",
    "beasts": "/beasts/all"
  }
}
```
```

--------------------------------

### API Build and Typecheck (Bash)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Executes the build process and performs type checking for the API project using pnpm and TypeScript.

```bash
pnpm exec tsc --noEmit
```

--------------------------------

### WebSocket API

Source: https://github.com/provable-games/summit/blob/main/api/AGENTS.md

Real-time communication endpoint for subscribing to game events.

```APIDOC
## WS /ws

### Description
WebSocket endpoint for real-time updates. Clients can subscribe to channels like `summit` and `event`.

### Method
WS

### Endpoint
/ws

### Parameters
#### WebSocket Message Types
- **subscribe**: To subscribe to channels.
- **unsubscribe**: To unsubscribe from channels.
- **ping**: To keep the connection alive.

#### Subscribe Payload Example
```json
{
  "type": "subscribe",
  "channels": ["summit", "event"]
}
```

### Channels
- **summit**: Real-time updates related to the summit game state.
- **event**: Real-time notifications for various game events.

### Response
#### Real-Time Messages
- Messages are pushed to the client based on their subscriptions.

#### Example Message (Summit Update)
```json
{
  "channel": "summit",
  "data": {
    "beast_id": "123",
    "event": "level_up",
    "details": "Beast Sparky leveled up to level 6."
  }
}
```
```

--------------------------------

### Leaderboard API

Source: https://github.com/provable-games/summit/blob/main/api/AGENTS.md

Retrieves the game leaderboard.

```APIDOC
## GET /leaderboard

### Description
Retrieves the game leaderboard, showing player rankings and rewards.

### Method
GET

### Endpoint
/leaderboard

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (array) - Array of leaderboard entries.
  - **player** (string) - The player's address.
  - **total_rewards** (number) - The total rewards earned by the player (scaled down).

#### Response Example
```json
{
  "data": [
    {
      "player": "0x...",
      "total_rewards": 150.75
    }
  ]
}
```
```

--------------------------------

### GET /adventurers/{playerAddress}

Source: https://context7.com/provable-games/summit/llms.txt

Retrieves a list of distinct adventurer IDs associated with a given player address.

```APIDOC
## GET /adventurers/{playerAddress}

### Description
Returns distinct adventurer IDs for a player address.

### Method
GET

### Endpoint
`/adventurers/{playerAddress}`

### Parameters
#### Path Parameters
- **playerAddress** (string) - Required - The wallet address of the player.

### Request Example
```bash
curl "http://localhost:3001/adventurers/0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1"
```

### Response
#### Success Response (200)
- **player** (string) - The wallet address of the player.
- **adventurer_ids** (array of strings) - A list of adventurer IDs belonging to the player.

#### Response Example
```json
{
  "player": "0x04b8e8f7a8c10e7c31f2e94c17282bc50e36a8b27c3e89a1f7c9e3b6c0d2a8e1",
  "adventurer_ids": ["123", "456", "789"]
}
```
```

--------------------------------

### WebSocket Pong Response (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON response from the server acknowledging a received ping message.

```json
{"type":"pong"}
```

--------------------------------

### WebSocket Unsubscribe Message (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON payload for unsubscribing from the 'event' channel via WebSocket.

```json
{"type":"unsubscribe","channels":["event"]}
```

--------------------------------

### WebSocket Ping Message (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON payload for sending a ping message to the WebSocket server.

```json
{"type":"ping"}
```

--------------------------------

### WebSocket Subscription Message (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON payload for subscribing to 'summit' and 'event' channels via WebSocket.

```json
{"type":"subscribe","channels":["summit","event"]}
```

--------------------------------

### Run Cairo Contract Tests with Coverage (Foundry)

Source: https://github.com/provable-games/summit/blob/main/contracts/README.md

Command to run Cairo contract tests with coverage using the Starknet Foundry runner. This provides an alternative method for generating coverage reports.

```bash
snforge test --coverage
```

--------------------------------

### WebSocket Subscribed Response (JSON)

Source: https://github.com/provable-games/summit/blob/main/api/README.md

Example JSON response from the server indicating successful subscription to specified channels.

```json
{"type":"subscribed","channels":[...]}
```