> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Guestlist API

> Event guestlist management with on-chain payment verification

# Guestlist API

Create events, manage guest lists, process RSVPs, handle check-ins, and sell tickets with optional on-chain payment verification on Base.

<Note>Event data is stored in memory and does not persist across server restarts. Ticket purchases with a non-zero tier price are verified against the buyer's USDC balance on Base mainnet.</Note>

## List events

```http theme={"dark"}
GET /api/guestlist
```

Returns all events.

### Response

```json theme={"dark"}
{
  "events": [
    {
      "id": "evt_abc123def",
      "name": "baseFM Launch Party",
      "date": "2026-04-15",
      "venue": "The Warehouse",
      "capacity": 200,
      "guestlist": [],
      "tiers": [
        { "name": "general", "price": "0", "count": 150 },
        { "name": "guestlist", "price": "0", "count": 50 }
      ]
    }
  ]
}
```

## Get event

```http theme={"dark"}
GET /api/guestlist?eventId=evt_abc123def
```

Returns a single event with its full guestlist.

### Query parameters

| Parameter | Type   | Required | Description      |
| --------- | ------ | -------- | ---------------- |
| `eventId` | string | Yes      | Event identifier |

### Response

```json theme={"dark"}
{
  "id": "evt_abc123def",
  "name": "baseFM Launch Party",
  "date": "2026-04-15",
  "venue": "The Warehouse",
  "capacity": 200,
  "guestlist": [
    {
      "id": "g_xyz789abc",
      "name": "Alice",
      "email": "alice@example.com",
      "wallet": "0xabc...123",
      "status": "confirmed",
      "tier": "vip",
      "timestamp": 1713139200000
    }
  ],
  "tiers": [
    { "name": "general", "price": "0", "count": 150 },
    { "name": "guestlist", "price": "0", "count": 50 }
  ]
}
```

| Field                     | Type   | Description                                                                           |
| ------------------------- | ------ | ------------------------------------------------------------------------------------- |
| `id`                      | string | Event identifier                                                                      |
| `name`                    | string | Event name                                                                            |
| `date`                    | string | Event date                                                                            |
| `venue`                   | string | Event venue                                                                           |
| `capacity`                | number | Maximum number of guests                                                              |
| `guestlist`               | array  | List of guest objects                                                                 |
| `guestlist[].id`          | string | Guest identifier                                                                      |
| `guestlist[].name`        | string | Guest name                                                                            |
| `guestlist[].email`       | string | Guest email (optional)                                                                |
| `guestlist[].wallet`      | string | Guest wallet address (optional)                                                       |
| `guestlist[].status`      | string | One of: `pending`, `confirmed`, `checked-in`, `cancelled`                             |
| `guestlist[].tier`        | string | One of: `vip`, `guestlist`, `general`, `press`                                        |
| `guestlist[].timestamp`   | number | Unix timestamp (milliseconds) when the guest was added                                |
| `guestlist[].checkedInAt` | number | Unix timestamp (milliseconds) when the guest checked in (only present after check-in) |
| `tiers`                   | array  | Available ticket tiers                                                                |
| `tiers[].name`            | string | Tier name                                                                             |
| `tiers[].price`           | string | Tier price in token units (`0` for free)                                              |
| `tiers[].count`           | number | Number of spots in this tier                                                          |

### Errors

| Code | Description     |
| ---- | --------------- |
| 404  | Event not found |

## Create event

```http theme={"dark"}
POST /api/guestlist
```

### Request body

| Field      | Type   | Required | Description                                                                              |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `action`   | string | Yes      | Must be `create-event`                                                                   |
| `name`     | string | Yes      | Event name                                                                               |
| `date`     | string | Yes      | Event date                                                                               |
| `venue`    | string | Yes      | Event venue                                                                              |
| `capacity` | number | No       | Maximum guests (default: `200`)                                                          |
| `tiers`    | array  | No       | Ticket tiers. Defaults to general (150 spots) and guestlist (50 spots) tiers, both free. |

```json theme={"dark"}
{
  "action": "create-event",
  "name": "baseFM Launch Party",
  "date": "2026-04-15",
  "venue": "The Warehouse",
  "capacity": 200,
  "tiers": [
    { "name": "general", "price": "0", "count": 150 },
    { "name": "vip", "price": "10000000", "count": 50 }
  ]
}
```

