Skip to main content
The API serves an experimental protocol. Follow the Terms, treat indexed reads as potentially delayed and revalidate before wallet transactions.

​
Discover before reading

Building with an agent? Start with the canonical skill.md, our single agent instruction file. Re-fetch it each session; this page is the API reference. Include your API-KEY header on every request below, including website discovery. See registration, limits and consent. A default key allows 100 reads, 25 writes and 10 stream connections per minute, in separate per-replica budgets; approved multipliers apply. Looking for a wallet’s cards and sealed positions? Use the wallet holdings guide. The current API is graph-scoped; /api/vibemarket2/user/holdings is not a route.
  1. Read GET https://vibechain.com/api/vibemarket2/catalog/sources.
  2. Choose a source and one of its versions. The version’s runtimeId selects backend runtime routes. For new launches, choose the version explicitly marked launchTarget: true.
  3. Cross-check GET https://build.vibechain.com/api/vibemarket2/runtime/versions and retain the chain ID, market, factory and schema.
  4. Read GET /runtime/{version}/catalog?after=0 from the backend base URL.
Existing packs and wallet assets can belong to older graphs. Query those graphs rather than reassigning their drop IDs to the newest runtime. For a website pack URL, resolve GET /runtime/pack-slugs/{slug}. The response includes canonicalSlug, launchTx, graph and market; use that graph’s id for subsequent reads.

​
Read surfaces

The raw index and the board API are different views. Index lists return {items, next, head}; board responses vary by resource (for example {drops, next}, {trades}, or a quote object). There is no universal data wrapper. The inventory response returns {address, cards, tokens, pendingPulls, totals, next}. Its cursor advances three wallet indexes together and must be passed back unchanged. Query every relevant historical graph for an all-market wallet view; never combine holdings solely by numeric drop ID.

​
Numbers, units and time

  • Raw blockchain integers, IDs and wei quantities can be decimal strings. Use BigInt or exact decimal arithmetic, not JavaScript Number.
  • Board fields ending in Eth, such as ethIn, are formatted ETH decimal strings, not wei.
  • Board dates such as quotedAt are ISO timestamps. Session expiry, release scheduling and runtime-head update times use Unix milliseconds; raw chain event times may use seconds.
  • Missing or null accounting values are not zero. Preserve “not available” states in the UI.

​
Pagination

Do not reuse a cursor across resources, wallets or runtime versions. Deduplicate by graph-qualified identity, not a numeric drop ID alone.

​
Live updates

GET /runtime/{version}/stream is a server-sent event stream. Subscribe with comma-separated topics: catalog, pot, market:{dropId}, or wallet:{lowercaseAddress} (at most 16). Send API-KEY in the header, or use the narrowly supported apiKey query parameter for native EventSource on this exact GET route. Each connection/reconnection consumes stream quota; frames do not consume HTTP read quota. Retain event IDs and reconnect with Last-Event-ID or the numeric after query. A hello starts a stream; reset means you must refresh durable HTTP reads. Other events are updates/invalidation signals, not proof of finality or transactions. The optional watch value is shelf or a positive drop ID and participates in presence tracking. Use backoff and jitter on reconnect. Refetch relevant bounded reads after updates instead of polling the full catalog at high frequency.

​
Errors and freshness

Most application errors are JSON {"error":"..."}. Parsers and rate-limit middleware can also return non-JSON errors, so handle the HTTP status before assuming a JSON body.
  • 400: invalid arguments, cursors, signatures or action data.
  • 401 / 403: missing/invalid API key or missing, expired or unauthorized session/origin/wallet; inspect the error code.
  • 404: unknown market, artwork or runtime resource.
  • 409: conflict, stale edit or unavailable mutation on a retired runtime; inspect the operation.
  • 413: body too large.
  • 429: admission or rate limit; honor Retry-After when present.
  • 503: indexing, dependency or capacity failure; retry with backoff.
Some runtime routes classify an unknown runtime as 400, others as 404; the operation reference records this distinction. Do not turn an incomplete catalog or a 503 into an empty-success result. /health can return HTTP 200 with ready: false. Check readiness, head freshness and graph identity, not status alone. Honor cache headers; authenticated account and DM responses must not be shared between users. See the complete operation reference.