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

# vibe.market Classic API Introduction

> Integrate with vibe.market Classic packs, collections, creator tools, activity, social data, and analytics

## Overview

<Note>
  This is **vibe.market Classic**, the original Base booster-box API. For the current
  market at `/market`, use the [current API reference](/api-reference/vibemarket-intro).
  These APIs and contract graphs are not interchangeable.
</Note>

The vibe.market Classic API is the production HTTP interface behind
[vibe.market Classic](https://vibechain.com/market/classic). It exposes packs and card metadata,
collections, market activity, game discovery, creator drafts, allowlists,
recovery tools, chat, leaderboards, and platform analytics on Base.

The reference in this tab documents the complete routable API surface. Unless
an endpoint says otherwise, requests and responses use JSON.

## Base URL

```text theme={null}
https://build.vibechain.com/vibe/boosterbox
```

Base mainnet (`chainId: 8453`) is the default wherever a chain is optional.

## Create an API key

Most endpoints require a free caller-specific API key:

```bash theme={null}
curl -X POST https://build.vibechain.com/apikey/create \
  -H "Content-Type: application/json" \
  -d '{
    "description": "YOUR_PROJECT - vibe.market Classic",
    "email": "YOUR_EMAIL"
  }'
```

Send the returned key in the `API-KEY` header:

```bash theme={null}
curl "https://build.vibechain.com/vibe/boosterbox/featured?limit=3" \
  -H "API-KEY: YOUR_API_KEY"
```

An API key identifies your integration for quotas and abuse control. It is not
a wallet credential. Keep it out of source control, browser URLs, and logs.

## Authentication model

The API has two independent authentication layers:

| Credential                      | Purpose                                                                   | Where it is used                                                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `API-KEY`                       | Identifies an integration and applies its quota                           | Most reads and all creator/recovery writes                                                                                              |
| `Authorization: Bearer <token>` | Identifies a signed-in vibe.market Classic account and its linked wallets | Draft deletion, allowlist changes, metadata confirmation and editing, event recovery, reactions, reports, refreshes, and platform stats |

Endpoints that show both security requirements need **both headers**. A Bearer
token never replaces an API key unless the endpoint explicitly lists only
Bearer authentication.

The OpenSea-compatible collection and token metadata routes are public and do
not require either credential.

<Warning>
  Creator writes verify that the requested creator or contract belongs to a
  wallet linked to the signed-in account. A valid token alone does not grant
  access to another creator's data.
</Warning>

## Quick starts

### Discover featured games

```bash theme={null}
curl "https://build.vibechain.com/vibe/boosterbox/featured?limit=6&sortBy=trending" \
  -H "API-KEY: YOUR_API_KEY"
```

### List an owner's packs

```bash theme={null}
curl "https://build.vibechain.com/vibe/boosterbox/owner/0xYOUR_WALLET?limit=25&sortOrder=desc" \
  -H "API-KEY: YOUR_API_KEY"
```

### Read collection activity incrementally

```bash theme={null}
curl "https://build.vibechain.com/vibe/boosterbox/collection/0xCOLLECTION/events?limit=100" \
  -H "API-KEY: YOUR_API_KEY"
```

Use the returned cursor as the next request's `cursor` value. Cursors are
endpoint-specific: activity uses a block-number cursor, while `/recent` uses a
`timestamp-objectId` cursor.

## Response conventions

Most application routes return a top-level `success` boolean plus named data:

```json theme={null}
{
  "success": true,
  "games": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0
  }
}
```

There is intentionally no universal `data` envelope. The OpenSea metadata
routes return standard metadata objects directly, and `/unboxing-disallowed`
returns `{ "disallowed": boolean }`.

Errors normally use this shape:

```json theme={null}
{
  "success": false,
  "message": "Error description",
  "error": "Optional diagnostic detail"
}
```

Do not branch on message text. Use the HTTP status, then inspect endpoint fields
such as `status`, `available`, `ready`, or `receiptFound` where the reference
documents a successful negative result.

## Values and identifiers

* EVM addresses are `0x`-prefixed, 20-byte strings.
* Transaction hashes are `0x`-prefixed, 32-byte strings.
* Token IDs may exceed JavaScript's safe integer range in external systems;
  preserve identifier strings when your client library provides them that way.
* Onchain prices and rewards are returned as decimal strings in Wei unless a
  field explicitly ends in `Usd` or `Eth`.
* Rarity codes are `0` not assigned, `1` Common, `2` Rare, `3` Epic, `4`
  Legendary, and `5` Mythic.
* Pack status is one of `minted`, `opened`, `rarity_assigned`, or `burned`.

## Pagination

Page-based endpoints return `page`, `limit`, `total`, and `totalPages`.
Cursor-based endpoints return a next cursor when another page may exist. Treat
cursor values as opaque even when their current format is documented.

Limits vary by endpoint. The OpenAPI reference records the actual default and
maximum for each route; do not assume one global page size.

## Image delivery

Responses normally rewrite recognized CDN image URLs through the vibe.market Classic
image proxy. Server-side integrations that want the original
`imagedelivery.net` URLs can send:

```http theme={null}
X-Bypass-Image-Proxy: true
```

Because this header can change response URLs, cache variants separately. It
does not bypass authentication or API quotas.

## Rate limits

Standard keys receive these per-IP allowances. Approved keys may have a higher
multiplier.

| Route class               | Standard allowance        |
| ------------------------- | ------------------------- |
| General API-key reads     | 100 requests per minute   |
| Search and API-key writes | 25 requests per minute    |
| Public OpenSea metadata   | 2,000 requests per minute |
| Reports                   | 10 requests per hour      |

For API-key routes, a missing key, invalid key, and exhausted quota intentionally
share the same `429` response:

```json theme={null}
{
  "success": false,
  "message": "Too many requests or invalid API key! See docs.vibechain.com for more info."
}
```

Use exponential backoff with jitter after `429`. Contact
[gm@vibechain.com](mailto:gm@vibechain.com) for higher limits.

## HTTP status guide

| Status | Meaning                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | The request was handled; some negative states such as a pending rarity, unavailable slug, cooldown, or missing receipt are represented in the body |
| `400`  | A path, query, or body value is malformed or incomplete                                                                                            |
| `401`  | The Bearer token is missing, expired, or invalid                                                                                                   |
| `403`  | The signed-in account does not control the requested creator resource                                                                              |
| `404`  | The requested pack, game, draft, message, transaction, or collection was not found                                                                 |
| `429`  | API key missing/invalid, quota exhausted, duplicate report, or refresh/report limit reached                                                        |
| `500`  | The server could not complete the operation                                                                                                        |
| `503`  | ETH pricing is temporarily unavailable                                                                                                             |

## Caching and freshness

Read endpoints use endpoint-specific server caches, generally from 5 seconds
for rapidly changing pack/game state to 5 minutes for stable metadata and
analytics. Several hot endpoints also return `Cache-Control` headers.

* Honor response cache headers when present.
* Do not assume all list endpoints have the same freshness window.
* Use `/contractAddress/{contractAddressOrSlug}/ready` while newly created
  metadata is processing.
* Use `/events/{txHash}` only as an authenticated recovery path after normal
  indexing has not produced the expected state.
* Treat chat stream data and collection events as refresh signals; refetch the
  durable resource after a gap.

## Creator workflow

The usual offchain-to-onchain flow is:

1. Create or autosave a draft with `POST /metadata/draft/poll`.
2. Add and finalize an allowlist if the launch is gated.
3. Deploy the collection from a wallet linked to the signed-in account.
4. Attach the transaction with `POST /metadata/confirm`.
5. Poll readiness and read the published game by address or slug.
6. Use `PUT /metadata/{contractAddress}` for later metadata revisions.

Writes are idempotent only where the endpoint explicitly documents that
behavior. Persist draft IDs and transaction hashes so retries can address the
same resource.

## Support

For integration support, quota changes, or suspected API defects, contact
[gm@vibechain.com](mailto:gm@vibechain.com).