### Response

```json theme={"dark"}
{
  "success": true,
  "event": {
    "id": "evt_abc123def",
    "name": "baseFM Launch Party",
    "date": "2026-04-15",
    "venue": "The Warehouse",
    "capacity": 200,
    "guestlist": [],
    "tiers": [
      { "name": "general", "price": "0", "count": 150 },
      { "name": "vip", "price": "10000000", "count": 50 }
    ]
  }
}
```

## RSVP

```http theme={"dark"}
POST /api/guestlist
```

Adds a guest to an event's guestlist with `pending` status.

### Request body

| Field     | Type   | Required | Description                                                                       |
| --------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `action`  | string | Yes      | Must be `rsvp`                                                                    |
| `eventId` | string | Yes      | Event identifier                                                                  |
| `name`    | string | Yes      | Guest name                                                                        |
| `email`   | string | No       | Guest email                                                                       |
| `wallet`  | string | No       | Guest wallet address                                                              |
| `tier`    | string | No       | Ticket tier (default: `general`). Options: `vip`, `guestlist`, `general`, `press` |

### Response

```json theme={"dark"}
{
  "success": true,
  "guest": {
    "id": "g_xyz789abc",
    "name": "Alice",
    "email": "alice@example.com",
    "wallet": "0xabc...123",
    "status": "pending",
    "tier": "general",
    "timestamp": 1713139200000
  }
}
```

### Errors

| Code | Description                                               |
| ---- | --------------------------------------------------------- |
| 400  | Event full — the guestlist has reached the event capacity |
| 404  | Event not found                                           |

## Check in

```http theme={"dark"}
POST /api/guestlist
```

Marks a guest as checked in. You can identify the guest by either `guestId` or `wallet`.

### Request body

| Field     | Type   | Required    | Description                                      |
| --------- | ------ | ----------- | ------------------------------------------------ |
| `action`  | string | Yes         | Must be `check-in`                               |
| `eventId` | string | Yes         | Event identifier                                 |
| `guestId` | string | Conditional | Guest identifier (provide this or `wallet`)      |
| `wallet`  | string | Conditional | Guest wallet address (provide this or `guestId`) |

### Response

```json theme={"dark"}
{
  "success": true,
  "guest": {
    "id": "g_xyz789abc",
    "name": "Alice",
    "status": "checked-in",
    "tier": "vip",
    "timestamp": 1713139200000,
    "checkedInAt": 1713225600000
  }
}
```

### Errors

| Code | Description        |
| ---- | ------------------ |
| 400  | Already checked in |
| 404  | Event not found    |
| 404  | Guest not found    |

## Buy ticket

```http theme={"dark"}
POST /api/guestlist
```

Purchases a ticket for an event. When the tier price is non-zero, the buyer's USDC balance on Base is verified before confirming.

### Request body

| Field     | Type   | Required | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `action`  | string | Yes      | Must be `buy-ticket`                                          |
| `eventId` | string | Yes      | Event identifier                                              |
| `name`    | string | Yes      | Buyer name                                                    |
| `email`   | string | No       | Buyer email                                                   |
| `wallet`  | string | Yes      | Buyer wallet address (used for on-chain payment verification) |
| `tier`    | string | Yes      | Ticket tier to purchase                                       |

### Response

```json theme={"dark"}
{
  "success": true,
  "guest": {
    "id": "g_xyz789abc",
    "name": "Alice",
    "wallet": "0xabc...123",
    "status": "confirmed",
    "tier": "vip",
    "timestamp": 1713139200000
  }
}
```

<Note>Guests added via `buy-ticket` receive `confirmed` status immediately, unlike `rsvp` which creates guests with `pending` status.</Note>

### Errors

| Code | Description                                                                       |
| ---- | --------------------------------------------------------------------------------- |
| 400  | Invalid tier — the specified tier does not exist for this event                   |
| 400  | Insufficient payment — the wallet's on-chain USDC balance is below the tier price |
| 404  | Event not found                                                                   |

## Common errors

| Code | Description    |
| ---- | -------------- |
| 400  | Invalid action |
| 500  | Internal error |