Guestlist API

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

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.

List events

GET /api/guestlist

Returns all events.

Response

{
  "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

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

{
  "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

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.

{
  "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

{
  "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

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

{
  "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

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

{
  "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

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

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

Guests added via buy-ticket receive confirmed status immediately, unlike rsvp which creates guests with pending status.

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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Guestlist API

Guestlist API

List events

Response

Get event

Query parameters

Response

Errors

Create event

Request body

Response

RSVP

Request body

Response

Errors

Check in

Request body

Response

Errors

Buy ticket

Request body

Response

Errors

Common errors

​Guestlist API

​List events

​Response

​Get event

​Query parameters

​Response

​Errors

​Create event

​Request body

​Response

​RSVP

​Request body

​Response

​Errors

​Check in

​Request body

​Response

​Errors

​Buy ticket

​Request body

​Response

​Errors

​Common errors

Guestlist API

List events

Response

Get event

Query parameters

Response

Errors

Create event

Request body

Response

RSVP

Request body

Response

Errors

Check in

Request body

Response

Errors

Buy ticket

Request body

Response

Errors

Common errors