> For the complete documentation index, see [llms.txt](https://noctaly-bot.gitbook.io/noctaly-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noctaly-bot.gitbook.io/noctaly-api/economy/chests.md).

# Chests

#### List Guild Chests <a href="#list-guild-chests" id="list-guild-chests"></a>

```http
GET guilds/{guildID}/chests
```

Returns all chests configured in the guild's economy.

**Response Fields**

| Field  | Type      | Description                                |
| ------ | --------- | ------------------------------------------ |
| chests | `Chest[]` | All chests defined in the guild's economy. |

```json
{
    "chests": [
        {
            "id": "660e9511-f30c-52e5-b827-557766551111",
            "name": "Golden Chest",
            "primaryColor": "FFD700",
            "secondaryColor": "FFA500",
            "iconURL": null,
            "flags": ["ANIMATED"],
            "buyPrice": 5000,
            "sellPrice": 2500,
            "itemDrawCount": 3,
            "quantity": null,
            "quantityLimit": null
        }
    ]
}
```

#### Add Chests to a Member <a href="#add-chests-to-a-member" id="add-chests-to-a-member"></a>

```http
POST guilds/{guildID}/users/{userID}/chests
```

Adds a quantity of a chest to the member's inventory.

**Request Body**

| Field                                           | Type     | Description                                  | Default |
| ----------------------------------------------- | -------- | -------------------------------------------- | ------- |
| chestID <mark style="color:$danger;">\*</mark>  | `string` | UUID of the chest to add.                    | —       |
| quantity <mark style="color:$danger;">\*</mark> | `number` | Quantity to add. Min: `1`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                                        |
| -------- | -------- | -------------------------------------------------- |
| quantity | `number` | New quantity of the chest in the user's inventory. |

```json
{
    "quantity": 3
}
```

***

#### Remove Chests from a Member <a href="#remove-chests-from-a-member" id="remove-chests-from-a-member"></a>

```http
DELETE guilds/{guildID}/users/{userID}/chests
```

Removes a quantity of a chest from the member's inventory. If the resulting quantity falls to `0` or below, the chest is deleted from the inventory entirely.

**Request Body**

| Field                                           | Type     | Description                                     | Default |
| ----------------------------------------------- | -------- | ----------------------------------------------- | ------- |
| chestID <mark style="color:$danger;">\*</mark>  | `string` | UUID of the chest to remove.                    | —       |
| quantity <mark style="color:$danger;">\*</mark> | `number` | Quantity to remove. Min: `1`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                        |
| -------- | -------- | ---------------------------------- |
| quantity | `number` | New quantity of the chest (≥ `0`). |

```json
{
    "quantity": 1
}
```

***

#### Set Chest Quantity for a Member <a href="#set-chest-quantity-for-a-member" id="set-chest-quantity-for-a-member"></a>

```http
PUT guilds/{guildID}/users/{userID}/chests
```

Sets the exact quantity of a chest in the member's inventory. Passing `0` removes the chest entirely.

**Request Body**

| Field                                           | Type     | Description                                  | Default |
| ----------------------------------------------- | -------- | -------------------------------------------- | ------- |
| chestID <mark style="color:$danger;">\*</mark>  | `string` | UUID of the chest.                           | —       |
| quantity <mark style="color:$danger;">\*</mark> | `number` | Target quantity. Min: `0`. Max: `1,000,000`. | —       |

**Response Fields**

| Field    | Type     | Description                |
| -------- | -------- | -------------------------- |
| quantity | `number` | The quantity that was set. |

```json
{
    "quantity": 0
}
```

<br>