vibe.market API Introduction

Overview

The vibe.market API is the production HTTP interface behind vibe.market. 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

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:

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

Send the returned key in the API-KEY header:

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 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.

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.

Quick starts

Discover featured games

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

List an owner’s packs

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

Read collection activity incrementally

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:

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

{
  "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 image proxy. Server-side integrations that want the original imagedelivery.net URLs can send:

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:

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

Create or autosave a draft with POST /metadata/draft/poll.
Add and finalize an allowlist if the launch is gated.
Deploy the collection from a wallet linked to the signed-in account.
Attach the transaction with POST /metadata/confirm.
Poll readiness and read the published game by address or slug.
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.

vibe.market API

Packs

Metadata

Collections

Activity

Creator drafts

Allowlists

Utility

Games

Social

Analytics

Overview

Base URL

Create an API key

Authentication model

Quick starts

Discover featured games

List an owner’s packs

Read collection activity incrementally

Response conventions

Values and identifiers

Image delivery

Rate limits

HTTP status guide

Caching and freshness

Creator workflow

Support

​Overview

​Base URL

​Create an API key

​Authentication model

​Quick starts

​Discover featured games

​List an owner’s packs

​Read collection activity incrementally

​Response conventions

​Values and identifiers

​Pagination

​Image delivery

​Rate limits

​HTTP status guide

​Caching and freshness

​Creator workflow

​Support

Overview

Base URL

Create an API key

Authentication model

Quick starts

Discover featured games

List an owner’s packs

Read collection activity incrementally

Response conventions

Values and identifiers

Pagination

Image delivery

Rate limits

HTTP status guide

Caching and freshness

Creator workflow

Support