# retard.market API Introduction Source: https://docs.vibechain.com/api-reference/retardmarket-intro Read the Robinhood Chain V9 market feed, quotes, portfolios, points, media, and realtime events ## Overview The retard.market API exposes the projection-backed V9 prediction-market feed on Robinhood Chain. The supported integration contract is V9; older RetardMarket routes remain key-gated for first-party history and migration flows but are not the recommended developer surface. Every HTTP route under `/api/retard` requires a VibeChain API key, including runtime, health, legacy, and realtime endpoints. ## Create an API key Create a free caller-specific key before making your first request: ```bash theme={null} curl -X POST https://build.vibechain.com/apikey/create \ -H "Content-Type: application/json" \ -d '{ "description": "YOUR_PROJECT - retard.market", "email": "YOUR_EMAIL" }' ``` Send the returned key in the `API-KEY` header on every API request: ```bash theme={null} curl https://build.vibechain.com/api/retard/v9/runtime \ -H "API-KEY: YOUR_API_KEY" ``` The API key identifies your workload for quota and abuse control. It is not a wallet credential and does not replace transaction simulation, slippage protection, or wallet signatures. Keep it out of source control and URLs. ## Base URL The current V9 base URL is: ```text theme={null} https://build.vibechain.com/api/retard/v9 ``` The API serves Robinhood Chain (`chainId: 4663`). Read `/runtime` at startup and fail closed unless both `enabled` and `publicEnabled` are true. ## Quick start Read the newest projected market: ```bash theme={null} curl "https://build.vibechain.com/api/retard/v9/markets?cursor=0&limit=1" \ -H "API-KEY: YOUR_API_KEY" ``` Addresses and integer onchain amounts are returned as strings where precision matters. WETH values such as `totalSeed`, `backingWeth`, and quote amounts are denominated in Wei unless a field explicitly says otherwise. Probabilities use basis points (`10,000 = 100%`). ## Pagination and projection safety List endpoints use a numeric `cursor` and a `limit` from 1 to 100. Follow `nextCursor` until it is `null`; do not infer completeness from a short page. V9 reads come from a finalized MongoDB projection. The API returns a non-cacheable `503` instead of silently rebuilding stale state from chain or serving data beyond its freshness bounds. Retry with backoff and keep the last known-good snapshot marked stale until a fresh read succeeds. ## Realtime stream `GET /stream` is a Server-Sent Events stream used to invalidate or refresh REST snapshots. External clients must attach `API-KEY` as a header. Native browser `EventSource` cannot set headers, so use a fetch-based SSE client or an EventSource-compatible library that supports request headers. Do not place your API key in the URL. Treat stream events as wakeups, not as a replacement for the durable REST snapshot. Reconnect with backoff and recover through `/markets` after a gap or `resync` event. ## Rate limits and errors The default allowance is 100 requests per minute per client IP for a standard key; approved key multipliers may raise that allowance. A missing key, invalid key, or exhausted allowance returns the same `429` response: ```json theme={null} { "error": "API_KEY_REQUIRED_OR_RATE_LIMITED", "docs": "https://docs.vibechain.com/api-reference/retardmarket-intro" } ``` | Status | Meaning | | ------ | --------------------------------------------------------------------- | | `400` | Invalid address, cursor, limit, side, amount, or other request input | | `404` | The requested market does not exist in the official projection | | `409` | The requested action conflicts with the market or transaction state | | `429` | API key missing/invalid or caller quota exhausted | | `503` | Product disabled, projection stale/unavailable, or realtime not ready | ## Trading boundary The HTTP API is a read/projection and preparation surface. `/quote` returns a block-pinned conservative buy preview, but trading and claims still happen in the audited Robinhood Chain contracts using wallet-signed transactions. The public [retard.market agent runbook](https://vibechain.com/retard/agents.md) describes the required runtime, quote, simulation, receipt, and recovery sequence. For API support or higher limits, contact [gm@vibechain.com](mailto:gm@vibechain.com). # List projected V9 markets Source: https://docs.vibechain.com/api-reference/retardmarket/markets/list-projected-v9-markets /api-reference/retardmarket_openapi.yml get /markets Returns official markets in deterministic cursor order from the finalized projection. # Preview a wrapper buy Source: https://docs.vibechain.com/api-reference/retardmarket/markets/preview-a-wrapper-buy /api-reference/retardmarket_openapi.yml get /markets/{market}/quote Returns a block-pinned, principal-only conservative preview. The quote is not a transaction and does not replace wallet-side simulation, slippage bounds, or a deadline. # Read one projected V9 market Source: https://docs.vibechain.com/api-reference/retardmarket/markets/read-one-projected-v9-market /api-reference/retardmarket_openapi.yml get /markets/{market} # Read the attributable trade tape Source: https://docs.vibechain.com/api-reference/retardmarket/markets/read-the-attributable-trade-tape /api-reference/retardmarket_openapi.yml get /markets/{market}/trades Includes official wrapper flows and exactly reconciled official-pool swaps. # Upload optional market image or video media Source: https://docs.vibechain.com/api-reference/retardmarket/media/upload-optional-market-image-or-video-media /api-reference/retardmarket_openapi.yml post /media Accepts one raw image or video body up to 5 MiB. # Evaluate one transaction for eligible points Source: https://docs.vibechain.com/api-reference/retardmarket/points/evaluate-one-transaction-for-eligible-points /api-reference/retardmarket_openapi.yml post /points/transactions/{transactionHash} # Read an auditable V9 points account Source: https://docs.vibechain.com/api-reference/retardmarket/points/read-an-auditable-v9-points-account /api-reference/retardmarket_openapi.yml get /points/{wallet} # Read one wallet's V9 positions and activity Source: https://docs.vibechain.com/api-reference/retardmarket/portfolio/read-one-wallets-v9-positions-and-activity /api-reference/retardmarket_openapi.yml get /portfolio/{wallet} # Connect to realtime V9 invalidation events Source: https://docs.vibechain.com/api-reference/retardmarket/realtime/connect-to-realtime-v9-invalidation-events /api-reference/retardmarket_openapi.yml get /stream Server-Sent Events stream. Attach `API-KEY` as a request header and use stream events to wake a durable REST snapshot refresh. Native browser EventSource cannot set headers; use a header-capable SSE client. # Read realtime hub readiness and counters Source: https://docs.vibechain.com/api-reference/retardmarket/realtime/read-realtime-hub-readiness-and-counters /api-reference/retardmarket_openapi.yml get /stream/stats # Check V9 HTTP readiness Source: https://docs.vibechain.com/api-reference/retardmarket/runtime/check-v9-http-readiness /api-reference/retardmarket_openapi.yml get /health # Read the attested V9 runtime Source: https://docs.vibechain.com/api-reference/retardmarket/runtime/read-the-attested-v9-runtime /api-reference/retardmarket_openapi.yml get /runtime Read this first and fail closed unless `enabled` and `publicEnabled` are both true. # vibe.market API Introduction Source: https://docs.vibechain.com/api-reference/vibemarket-intro Integrate with vibe.market packs, collections, creator tools, activity, social data, and analytics ## Overview The vibe.market API is the production HTTP interface behind [vibe.market](https://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 ```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", "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 ` | 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 ```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 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). # List recently updated packs Source: https://docs.vibechain.com/api-reference/vibemarket/activity/list-recently-updated-packs /api-reference/vibemarket_openapi.yml get /recent Cursor-paginated feed of recently minted, opened, burned, or assigned packs. A status of `opened` includes both burn and rarity-assignment records. Successful responses use a short shared-cache lifetime. # Recover events from a transaction Source: https://docs.vibechain.com/api-reference/vibemarket/activity/recover-events-from-a-transaction /api-reference/vibemarket_openapi.yml post /events/{txHash} Authenticated recovery path that replays supported pack events when normal indexing has not produced the expected state. Repeated requests may return a cached or already-processed result. # Add one allowlist entry Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/add-one-allowlist-entry /api-reference/vibemarket_openapi.yml post /metadata/draft/whitelist/entry # Bulk-add allowlist addresses Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/bulk-add-allowlist-addresses /api-reference/vibemarket_openapi.yml post /metadata/draft/whitelist/csv Validates, deduplicates, and adds up to 10,000 addresses parsed by the client from a CSV file. # Check allowlist eligibility Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/check-allowlist-eligibility /api-reference/vibemarket_openapi.yml get /whitelist/check/{slug} Returns whether an address is listed and, when eligible, the Merkle proof required by the launch flow. # Finalize a draft allowlist Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/finalize-a-draft-allowlist /api-reference/vibemarket_openapi.yml post /metadata/draft/whitelist/finalize Rebuilds and persists the Merkle tree for the current entries. # List a draft allowlist Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/list-a-draft-allowlist /api-reference/vibemarket_openapi.yml get /metadata/draft/whitelist/{draftId} # Remove one allowlist entry Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/remove-one-allowlist-entry /api-reference/vibemarket_openapi.yml delete /metadata/draft/whitelist/entry # Replace a draft allowlist Source: https://docs.vibechain.com/api-reference/vibemarket/allowlists/replace-a-draft-allowlist /api-reference/vibemarket_openapi.yml post /metadata/draft/whitelist Replaces all entries, updates the enabled state, and calculates a Merkle root. # Get collection price history Source: https://docs.vibechain.com/api-reference/vibemarket/analytics/get-collection-price-history /api-reference/vibemarket_openapi.yml get /price-chart/{contractAddress} Cache lifetime ranges from about one minute for `1h` to 30 minutes for `30d`. # Get one wallet's leaderboard statistics Source: https://docs.vibechain.com/api-reference/vibemarket/analytics/get-one-wallets-leaderboard-statistics /api-reference/vibemarket_openapi.yml get /leaderboard/{ownerAddress} # Get platform-wide market statistics Source: https://docs.vibechain.com/api-reference/vibemarket/analytics/get-platform-wide-market-statistics /api-reference/vibemarket_openapi.yml get /platform-stats Returns cached platform totals for the signed-in vibe.market user. This endpoint requires only Bearer authentication, not an API key, and uses the public-read IP allowance. # List the wallet leaderboard Source: https://docs.vibechain.com/api-reference/vibemarket/analytics/list-the-wallet-leaderboard /api-reference/vibemarket_openapi.yml get /leaderboard Results are cached for about five minutes. Unknown sort or time-period values fall back to `opened` and `alltime`. # Get collection statistics Source: https://docs.vibechain.com/api-reference/vibemarket/collections/get-collection-statistics /api-reference/vibemarket_openapi.yml get /collection/{contractAddress}/stats Returns pack, holder, and optional token-market statistics. Responses are cached for about 60 seconds. # Get one wallet's collection holdings Source: https://docs.vibechain.com/api-reference/vibemarket/collections/get-one-wallets-collection-holdings /api-reference/vibemarket_openapi.yml get /collection/{ownerAddress} Returns the collection-service view for a wallet and contract. Responses are cached for about 30 seconds. # List collection activity Source: https://docs.vibechain.com/api-reference/vibemarket/collections/list-collection-activity /api-reference/vibemarket_openapi.yml get /collection/{contractAddress}/events Returns collection events in descending chain order. Pass the returned block-number cursor to continue. Responses are cached for about 10 seconds. # Attach a deployment transaction to a draft Source: https://docs.vibechain.com/api-reference/vibemarket/creator-drafts/attach-a-deployment-transaction-to-a-draft /api-reference/vibemarket_openapi.yml post /metadata/confirm Confirms that a creator draft was deployed and records its transaction hash. # Create a complete metadata draft Source: https://docs.vibechain.com/api-reference/vibemarket/creator-drafts/create-a-complete-metadata-draft /api-reference/vibemarket_openapi.yml post /metadata/draft Creates a launch draft containing at least four card metadata items. The `creator` wallet must belong to the signed-in account. Use the poll endpoint instead when building an autosave workflow. # Create or autosave a metadata draft Source: https://docs.vibechain.com/api-reference/vibemarket/creator-drafts/create-or-autosave-a-metadata-draft /api-reference/vibemarket_openapi.yml post /metadata/draft/poll Upserts an in-progress draft. Pass its `draftId` on subsequent saves. Metadata may be empty while a creator is still configuring the launch. # Delete a draft Source: https://docs.vibechain.com/api-reference/vibemarket/creator-drafts/delete-a-draft /api-reference/vibemarket_openapi.yml delete /metadata/draft/id/{draftId} The signed-in account must control the draft creator. # Get a draft by ID Source: https://docs.vibechain.com/api-reference/vibemarket/creator-drafts/get-a-draft-by-id /api-reference/vibemarket_openapi.yml get /metadata/draft/id/{draftId} # Get a game by contract address Source: https://docs.vibechain.com/api-reference/vibemarket/games/get-a-game-by-contract-address /api-reference/vibemarket_openapi.yml get /games/{contractAddress} # List featured games Source: https://docs.vibechain.com/api-reference/vibemarket/games/list-featured-games /api-reference/vibemarket_openapi.yml get /featured Returns curated games ordered by trend, market cap, or recency. Responses are cached for about five minutes with shorter browser/shared cache headers. # List games Source: https://docs.vibechain.com/api-reference/vibemarket/games/list-games /api-reference/vibemarket_openapi.yml get /games # List games created by a wallet Source: https://docs.vibechain.com/api-reference/vibemarket/games/list-games-created-by-a-wallet /api-reference/vibemarket_openapi.yml get /games/creator/{ownerAddress} Optionally includes that wallet's unpublished drafts in a separate page. # Resolve a game by contract address or slug Source: https://docs.vibechain.com/api-reference/vibemarket/games/resolve-a-game-by-contract-address-or-slug /api-reference/vibemarket_openapi.yml get /contractAddress/{contractAddressOrSlug} Returns the launch and pricing configuration for one active game. Responses are cached briefly because pricing can change. # Search games Source: https://docs.vibechain.com/api-reference/vibemarket/games/search-games /api-reference/vibemarket_openapi.yml get /search Search by text, owner address, or both. This route has the lower search allowance of 25 requests per minute for a standard key. # Get all card metadata and odds Source: https://docs.vibechain.com/api-reference/vibemarket/metadata/get-all-card-metadata-and-odds /api-reference/vibemarket_openapi.yml get /contractAddress/{contractAddressOrSlug}/all-metadata Resolves a collection by address or slug and returns its active card metadata with calculated odds. Cached for about five minutes. # Get OpenSea-compatible collection metadata Source: https://docs.vibechain.com/api-reference/vibemarket/metadata/get-opensea-compatible-collection-metadata /api-reference/vibemarket_openapi.yml get /metadata/{slugOrContractAddress} Public collection metadata for a game slug. The response is an OpenSea collection object, not a vibe.market success envelope, and is cached for about five minutes. # Get OpenSea-compatible token metadata Source: https://docs.vibechain.com/api-reference/vibemarket/metadata/get-opensea-compatible-token-metadata /api-reference/vibemarket_openapi.yml get /metadata/{slug}/{tokenId} Public token metadata for NFT clients and marketplaces. The response is an OpenSea metadata object, not a vibe.market success envelope, and is cached for about five minutes. # List published card metadata Source: https://docs.vibechain.com/api-reference/vibemarket/metadata/list-published-card-metadata /api-reference/vibemarket_openapi.yml get /metadata Lists active card metadata for a collection contract. # Update a launched collection's metadata Source: https://docs.vibechain.com/api-reference/vibemarket/metadata/update-a-launched-collections-metadata /api-reference/vibemarket_openapi.yml put /metadata/{slugOrContractAddress} Replaces or revises card metadata for a launched contract. The signed-in account must control the collection creator. Set `noImageChange=true` to update collection-level fields without replacing card images. # Get one pack Source: https://docs.vibechain.com/api-reference/vibemarket/packs/get-one-pack /api-reference/vibemarket_openapi.yml get / Returns one pack by contract and token ID, with optional metadata and game details. # List packs in a token range Source: https://docs.vibechain.com/api-reference/vibemarket/packs/list-packs-in-a-token-range /api-reference/vibemarket_openapi.yml get /range Supply either `tokenIds` or both `startTokenId` and `endTokenId`. `forceRefreshState` schedules a background state refresh and should be reserved for recovery; repeated refreshes are internally throttled. # List packs owned by a wallet Source: https://docs.vibechain.com/api-reference/vibemarket/packs/list-packs-owned-by-a-wallet /api-reference/vibemarket_openapi.yml get /owner/{ownerAddress} Filters packs owned by an EVM address. Set `groupBy=contract` or `groupCommonRarity=true` to receive grouped results instead of a flat list. # Refresh pack state from chain Source: https://docs.vibechain.com/api-reference/vibemarket/packs/refresh-pack-state-from-chain /api-reference/vibemarket_openapi.yml post /{contractAddress}/{tokenId}/refresh Queues one or more pack-state refreshes. `tokenId` may be a single ID or a comma-separated list. Cooldown, in-progress, no-update, and queued states all return HTTP 200; inspect the response `status`. # Resolve rarity assignments from a transaction Source: https://docs.vibechain.com/api-reference/vibemarket/packs/resolve-rarity-assignments-from-a-transaction /api-reference/vibemarket_openapi.yml get /rarity Parses pack token IDs and rarity assignments from a transaction receipt. A missing receipt or still-pending assignment is represented by HTTP 200; inspect `receiptFound`, `rarityCode`, and `isPending`. # List market chat messages Source: https://docs.vibechain.com/api-reference/vibemarket/social/list-market-chat-messages /api-reference/vibemarket_openapi.yml get /chat-messages Cursor-paginated chat and system activity. Responses are cached for about 60 seconds with shorter shared-cache headers. # React to a chat message Source: https://docs.vibechain.com/api-reference/vibemarket/social/react-to-a-chat-message /api-reference/vibemarket_openapi.yml post /chat-messages/{messageId}/react # Report a collection Source: https://docs.vibechain.com/api-reference/vibemarket/social/report-a-collection /api-reference/vibemarket_openapi.yml post /report/{contractAddress} Creates one abuse report from the signed-in account. This endpoint is Bearer-only and limited to 10 requests per hour per IP; duplicate reports can also return `429`. # Check whether a slug is available Source: https://docs.vibechain.com/api-reference/vibemarket/utility/check-whether-a-slug-is-available /api-reference/vibemarket_openapi.yml get /check-slug/{slug} # Check whether collection metadata is ready Source: https://docs.vibechain.com/api-reference/vibemarket/utility/check-whether-collection-metadata-is-ready /api-reference/vibemarket_openapi.yml get /contractAddress/{contractAddressOrSlug}/ready A missing or still-processing collection is represented by HTTP 200 with `ready: false`. # Check whether unboxing is regionally disallowed Source: https://docs.vibechain.com/api-reference/vibemarket/utility/check-whether-unboxing-is-regionally-disallowed /api-reference/vibemarket_openapi.yml get /unboxing-disallowed Uses the request's edge-derived country and currently returns `true` for Belgium, the Netherlands, and France. # Generate a normalized game slug Source: https://docs.vibechain.com/api-reference/vibemarket/utility/generate-a-normalized-game-slug /api-reference/vibemarket_openapi.yml post /generate-slug # Get the current ETH/USD price Source: https://docs.vibechain.com/api-reference/vibemarket/utility/get-the-current-ethusd-price /api-reference/vibemarket_openapi.yml get /eth-price Returns the server's current cached ETH/USD price. The cache lifetime is about 60 seconds. # Careers Source: https://docs.vibechain.com/docs/careers # Vibechain - Software Engineer **Location**: Remote, United States ### Job Summary At Vibechain, we're building on the frontier of crypto through [vibe.market](https://vibe.market). We are seeking a highly experienced Software Engineer who is both passionate about the future of crypto and also excels in building the frontier of tech. ### Job Responsibilities * Lead the development and enhancement of features for our applications, including [vibe.market](https://vibe.market). * Drive the full software development lifecycle, from conception to deployment, ensuring high standards of quality and efficiency. * Architect and implement solutions using modern technologies like React, Node.js, MongoDB, Expo, AWS, GCE, Cloudflare, and Docker, AI tooling (like Claude Code, OpenAI, Anthropic, Hugging Face) while contributing significantly to our open-source repositories. * Oversee the testing, troubleshooting, and optimization of application performance, ensuring scalability and reliability. * Facilitate and lead brainstorming sessions, providing innovative ideas and strategic direction for future projects. * Proactively stay updated with the latest crypto trends and technologies, and apply this knowledge to drive continuous improvement and innovation. ### Required Skills * Deep expertise in Node.js, MongoDB, React, and Javascript, with a continuous drive for learning and adopting new technologies. * Extensive experience with cloud services (AWS, GCE), AI tooling (like Claude Code, OpenAI, Anthropic, Hugging Face), and web performance optimization tools (e.g. Cloudflare). * Advanced knowledge and practical experience with containerization technology, preferably Docker. * Exceptional problem-solving skills and a demonstrated passion for crypto. * Proven ability to work collaboratively in a team environment. * Excellent communication skills, with a strong aptitude for mentoring and learning new technologies. * Previous significant experience with open-source projects and a strong contributor to the open-source community is a plus. ### Compensation and Benefits Information We offer a competitive salary that includes healthcare, denominated in US Dollars ($125,000-$200,000/year), with startup equity. As a remote company, you can work anywhere in the United States with work authorization. ### Apply Email us at [careers@vibechain.com](mailto:careers@vibechain.com) with your resume and a short intro! # Vibechain - Software Engineering Intern **When**: Flexible\ **Location**: Remote, United States ### Job Summary At Vibechain, we're building on the frontier of crypto through [vibe.market](https://vibe.market). We're inviting a Software Engineering Intern who is passionate about the future of crypto and eager to work on the frontier. ### Job Responsibilities * Collaborate with a dynamic team to develop and enhance features for our applications, including [vibe.market](https://vibe.market). * Engage in the full software development lifecycle, from conception to deployment. * Work with modern technologies like React, Node.js, MongoDB, Expo, AWS, GCE, Cloudflare, Docker, AI tooling (like Claude Code, OpenAI, Anthropic, Hugging Face). * Test, troubleshoot, and optimize application performance. * Participate in brainstorming sessions, contributing innovative ideas for future projects. * Stay updated with the latest crypto trends and technologies. ### Required Skills * A core understanding of Node.js, MongoDB, React, and Javascript, with an eagerness to learn more. * Familiarity with cloud services (AWS, GCE), AI tooling (like Claude Code, OpenAI, Anthropic, Hugging Face), and web performance optimization tools (e.g. Cloudflare). * Knowledge of containerization technology, preferably Docker. * Strong problem-solving skills and a passion for crypto. * Ability to work collaboratively in a team environment. * Good communication skills, with an aptitude for learning new technologies. * Previous experience with open-source projects is a plus. ### Compensation and Benefits Information We offer a competitive internship salary that includes healthcare, denominated in US Dollars (\$30-60/hour). As a remote company, you can work anywhere in the United States with work authorization. ### Apply Email us at [careers@vibechain.com](mailto:careers@vibechain.com) with your resume and a short intro! # Another Role In Mind? While we don't have any active openings besides what you see here, feel free to email us at [careers@vibechain.com](mailto:careers@vibechain.com) with your resume and a short intro for what you'd have in mind! # Getting Started with vibe.market Source: https://docs.vibechain.com/docs/vibemarket vibe.market ## What is [vibe.market](https://vibe.market)? [vibe.market](https://vibe.market) brings trading card booster packs onchain! Like Pokémon or Yu-Gi-Oh!, but every pack, card, and trade lives on Base. * Buy Liquid Booster Packs with ETH * Open to reveal Liquid Trading Cards (LTC) with different rarities * Optionally sell Liquid Trading Cards for tickets * Randomness and rarity generation is public - build anything on top * Card links allow music, video, and broad experimentation ## How It Works Each pack costs a fixed amount of tickets (for example, 100,000 tickets). During preorder, ticket prices may vary (example range: `$0.002` to `$0.20` each), making pack costs variable (example: `$0.20` to `$20`). Open your pack to reveal a digital collectible card with random rarity. Cards can optionally be exchanged for tickets through the collection's smart contracts (subject to availability). ### Wear & Foil Cards can have additional random attributes generated onchain: * **Wear**: Card condition from pristine (0.0) to heavily worn (1.0) * **Foil**: Special effects like Prize Foil (example: \~0.05%) or Standard Foil (example: \~0.5%) Foil and wear add depth and collectibility similar to graded shiny Pokémon/Yu-Gi-Oh! cards. Creators can disable these features, but are highly encouraged to kept them on. ### Unopened Packs Unopened packs may optionally be redeemed for tickets (example: 80,000-100,000 tickets or 80-100% of the original cost \[100% for contracts deployed after August 1st, 2025]). This feature's availability depends on the specific collection. ## Market Phases ### Preorder (Bonding Curve) * Ticket prices start low and increase as more are bought * Progress bar shows advancement to graduation goal (example: 2.5 ETH) * Creator earns a percentage of all trades (example: 2%) ### Graduation When the collection reaches its graduation threshold (example: 2.5 ETH): * A portion of tokens moves to Uniswap V3 pool (example: 5%) * The rest of tokens is locked in the contract to facilitate exchanges of tickets * Trading shifts from bonding curve to open market * Creator earns a percentage of all Uniswap trades (example: 0.5%) ## Fees **Trading Fee**: A percentage fee on all transactions (example: 7.5% total) Example fee distribution: * Creator: 40% * Referrers: 10% * Platform: 50% (w/ 10% origin fee) **Opening Fee**: Small fee for onchain randomness via [Pyth Network](https://www.pyth.network/) (example: \~\$0.01) *Note: All fees and percentages shown are examples. Actual values are determined by a collection's smart contracts.* ## For Builders * Randomness and rarity generation happens onchain via [Pyth Network](https://www.pyth.network/) * Query any public RPC to access card attributes * Build games, marketplaces, or apps on any collection * Earn referral fees by integrating pack sales (example: up to 10% of contract fees) * No permission needed - deploy packs via our interfaces without [vibe.market](https://vibe.market) See [developer docs](/docs/vibemarket/developers) for contract interfaces and examples. ## Important Notes * Digital collectibles intended solely for personal enjoyment, collection, and entertainment purposes * Every pack purchase receives a digital collectible LTC (Liquid Trading Card) * All numerical values shown are examples only - actual values vary by collection * Parameters may vary by collection * An older version of vibe.market contracts with factory 0xddb8a2f1fc79898df9854acef7d15729817bc07e had Mythics require a certain amount of fee volume (20M mythic tickets were paid by 10M tickets from drop contract fees) - all versions after allow Mythics to sell even if they are the first card pulled. * See [Terms of Service](https://vibechain.com/tos) ## Get Started [vibe.market](https://vibe.market) - Connect wallet and start collecting [Discord](https://discord.gg/MfsS9Yfqae) - Join the community [.vibe domains](https://vibechain.com) - buy a .vibe domain and show support ## For AI Agents ```bash theme={null} curl -s https://vibechain.com/skill.md ``` 1. Run the command above to get started 2. Get your free API key from [docs.vibechain.com](https://docs.vibechain.com/api-reference/vibemarket-intro) 3. Browse packs, check rarities, mint and trade! ## Additional Resources Learn how to create and launch your own Booster Pack collection Integrate with vibe.market smart contracts and build on the platform Skill file for AI agents to interact with vibe.market programmatically # Build with the vibe.market API Source: https://docs.vibechain.com/docs/vibemarket/api Choose the right vibe.market endpoints, credentials, and integration flow The vibe.market API covers the same production resources used by the web app: games, packs, card metadata, creator drafts, allowlists, collection activity, chat, price history, leaderboards, and platform analytics. Browse every operation, parameter, request body, response schema, auth rule, status code, and cache note. ## Start with the resource you need | Goal | Recommended operation | | ----------------------------- | ----------------------------------------------------------- | | Discover launches | `GET /featured`, `GET /games`, or `GET /search` | | Resolve one game | `GET /contractAddress/{contractAddressOrSlug}` | | Read a wallet's packs | `GET /owner/{address}` | | Read recent activity | `GET /recent` or `GET /collection/{contractAddress}/events` | | Read cards and odds | `GET /contractAddress/{contractAddressOrSlug}/all-metadata` | | Build a creator autosave flow | `POST /metadata/draft/poll` | | Manage a gated launch | `/metadata/draft/whitelist/*` | | Check post-deploy processing | `GET /contractAddress/{contractAddressOrSlug}/ready` | | Recover a missed transaction | `POST /events/{txHash}` | | Build analytics | `/price-chart/*`, `/leaderboard*`, and `/platform-stats` | ## Credentials Most reads require `API-KEY`. Creator and recovery writes require both `API-KEY` and `Authorization: Bearer ` because the server also checks the account's linked wallets. The public OpenSea metadata routes need no credential. Reports and platform stats are Bearer-only. The reference marks these exceptions per operation. ## Production integration rules * Preserve Wei values as decimal strings until converting with a big-integer or decimal library. * Treat cursor values as opaque and follow the returned cursor until it is absent. * Expect short server caches on feeds and longer caches on stable metadata. * Back off with jitter after `429`; a missing or invalid API key deliberately uses the same status as an exhausted API-key quota. * Inspect body states on HTTP `200`. Pending rarity, slug availability, readiness, refresh cooldowns, and missing receipts are not transport errors. * Persist draft IDs and deployment transaction hashes so creator flows can be resumed safely. The production base URL is: ```text theme={null} https://build.vibechain.com/vibe/boosterbox ``` Create a free API key and see runnable examples in the [API introduction](/api-reference/vibemarket-intro). # Creating Booster Packs Source: https://docs.vibechain.com/docs/vibemarket/creators vibe.market lets you create and collect digital collectible booster packs - like Pokémon or Yu-Gi-Oh! cards but fully onchain. Every pack contains digital collectible LTCs (Liquid Trading Cards) for personal enjoyment and entertainment. All randomness, rarity, and card data is public and verifiable through any RPC. With card links, and with a website link for packs, you are free to experiment with music, videos, and other formats for your pack! We support any type of link for both cards & packs, from YouTube to Spotify. **For Creators**: Upload images, deploy a collection, earn fees from trading\ **For Developers**: Build on top of any collection permissionlessly - check the [developer docs](/docs/vibemarket/developers)\ **Support**: [Discord](https://discord.gg/MfsS9Yfqae) ## How it works **The Process:** 1. User opens pack → Receives a digital collectible LTC (Liquid Trading Card) with random rarity 2. User may optionally exchange LTC (Liquid Trading Card) to contract → Burns LTC (Liquid Trading Card) and receives tickets (if feature is available) 3. User may trade tickets → Receives ETH based on current market price ### Creator Fee Structure #### Preorder Phase (Bonding Curve) ``` Example Fee Structure: Total Fee: 7.5% on all buys and sells ├── Creator: 40% (2% of transaction) ├── Referrer: 10% (0.5% of transaction) └── Platform: 50% (2.5% of transaction, w/ 10% origin fee) *Note: These percentages are examples. Actual fees vary by collection.* ``` #### Post-Graduation (Uniswap) ``` Example Uniswap LP Fees: 1% on all trades ├── Creator: 50% (0.5% of transaction) └── Liquidity Providers: 50% (0.5% of transaction) *Note: These percentages are examples. Actual fees vary by collection.* ``` ### How Pricing Works **Preorder Phase:** * Tickets start cheap and increase as more are bought (bonding curve) * Example price range: `$0.002 - $0.20` per ticket (example based on ETH = \~\$2000, subject to market fluctuation) * Example: 100k tickets (1 pack) might cost: `$0.20 - $20` * Cards are rarity based, for example: Common = 66.53%, Rare = 24%, Epic = 9%, Legendary = 0.45%, Mythic = 0.02% (exact numbers are based on contract implementation) * Note: an older version of vibe.market contracts with factory 0xddb8a2f1fc79898df9854acef7d15729817bc07e had Mythics require a certain amount of fee volume (20M mythic tickets were paid by 10M tickets from drop contract fees) - all versions after allow Mythics to sell even if they are the first card pulled. **Post-Graduation:** * Price determined by Uniswap market (supply/demand) * No fixed price range - fully market driven ## Complete Creator Journey ``` 1. CREATE COLLECTION │ ├─→ Upload 4-1000 images ├─→ Set name & symbol ├─→ Choose fee recipient └─→ Deploy contracts 2. PREORDER PHASE (Bonding Curve) │ ├─→ Users buy tickets (100k = 1 pack) ├─→ Example price: $0.20 → $20 per pack ├─→ You earn a percentage of all trades (example: 2%) └─→ Progress bar fills to graduation threshold (example: 2.5 ETH) 3. GRADUATION │ ├─→ A portion of tokens go to Uniswap (example: 5%) ├─→ The rest of tokens is locked in the contract to facilitate exchanges of tickets ├─→ Trading moves to Uniswap └─→ Price becomes market-driven 4. POST-GRADUATION │ ├─→ Users trade on Uniswap ├─→ You earn a percentage of all trades (example: 0.5%) └─→ Collect fees via My Creations ``` ## Frequently Asked Questions ### Creating Booster Packs **How many images can I upload to a booster pack?** You can upload up to 1,000 images per booster pack. When uploading in batches, you can select up to 100 files at once. **What image formats are supported?** All standard non-animated image formats are supported (PNG, JPG, WebP). We use WebGL for some parts of vibe.market, hence this restriction - animations would require spritesheets if we support it in the future. **What are the pack name requirements?** Pack names can be up to 18 characters long and will be used to generate a unique URL for your pack. **Can I customize the token symbol?** Yes, you can set a custom token symbol up to 5 characters long. The symbol will automatically be converted to uppercase. **Can I set a custom address as the fee recipient of the collection?** Yes, you can set a custom address as the fee recipient. **Make sure it is a wallet or smart wallet and you have ownership privileges.** If you want to split the fee between multiple addresses, we recommend setting up something like 0xSplit smart wallets. **Can I edit my pack after creating it?** You can edit the metadata and images of your pack, but certain core parameters like the contract address and token symbol cannot be changed after deployment. You can add more images to the collection later, and existing mints won't be affected. **How do I collect my fees?** Preorder fees are automatically collected to the address you provided when creating the pack. Uniswap trading fees can be collected by going to My Creations → Select your collection → Rewards. ### Collection Design and Creation **How do I assign rarities to my pack images?** You can manually assign rarities to specific images - rarities are automatically assigned when users open packs using verifiable onchain randomness from [Pyth Network](https://www.pyth.network/). There are 5 rarity tiers: Common, Rare, Epic, Legendary, and Mythic. **What is the optimal number of images for a collection?** While you can upload between 4 and 1,000 images, the optimal collection size depends on your goals: * **Small collections (10-50 images)**: Easier to curate and maintain consistent quality * **Medium collections (50-200 images)**: Good balance of variety and manageability * **Large collections (200-1,000 images)**: Maximum variety but requires more curation effort **What image dimensions should I use?** There are no strict dimension requirements. Images are automatically processed by Cloudflare Images to create optimized variants. However, we recommend: * Using consistent dimensions across your collection for visual cohesion * Minimum 609x864 pixels for good quality on all devices, maximum 10MB / 100 megapixels (10,000×10,000) * A trading card aspect ratio works best for the pack display format **Can I use GIF images in my pack?** No, animated GIFs are not currently supported. You can only use static image formats: PNG, JPG/JPEG, and non-animated WebP files. **Can I upload a custom pack cover image?** Yes, you can upload a custom cover image for your booster pack. The cover image is what users see before opening the pack and helps make your collection stand out. We recommend using eye-catching artwork that represents the theme of your collection. ### Pricing and Economics **How much does it cost to mint a pack?** Buying a booster pack requires a fixed amount of tickets (example: 100K tickets or their equivalent in ETH). Each booster pack collection has its own unique ticket system. During the preorder phase, pack prices may vary (example range: `$0.20` to `$20` per pack). After graduation, pricing is determined by market forces through decentralized exchanges like Uniswap. **How much do I earn as a creator?** Creators earn fees from trading activity: Example creator earnings: * **Percentage of all token transactions** (example: 2%, which is 40% of a 7.5% total fee) * **Portion of Uniswap V3 trading fees** after graduation (example: 50%) *Note: Actual percentages are determined by a collection's smart contracts.* **Can I provide my own memecoin for my collection?** No, each collection automatically creates its own ERC20 token (memecoin) during deployment. ### Collection Mechanics **How many packs can exist in my collection?** There's no hard limit on the number of packs that can be minted. However, the associated token typically has a maximum supply (example: 1 billion tokens), and each pack mint requires tokens (example: 100,000 tokens), creating a natural scarcity mechanism. **Are cards randomly assigned on open?** Yes, cards are randomly assigned when packs are opened. You can access the random number generated onchain by querying any public RPC URL on Base. **What is the "Preorder" phase?** The preorder phase is the bonding curve period before "graduation": * Collections start with tokens traded on an automated bonding curve * The progress bar shows advancement toward the graduation goal (example: 2.5 ETH) * Once graduated, a portion of token supply moves to a Uniswap V3 liquidity pool (example: 5%) * The rest of tokens is locked in the contract to facilitate exchanges of tickets * After graduation, trading happens on Uniswap instead of the bonding curve **What are foils and wear, and can I disable them?** Foils and wear are pure crypto randomness features generated onchain to boost collectibility, similar to shiny Pokémon/Yu-Gi-Oh! cards. You can disable these features by editing the collection settings. **How do I get verified?** Verifications are automatic based on volume, we rarely manually verify unless absolutely necessary. **How many cards are in each pack?** Each booster pack contains 1 card. **How can I add special features for rare cards?** You are free to build on top of your trading cards - but you'll have to maintain your own website, etc for your special features! All randomness and rarity data is stored onchain and can be accessed by querying any public RPC URL, making it easy to integrate special features based on card rarity. See the [developer docs](/docs/vibemarket/developers) for more information on accessing this data. **Can I have a "NSFW" Pack?** For economic reasons, we heavily discourage "NSFW packs" because this would lead to these packs being blurred on our frontpage or removed completely, leading to significantly less mints - on top of social networks censoring your link sharing. We recommend an alterate art approach - make the cards/pack social network friendly, and in the description of the pack or via card links, tell users to visit your website for the full "alternate art". **What links are supported for packs?** We support any links for packs and cards! That includes YouTube, Spotify, Soundcloud, or any other hosting service you prefer. **How do I show support for vibe.market?** Besides being involved in our community, you can buy a [.vibe domain](https://vibechain.com) and show support! ### Technical and License Questions **Can I apply referral to my own collection?** Yes, you need to link directly to your collection eg collection-link/0x123...?referrer=YOUR\_ADDRESS **Can I sell the LTC (Liquid Trading Card) without burning it? Are the LTCs (Liquid Trading Cards) compatible with third party marketplaces?** Yes, it is a standard LTC (Liquid Trading Card) and you can trade on any secondary marketplaces like OpenSea, Rarible, Magic Eden. **Who owns the rights to the images in my pack?** As the pack creator, you retain ownership of your uploaded images. However, by creating a pack on vibe.market, you grant an irrevocable, perpetual, worldwide, royalty-free license to all third parties building on vibe.market to use, reproduce, modify, remix, and commercialize your artwork. This includes the right to incorporate your art into their own booster pack products, games, or applications. This license encourages a vibrant ecosystem of creativity and remixability within the vibe.market community. **What licenses apply to vibe.market?** Please refer to our [Terms of Service](https://vibechain.com/tos) for complete licensing and usage terms. All LTCs (Liquid Trading Cards) and tokens are digital collectibles intended solely for personal enjoyment, collection, and entertainment purposes. Every booster pack purchase receives a digital collectible LTC (Liquid Trading Card). #### Why is the license so broad? The broad license enables a thriving ecosystem where developers can build innovative experiences without legal friction. Imagine someone creating an onchain solitaire game that uses any vibe.market cards - they'd need permission from hundreds of artists without this license. While this means your art is being "commercialized," it also means more exposure and potential sales for your collection. The practical challenges of a restrictive license are significant. Games that dynamically load vibe.market inventories would need to credit hundreds of packs that change daily. Even vibe.market's own unboxing experience technically "modifies and commercializes" your pack. A more specific license would be very difficult to broaden later, limiting usage of booster packs. The onchain nature of vibe.market provides inherent protection - all data is verifiable and fakes rarely succeed, similar to how countless cryptopunk derivatives exist but the originals maintain their value. This open approach encourages creativity and remixability within the community while maintaining the authenticity of your original work. # Developer Documentation Source: https://docs.vibechain.com/docs/vibemarket/developers Build on vibe.market's smart contracts to create your own integrations, trading bots, or applications for digital collectibles. ## Smart Contract Addresses All vibe.market contracts are deployed on Base. Each booster pack collection has its own contract addresses for the LTC (Liquid Trading Card) (BoosterDropV2) and token (BoosterTokenV2). **Source availability**: The core vibe.market booster contracts are now source-available in [`wieldlabs/contracts`](https://github.com/wieldlabs/contracts/tree/main/vibemarket). This includes `BoosterDropV2`, `BoosterTokenV2`, `BoosterDeployerFactoryV2`, `BoosterBondingCurveV2`, `BoosterCardSeedUtils`, and the canonical interfaces under the licenses in each source file. We also continue to run security scanning via [Almanax](https://www.almanax.ai/). View the complete smart contract interfaces View the canonical vibe.market contract sources on GitHub ## Common Use Cases ### 1. Buying Booster Packs Purchase digital collectible booster packs programmatically and earn referral fees. ```javascript theme={null} // Using ethers.js v6 import { ethers } from "ethers"; // Connect to provider const provider = new ethers.JsonRpcProvider("https://base.llamarpc.com"); const signer = new ethers.Wallet(PRIVATE_KEY, provider); // BoosterDropV2 contract const boosterDrop = new ethers.Contract( BOOSTER_DROP_ADDRESS, IBoosterDropV2_ABI, signer ); // Get mint price for packs (example: 5 packs) const mintPrice = await boosterDrop.getMintPrice(5); // Mint packs with referral (earn fees!) await boosterDrop.mint( 5, // amount of packs signer.address, // recipient YOUR_ADDRESS, // referrer (example: earn portion of fees) YOUR_ADDRESS, // originReferrer (example: earn additional portion) { value: mintPrice } // ETH payment ); ``` ### 2. Selling Tickets (Tokens) Trade collectible tokens through the bonding curve or Uniswap pool. ```javascript theme={null} // BoosterTokenV2 contract const boosterToken = new ethers.Contract( BOOSTER_TOKEN_ADDRESS, IBoosterTokenV2_ABI, signer ); // Check current market type const marketType = await boosterToken.marketType(); // 0 = BONDING_CURVE, 1 = UNISWAP_POOL // Get sell quote for tokens (example: 100,000 tokens) const tokenAmount = ethers.parseUnits("100000", 18); const ethReceived = await boosterToken.getTokenSellQuote(tokenAmount); // Sell tokens with slippage protection const minPayout = (ethReceived * 98n) / 100n; // Example: 2% slippage await boosterToken.sell( tokenAmount, signer.address, // recipient of ETH minPayout, // minimum ETH to accept YOUR_ADDRESS, // referrer YOUR_ADDRESS // originReferrer ); ``` ### 3. Opening Packs and Getting Randomness Open packs to reveal rarity using [Pyth Network](https://www.pyth.network/) entropy. ```javascript theme={null} // Get entropy fee required for opening const entropyFee = await boosterDrop.getEntropyFee(); // Open multiple packs (requires ETH for entropy) const tokenIds = [1, 2, 3]; // Your unopened pack token IDs await boosterDrop.open(tokenIds, { value: entropyFee }); // Get rarity info after randomness is fulfilled const rarityInfo = await boosterDrop.getTokenRarity(tokenIds[0]); console.log({ rarity: rarityInfo.rarity, // 1=Common, 2=Rare, 3=Epic, 4=Legendary, 5=Mythic randomValue: rarityInfo.randomValue, randomness: rarityInfo.tokenSpecificRandomness, }); ``` ### 4. Selling LTCs (Liquid Trading Cards) for Token Offers Sell both opened and unopened packs back to the contract. ```javascript theme={null} // Sell single LTC (Liquid Trading Card) (opened or unopened) await boosterDrop.sellAndClaimOffer(tokenId); // Batch sell multiple LTCs (Liquid Trading Cards) const tokenIds = [1, 2, 3]; await boosterDrop.sellAndClaimOfferBatch(tokenIds); // Exchange values are examples only - actual values vary by collection: // Unopened packs example: 80,000-100,000 tokens (80-100% of mint cost) [100% for packs created after August 1st, 2025] // Opened packs examples based on rarity: // - Common: 20,000 tokens (example) // - Rare: 120,000 tokens (example) // - Epic: 420,000 tokens (example) // - Legendary: 3,000,000 tokens (example) // - Mythic: 10,000,000 tokens (example) // Note: This optional exchange feature may not be available for all collections ``` ### 5. Reading Onchain Data Access all card data directly from the blockchain. ```javascript theme={null} // Check if pack is opened by getting rarity try { const rarityInfo = await boosterDrop.getTokenRarity(tokenId); console.log("Pack is opened, rarity:", rarityInfo.rarity); } catch { console.log("Pack is unopened"); } // Track mint events const mintFilter = boosterDrop.filters.BoosterDropsMinted(); const mintEvents = await boosterDrop.queryFilter(mintFilter); // Track pack openings const openFilter = boosterDrop.filters.BoosterDropOpened(); const openEvents = await boosterDrop.queryFilter(openFilter); // Get token metadata URI const tokenURI = await boosterDrop.tokenURI(tokenId); ``` ### 6. Building Games with vibe.market Cards ```javascript theme={null} // Track user's cards via transfer events const userAddress = "0x..."; const transferFilter = boosterDrop.filters.BoosterDropTransfer( null, userAddress ); const transferEvents = await boosterDrop.queryFilter(transferFilter); // Get card details including randomness for game mechanics const userCards = []; for (const event of transferEvents) { const tokenId = event.args.tokenId; try { const rarityInfo = await boosterDrop.getTokenRarity(tokenId); userCards.push({ tokenId, rarity: rarityInfo.rarity, randomValue: rarityInfo.randomValue, // Use for game RNG randomness: rarityInfo.tokenSpecificRandomness, // Unique per card isOpened: true, }); // Use randomness for unique card attributes (example values) const uniqueSeed = rarityInfo.randomValue; const attackPower = 100 + (uniqueSeed % 50); // Example calculation const defense = 80 + (uniqueSeed % 30); // Example calculation } catch { // Rarity not defined - pack hasn't been opened yet userCards.push({ tokenId, rarity: 0, isOpened: false, }); } } // Grant game benefits based on collection const legendaryCount = userCards.filter((c) => c.rarity === 4).length; const mythicCount = userCards.filter((c) => c.rarity === 5).length; if (mythicCount > 0) { // Unlock ultra-rare game features } else if (legendaryCount > 0) { // Unlock special game features } ``` ### 7. Onchain Wear & Foil We deployed the following source-available contract at [0x002aaaa42354bf8f09f9924977bf0c531933f999](https://basescan.org/address/0x002aaaa42354bf8f09f9924977bf0c531933f999#code) that allows you to query wear and foil onchain from `getTokenRarity` using `tokenSpecificRandomness`. `0.5%` of cards are standard foil, and `0.05%` of cards are prize foil. Wear is distributed between `0` and `1`. ```javascript theme={null} // IBoosterCardSeedUtils contract address on Base const SEED_UTILS_ADDRESS = "0x002aaaa42354bf8f09f9924977bf0c531933f999"; // Connect to the BoosterCardSeedUtils contract const seedUtils = new ethers.Contract( SEED_UTILS_ADDRESS, IBoosterCardSeedUtils_ABI, provider ); // Get rarity info from a card (must be opened) const tokenId = 123; // Your opened pack token ID const rarityInfo = await boosterDrop.getTokenRarity(tokenId); // Use tokenSpecificRandomness as the seed for wear & foil const seed = rarityInfo.tokenSpecificRandomness; // Get wear value (string with 10 decimal places, e.g., "0.1234567890") const wear = await seedUtils.wearFromSeed(seed); console.log("Card wear:", wear); // Get foil type (returns "Prize", "Standard", or "Normal") const foilType = await seedUtils.getFoilMappingFromSeed(seed); console.log("Card foil:", foilType); // Get both wear and foil in a single call const cardData = await seedUtils.getCardSeedData(seed); console.log({ wear: cardData.wear, // e.g., "0.0123456789" foilType: cardData.foilType, // e.g., "Normal", "Standard", or "Prize" }); // Example: Process multiple cards to get their wear & foil const userCards = [101, 102, 103]; // Token IDs of opened packs const cardDetails = []; for (const tokenId of userCards) { try { const rarityInfo = await boosterDrop.getTokenRarity(tokenId); const [wear, foilType] = await seedUtils.getCardSeedData( rarityInfo.tokenSpecificRandomness ); cardDetails.push({ tokenId, rarity: rarityInfo.rarity, wear, foilType, // Use wear for game mechanics condition: parseFloat(wear) < 0.05 ? "Pristine" : parseFloat(wear) < 0.2 ? "Mint" : parseFloat(wear) < 0.45 ? "Lightly Played" : parseFloat(wear) < 0.75 ? "Moderately Played" : "Heavily Played", }); } catch (error) { console.log(`Token ${tokenId} is unopened or invalid`); } } // Build game features based on foil & wear const prizeCards = cardDetails.filter((c) => c.foilType === "Prize"); const mintConditionCards = cardDetails.filter((c) => parseFloat(c.wear) < 0.05); ``` ### 8. Card Rarity Distribution Cards in a pack are mapped to specific random value ranges based on their `randomValue`. When a pack is opened, the on-chain randomness generates a value between 0-999,999 returned in `randomValue` from `getTokenRarity()`. **Example Random Value Mapping:** ``` Random Value Range (0 - 999,999) ├─ Mythic (0 - 199): 0.02% │ └─ Cards split range evenly (e.g., 5 cards = ~40 values each) ├─ Legendary (200 - 4,699): 0.45% │ └─ Cards split range evenly (e.g., 10 cards = ~450 values each) ├─ Epic (4,700 - 94,699): 9.0% │ └─ Cards split range evenly (e.g., 20 cards = ~4,500 values each) ├─ Rare (94,700 - 334,699): 24.0% │ └─ Cards split range evenly (e.g., 30 cards = ~8,000 values each) └─ Common (334,700 - 999,999): 66.53% └─ Cards split range evenly (e.g., 40 cards = ~16,625 values each) ``` ## Important Considerations **Note**: All numerical values in code examples are for illustration purposes only. Actual values, fees, and percentages are determined by a collection's smart contracts and may vary significantly. These digital collectibles are intended solely for personal enjoyment and entertainment. * **Gas Optimization**: Batch operations when possible (e.g., opening multiple packs at once) * **Slippage Protection**: Always use `minPayoutSize` when selling tokens * **Referral System**: Include referral addresses to earn trading fees (example: 1% of trades, which might be 20% of a 7.5% total fee) * **Market State**: Check if market is on bonding curve or Uniswap before trading * **Entropy Fees**: Opening packs requires a small ETH fee for [Pyth Network](https://www.pyth.network/) randomness (example: \~\$0.01) * **Token Offers**: The optional LTC (Liquid Trading Card) exchange feature mints new tokens when available - this feature is not guaranteed and varies by collection ## Next Steps * Review the [contract interfaces](/docs/vibemarket/developers/interfaces) for complete method signatures * Review the [source-available contracts](https://github.com/wieldlabs/contracts/tree/main/vibemarket) for the canonical implementations * Join our [Discord](https://discord.gg/MfsS9Yfqae) for developer support # Smart Contract Interfaces Source: https://docs.vibechain.com/docs/vibemarket/developers/interfaces **Important Note**: These interfaces define the structure for vibe.market's digital collectible smart contracts. All numerical values, percentages, and fees shown in implementations are examples only and vary by collection. These contracts power digital collectibles intended solely for personal enjoyment, collection, and entertainment purposes. Every booster pack purchase results in receiving a digital collectible LTC (Liquid Trading Card). The canonical source-available files live in [`wieldlabs/contracts`](https://github.com/wieldlabs/contracts/tree/main/vibemarket). Use the GitHub files as the source of truth; the snippets below are included for quick reference. ## IBoosterDropV2 The `IBoosterDropV2` interface defines the LTC (Liquid Trading Card) contract that handles minting, opening, and exchanging digital collectible booster packs. * Canonical interface: [`interfaces/v2/IBoosterDropV2.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/interfaces/v2/IBoosterDropV2.sol) * Canonical implementation: [`v2/BoosterDropV2.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/v2/BoosterDropV2.sol) ```solidity theme={null} // SPDX-License-Identifier: BUSL-1.1 // Copyright (C) 2025 Beb, Inc. All Rights Reserved pragma solidity ^0.8.27; /** * @title IBoosterDropV2 * @dev Interface for the BoosterDropV2 contract */ interface IBoosterDropV2 { // Rarity level constants // uint8 public constant RARITY_COMMON = 1; // uint8 public constant RARITY_RARE = 2; // uint8 public constant RARITY_EPIC = 3; // uint8 public constant RARITY_LEGENDARY = 4; // uint8 public constant RARITY_MYTHIC = 5; struct SequenceRequest { uint256 batchId; address recipient; } struct Rarity { uint8 rarity; uint256 randomValue; bytes32 tokenSpecificRandomness; } // Market type enum (should match IBoosterTokenV2's enum) enum MarketType { BONDING_CURVE, UNISWAP_POOL } // Events event RandomnessRequested(address indexed requester, uint256 batchId, uint64 sequenceNumber); event RandomnessFulfilled(uint64 sequsenceNumber, bytes32 randomNumber); event BoosterDropsMinted(address indexed minter, uint256 amount, uint256 startTokenId, uint256 endTokenId); event BoosterDropTransfer(address indexed from, address indexed to, uint256 tokenId); event BoosterDropSold(address indexed burner, uint256 tokenId, uint8 rarity, uint256 offerAmount); event BoosterDropSoldBatch(address indexed burner, uint256[] tokenIds, uint8[] rarities, uint256 finalOfferAmount); event BoosterDropOpened(address indexed from, uint256[] tokenIds, uint256 batchId); event RarityAssigned(uint256 batchId, bytes32 randomNumber); event EntropyAddressUpdated(address newEntropyAddress); event EntropyProviderUpdated(address newProvider); // Initialize parameters struct struct InitializeParams { address owner; string nftName; string nftSymbol; address tokenAddress; string baseURI; uint256 tokensPerMint; uint256 commonOffer; uint256 rareOffer; uint256 epicOffer; uint256 legendaryOffer; uint256 mythicOffer; address entropyAddress; } /** * @notice Initializes the contract * @param params All initialization parameters */ function initialize(InitializeParams memory params) external; /** * @notice Mint multiple booster box LTCs (Liquid Trading Cards) with ETH * @param amount Number of LTCs (Liquid Trading Cards) to mint */ function mint(uint256 amount) external payable; /** * @notice Mint multiple booster box LTCs (Liquid Trading Cards) with ETH * @param amount Number of LTCs (Liquid Trading Cards) to mint * @param recipient Address to receive the LTCs (Liquid Trading Cards) * @param referrer Address of the referrer * @param originReferrer Address of the origin referrer */ function mint(uint256 amount, address recipient, address referrer, address originReferrer) external payable; /** * @notice Mint multiple booster box LTCs (Liquid Trading Cards) with tokens directly * @param amount Number of LTCs (Liquid Trading Cards) to mint */ function mintWithToken(uint256 amount) external payable; /** * @notice Sells LTC (Liquid Trading Card) to contract and claims token offers based on rarity * @param tokenId Token ID to sell */ function sellAndClaimOffer(uint256 tokenId) external; /** * @notice Get the token amount needed to mint a specific number of LTCs (Liquid Trading Cards) * @param amount Number of LTCs (Liquid Trading Cards) to mint * @return tokenAmount Total tokens required */ function getMintPrice(uint256 amount) external view returns (uint256); /** * @notice Get the token amount needed per LTC (Liquid Trading Card) mint * @return The token amount per mint */ function tokensPerMint() external view returns (uint256); /** * @notice Get the offer amount for a common rarity LTC (Liquid Trading Card) * @return The common offer amount */ function COMMON_OFFER() external view returns (uint256); /** * @notice Get the offer amount for a rare rarity LTC (Liquid Trading Card) * @return The rare offer amount */ function RARE_OFFER() external view returns (uint256); /** * @notice Get the offer amount for an epic rarity LTC (Liquid Trading Card) * @return The epic offer amount */ function EPIC_OFFER() external view returns (uint256); /** * @notice Get the offer amount for a legendary rarity LTC (Liquid Trading Card) * @return The legendary offer amount */ function LEGENDARY_OFFER() external view returns (uint256); /** * @notice Get the offer amount for a mythic rarity LTC (Liquid Trading Card) * @return The mythic offer amount */ function MYTHIC_OFFER() external view returns (uint256); /** * @notice Get the booster token contract address * @return The booster token address */ function boosterTokenAddress() external view returns (address); /** * @notice Get the entropy address */ function entropyAddress() external view returns (address); /** * @notice Get the entropy provider */ function entropyProvider() external view returns (address); /** * @notice Get the entropy fee */ function getEntropyFee() external view returns (uint256); /** * @notice Get rarity for a token using its batch * @param tokenId The token ID to get rarity for * @return rarityInfo A Rarity struct with the rarity level (1-5) and random value */ function getTokenRarity(uint256 tokenId) external view returns (Rarity memory rarityInfo); } ``` ## IBoosterTokenV2 The `IBoosterTokenV2` interface defines the collectible token contract that handles token trading, bonding curves, and Uniswap graduation for digital collectibles. * Canonical interface: [`interfaces/v2/IBoosterTokenV2.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/interfaces/v2/IBoosterTokenV2.sol) * Canonical implementation: [`v2/BoosterTokenV2.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/v2/BoosterTokenV2.sol) ```solidity theme={null} // SPDX-License-Identifier: BUSL-1.1 // Copyright (C) 2025 Beb, Inc. All Rights Reserved pragma solidity ^0.8.27; /** * @title IBoosterTokenV2 * @dev Interface for the BoosterTokenV2 contract with graduation mechanism */ interface IBoosterTokenV2 { // Enum for market type enum MarketType { BONDING_CURVE, UNISWAP_POOL } // Events event OfferMinted(address indexed recipient, uint256 amount); event LiquiditySetup(address indexed pool, uint256 ethAmount, uint256 tokenAmount); event PositionFeesCollected(uint256 indexed positionId, uint256 amount0, uint256 amount1); event TokensPurchased(address indexed buyer, uint256 amount, uint256 ethPaid); event TokensSold(address indexed seller, address indexed recipient, uint256 amount, uint256 ethReceived); event UniswapPositionConfigured(address positionManager, address swapRouter, uint256 positionId); event TokensSold(address indexed from, uint256 amount); event MarketGraduated(address indexed nftAddress, address indexed tokenAddress, address indexed pool, uint256 ethAmount, uint256 tokenAmount, uint256 positionId); event BoosterTokenFeesDispersed(uint256 ownerFee, uint256 protocolFee, address owner, address protocolFeeRecipient, uint256 referrerFee, uint256 originReferrerFee, address referrer, address originReferrer); event BoosterTokenTransfer(address indexed from, address indexed to, uint256 value, uint256 balanceOfFrom, uint256 balanceOfTo, uint256 totalSupply); /** * @notice Initialize the BoosterTokenV2 contract * @param owner The owner of the token contract * @param name The name of the token * @param symbol The symbol of the token * @param dropAddress The address of the LTC (Liquid Trading Card) drop contract * @param factoryAddress The address of the factory contract * @param uniswapV3Factory The address of the Uniswap V3 factory * @param uniswapV3PositionManager The address of the Uniswap V3 position manager * @param uniswapV3SwapRouter The address of the Uniswap V3 swap router * @param wethAddress The address of WETH * @param bondingCurveAddress The address of the bonding curve contract * @param protocolFeeRecipient The address of the protocol fee recipient */ function initialize( address owner, string memory name, string memory symbol, address dropAddress, address factoryAddress, address uniswapV3Factory, address uniswapV3PositionManager, address uniswapV3SwapRouter, address wethAddress, address bondingCurveAddress, address protocolFeeRecipient ) external; /** * @notice Get current market type (BONDING_CURVE or UNISWAP_POOL) * @return The current market type */ function marketType() external view returns (MarketType); /** * @notice Buy tokens with ETH * @param tokenAmount Amount of tokens to buy * @param recipient Address to receive the tokens */ function buy(uint256 tokenAmount, address recipient) external payable; /** * @notice Buy tokens with ETH * @param tokenAmount Amount of tokens to buy * @param recipient Address to receive the tokens * @param referrer The address of the referrer * @param originReferrer The address of the origin referrer */ function buy(uint256 tokenAmount, address recipient, address referrer, address originReferrer) external payable; /** * @notice Sell tokens for ETH * @param tokensToSell The number of tokens to sell * @param recipient The address to receive the ETH payout * @param minPayoutSize The minimum ETH payout to prevent slippage * @param referrer The address of the referrer * @param originReferrer The address of the origin referrer */ function sell( uint256 tokensToSell, address recipient, uint256 minPayoutSize, address referrer, address originReferrer ) external returns (uint256); /** * @notice Sell tokens for ETH (only available after graduation) * @param tokensToSell The number of tokens to sell * @param recipient The address to receive the ETH payout * @param minPayoutSize The minimum ETH payout to prevent slippage * @return Amount of ETH received */ function sell( uint256 tokensToSell, address recipient, uint256 minPayoutSize ) external returns (uint256); /** * @notice Sells tokens from the specified address to the contract * @param from The address to sell tokens from * @param amount The amount of tokens to sell */ function sellTokens(address from, uint256 amount) external; /** * @notice Mints tokens as offers for selling LTCs (Liquid Trading Cards) * @param recipient The address to receive the tokens * @param amount The amount of tokens to mint */ function mintOffer(address recipient, uint256 amount) external; /** * @notice Get quote for buying tokens with ETH using bonding curve * @param ethAmount Amount of ETH to spend * @return Token amount that can be purchased */ function getEthBuyQuote(uint256 ethAmount) external view returns (uint256); /** * @notice Get quote for buying tokens with a specified token amount * @param tokenAmount Amount of tokens to purchase * @return ETH amount needed */ function getTokenBuyQuote(uint256 tokenAmount) external view returns (uint256); /** * @notice Get quote for selling tokens for ETH using bonding curve * @param tokenAmount Amount of tokens to sell * @return ETH amount received */ function getTokenSellQuote(uint256 tokenAmount) external view returns (uint256); /** * @notice Get the address of the bonding curve contract * @return The bonding curve address */ function bondingCurve() external view returns (address); function poolAddress() external view returns (address); } ``` ## IBoosterCardSeedUtils With source available at [0x002aaaa42354bf8f09f9924977bf0c531933f999](https://basescan.org/address/0x002aaaa42354bf8f09f9924977bf0c531933f999#code), this interface provides a way to derive foil & wear from a `tokenSpecificRandomness`. * Canonical interface: [`interfaces/IBoosterCardSeedUtils.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/interfaces/IBoosterCardSeedUtils.sol) * Canonical implementation: [`BoosterCardSeedUtils.sol`](https://github.com/wieldlabs/contracts/blob/main/vibemarket/BoosterCardSeedUtils.sol) ```solidity theme={null} // SPDX-License-Identifier: BUSL-1.1 pragma solidity ^0.8.23; interface IBoosterCardSeedUtils { /** * @notice Generates a wear value from a seed * @param seed The seed value to generate wear from * @return wear A string representing the wear value with exactly 10 decimal places */ function wearFromSeed(bytes32 seed) external pure returns (string memory wear); /** * @notice Gets the foil mapping from a seed * @param seed The seed value to determine foil type * @return foilType The foil type: "Prize", "Standard", or "Normal" */ function getFoilMappingFromSeed(bytes32 seed) external pure returns (string memory foilType); /** * @notice Gets both wear and foil data from a seed * @param seed The seed value (bytes32(0) returns defaults) * @return wear The wear value string * @return foilType The foil type string */ function getCardSeedData(bytes32 seed) external pure returns (string memory wear, string memory foilType); } ```