---
name: vibemarket
version: 0.0.1
description: The onchain trading card marketplace. Browse packs, mint liquid trading cards and packs, reveal rarities, and trade NFT collections on Base.
homepage: https://vibe.market
metadata:
  {
    "openclaw":
      {
        "emoji": "🎴",
        "category": "nft",
        "api_base": "https://build.vibechain.com/vibe/boosterbox",
      },
  }
---

# vibe.market

The onchain trading card marketplace. Browse packs, view boosterboxes, check rarities, and discover NFT collections on Base.

## Skill Files

| File                        | URL                                |
| --------------------------- | ---------------------------------- |
| **SKILL.md** (this file)    | `https://vibechain.com/skill.md`   |
| **package.json** (metadata) | `https://vibechain.com/skill.json` |

**Install locally:**

```bash
mkdir -p ~/.openclaw/skills/vibemarket
curl -s https://vibechain.com/skill.md > ~/.openclaw/skills/vibemarket/SKILL.md
curl -s https://vibechain.com/skill.json > ~/.openclaw/skills/vibemarket/package.json
```

**Or just read them from the URLs above!**

**Base URL:** `https://build.vibechain.com/vibe/boosterbox`

**Check for updates:** Re-fetch these files anytime to see new features!

---

## Get Your API Key First

Every agent needs an API key to use the vibe.market API. Get one free at:
**https://docs.vibechain.com/api-reference/vibemarket-intro**

Or create one programmatically:

```bash
curl -X POST https://build.vibechain.com/apikey/create \
  -H "Content-Type: application/json" \
  -d '{"description": "YourAgentName - vibe.market bot", "email": "your@email.com"}'
```

Response:

```json
{
  "success": true,
  "apiKey": "your_api_key_here"
}
```

**Recommended:** Save your API key to `~/.config/vibemarket/credentials.json`:

```json
{
  "api_key": "your_api_key_here",
  "agent_name": "YourAgentName"
}
```

You can also save it to an environment variable named `VIBECHAIN_API_KEY`, or wherever you store configuration. The checked-in first-party key is a public quota identity, not an authorization secret.

---

## Authentication

All requests require your API key in the header:

```bash
curl https://build.vibechain.com/vibe/boosterbox/games \
  -H "API-KEY: YOUR_API_KEY"
```

---

## Browse Packs (Games)

### Get all packs

```bash
curl "https://build.vibechain.com/vibe/boosterbox/games?limit=20&page=1" \
  -H "API-KEY: YOUR_API_KEY"
```

Query parameters:

- `limit` - Results per page (default: 20, max: 100)
- `page` - Page number (default: 1)
- `chainId` - Filter by chain ID (default: 8453 for Base)
- `isActive` - Filter by active status (default: true)
- `includeGraduated` - Include graduated packs (default: true)
- `isFeatured` - Filter by featured status

**Response:**

```json
{
  "success": true,
  "games": [
    {
      "gameId": "unique-id",
      "tokenAddress": "0x...",
      "tokenName": "Pack Token",
      "tokenSymbol": "PACK",
      "nftName": "Pack NFT",
      "nftSymbol": "PACKNFT",
      "description": "A trading card pack",
      "imageUrl": "https://...",
      "isGraduated": false,
      "marketCap": "1000000000000000000",
      "marketCapUsd": "$3,245.67",
      "preorderProgress": 0.65,
      "pricePerPack": "10000000000000000",
      "pricePerPackUsd": "$32.45",
      "dropContractAddress": "0x...",
      "ownerAddress": "0x...",
      "slug": "my-pack",
      "packImage": "https://...",
      "isActive": true,
      "isFeatured": true,
      "isVerified": false,
      "version": "V2",
      "chainId": 8453,
      "createdAt": "2025-01-15T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

### Get featured packs

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

Sort options: `trending`, `marketCap`, `recent`

### Get packs by creator

```bash
curl "https://build.vibechain.com/vibe/boosterbox/games/creator/0xYOUR_ADDRESS" \
  -H "API-KEY: YOUR_API_KEY"
```

---

## Get Pack Info

### Get contract/pack details

```bash
curl "https://build.vibechain.com/vibe/boosterbox/contractAddress/CONTRACT_ADDRESS_OR_SLUG" \
  -H "API-KEY: YOUR_API_KEY"
```

You can use either the contract address or the pack slug.

### Contract Details Response

When you fetch a pack, you get these fields:

```json
{
  "success": true,
  "game": {
    "gameId": "unique-game-id",
    "tokenAddress": "0x...",
    "tokenName": "Pack Token",
    "tokenSymbol": "PACK",
    "nftName": "Pack NFT",
    "nftSymbol": "PACKNFT",
    "description": "A trading card pack",
    "imageUrl": "https://...",
    "websiteUrl": "https://...",
    "isGraduated": false,
    "marketCap": "1000000000000000000",
    "marketCapUsd": "$3,245.67",
    "pricePerPack": "10000000000000000",
    "pricePerPackUsd": "$32.45",
    "dropContractAddress": "0x...",
    "ownerAddress": "0x...",
    "slug": "my-pack",
    "bgColor": "#1a1a2e",
    "featuredImageUrl": "https://...",
    "packImage": "https://...",
    "isActive": true,
    "isVerified": false,
    "isVerifiedArtist": false,
    "disableFoil": false,
    "disableWear": false,
    "links": { "twitter": "...", "discord": "..." },
    "version": "V2"
  }
}
```

Key fields:

- `tokenAddress` - The ERC20 token contract for trading
- `dropContractAddress` - The NFT contract for booster packs (LTCs)
- `pricePerPack` / `pricePerPackUsd` - Cost to mint one pack
- `marketCap` / `marketCapUsd` - Total market cap of the token
- `isGraduated` - Whether the token has graduated to Uniswap

---

## Reading Contracts On-Chain

vibe.market uses two main smart contracts per pack:

### 1. IBoosterDropV2 (NFT Contract)

The `dropContractAddress` is the LTC (Liquid Trading Card) NFT contract. Key read functions:

```solidity
// Get price to mint packs
function getMintPrice(uint256 amount) external view returns (uint256);
function tokensPerMint() external view returns (uint256);

// Get rarity offers (tokens received when selling back)
function COMMON_OFFER() external view returns (uint256);
function RARE_OFFER() external view returns (uint256);
function EPIC_OFFER() external view returns (uint256);
function LEGENDARY_OFFER() external view returns (uint256);
function MYTHIC_OFFER() external view returns (uint256);

// Get token rarity (after opening)
function getTokenRarity(uint256 tokenId) external view returns (Rarity memory);

// Get associated token contract
function boosterTokenAddress() external view returns (address);
```

**Rarity Struct:**

```solidity
struct Rarity {
    uint8 rarity;           // 1=Common, 2=Rare, 3=Epic, 4=Legendary, 5=Mythic
    uint256 randomValue;
    bytes32 tokenSpecificRandomness;
}
```

### 2. IBoosterTokenV2 (ERC20 Token Contract)

The `tokenAddress` is the tradeable token contract. Key read functions:

```solidity
// Get market type
function marketType() external view returns (MarketType);
// Returns: BONDING_CURVE (0) or UNISWAP_POOL (1)

// Get buy/sell quotes
function getEthBuyQuote(uint256 ethAmount) external view returns (uint256);
function getTokenBuyQuote(uint256 tokenAmount) external view returns (uint256);
function getTokenSellQuote(uint256 tokenAmount) external view returns (uint256);

// Get Uniswap pool (after graduation)
function poolAddress() external view returns (address);

// Get bonding curve address
function bondingCurve() external view returns (address);
```

### 3. IBoosterCardSeedUtils (Utility Contract)

Deployed at `0x002aaaa42354bf8f09f9924977bf0c531933f999` on Base. Derives foil & wear from token randomness:

```solidity
// Get wear value (0-1 with 10 decimals)
function wearFromSeed(bytes32 seed) external pure returns (string memory);

// Get foil type: "Prize", "Standard", or "Normal"
function getFoilMappingFromSeed(bytes32 seed) external pure returns (string memory);

// Get both at once
function getCardSeedData(bytes32 seed) external pure returns (string memory wear, string memory foilType);
```

### Example: Reading Contract with ethers.js

```javascript
import { ethers } from "ethers";

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org");

// Get pack details from API first
const packResponse = await fetch(
  "https://build.vibechain.com/vibe/boosterbox/contractAddress/my-pack",
  { headers: { "API-KEY": "YOUR_API_KEY" } },
);
const pack = await packResponse.json();

// Read from drop contract (NFT)
const dropAbi = [
  "function getMintPrice(uint256 amount) view returns (uint256)",
  "function getTokenRarity(uint256 tokenId) view returns (tuple(uint8 rarity, uint256 randomValue, bytes32 tokenSpecificRandomness))",
  "function COMMON_OFFER() view returns (uint256)",
  "function LEGENDARY_OFFER() view returns (uint256)",
];
const dropContract = new ethers.Contract(
  pack.game.dropContractAddress,
  dropAbi,
  provider,
);

const mintPrice = await dropContract.getMintPrice(1);
console.log("Price to mint 1 pack:", ethers.formatEther(mintPrice), "tokens");

// Read from token contract (ERC20)
const tokenAbi = [
  "function marketType() view returns (uint8)",
  "function getEthBuyQuote(uint256 ethAmount) view returns (uint256)",
  "function getTokenSellQuote(uint256 tokenAmount) view returns (uint256)",
];
const tokenContract = new ethers.Contract(
  pack.game.tokenAddress,
  tokenAbi,
  provider,
);

const marketType = await tokenContract.marketType();
console.log(
  "Market type:",
  marketType === 0 ? "Bonding Curve" : "Uniswap Pool",
);

// Get foil/wear from card seed utils
const seedUtilsAbi = [
  "function getCardSeedData(bytes32 seed) view returns (string wear, string foilType)",
];
const seedUtils = new ethers.Contract(
  "0x002aaaa42354bf8f09f9924977bf0c531933f999",
  seedUtilsAbi,
  provider,
);

// If you have a token's randomness seed:
const { wear, foilType } = await seedUtils.getCardSeedData(tokenRandomness);
console.log("Card wear:", wear, "Foil:", foilType);
```

### Example: Reading Contract with cast (Foundry)

```bash
# Get mint price for 1 pack
cast call $DROP_CONTRACT "getMintPrice(uint256)" 1 --rpc-url https://mainnet.base.org

# Get legendary offer amount
cast call $DROP_CONTRACT "LEGENDARY_OFFER()" --rpc-url https://mainnet.base.org

# Get market type (0=bonding curve, 1=uniswap)
cast call $TOKEN_CONTRACT "marketType()" --rpc-url https://mainnet.base.org

# Get ETH buy quote (how many tokens for 0.1 ETH)
cast call $TOKEN_CONTRACT "getEthBuyQuote(uint256)" 100000000000000000 --rpc-url https://mainnet.base.org
```

---

## Writing to Contracts (Minting, Opening, Selling)

### Mint Booster Packs

Mint packs by sending ETH to the drop contract:

```solidity
// Mint with ETH (amount = number of packs)
function mint(uint256 amount) external payable;

// Mint with referrer tracking
function mint(uint256 amount, address recipient, address referrer, address originReferrer) external payable;

// Mint directly with tokens (if you already hold the pack token)
function mintWithToken(uint256 amount) external payable;
```

**Example with ethers.js:**

```javascript
import { ethers } from "ethers";

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Get pack info from API
const packRes = await fetch(
  "https://build.vibechain.com/vibe/boosterbox/contractAddress/my-pack",
  { headers: { "API-KEY": "YOUR_API_KEY" } },
);
const pack = await packRes.json();

// Connect to drop contract
const dropAbi = [
  "function mint(uint256 amount) payable",
  "function getMintPrice(uint256 amount) view returns (uint256)",
];
const dropContract = new ethers.Contract(
  pack.game.dropContractAddress,
  dropAbi,
  signer,
);

// Get price and mint 1 pack
const price = await dropContract.getMintPrice(1);
const tx = await dropContract.mint(1, { value: price });
await tx.wait();
console.log("Minted! Tx:", tx.hash);
```

**Example with cast:**

```bash
# First get the mint price
PRICE=$(cast call $DROP_CONTRACT "getMintPrice(uint256)" 1 --rpc-url https://mainnet.base.org)

# Mint 1 pack
cast send $DROP_CONTRACT "mint(uint256)" 1 --value $PRICE --rpc-url https://mainnet.base.org --private-key $PRIVATE_KEY
```

### Open Booster Packs (Reveal Rarity)

Opening a pack requests randomness to determine the card's rarity. The contract emits `BoosterDropOpened` when initiated and `RarityAssigned` when complete.

**Note:** Opening requires paying an entropy fee for Pyth VRF randomness.

```solidity
// Open packs (requires entropy fee)
function openPacks(uint256[] calldata tokenIds) external payable;

// Get entropy fee
function getEntropyFee() external view returns (uint256);
```

**Example with ethers.js:**

```javascript
const dropAbi = [
  "function openPacks(uint256[] calldata tokenIds) payable",
  "function getEntropyFee() view returns (uint256)",
];
const dropContract = new ethers.Contract(
  pack.game.dropContractAddress,
  dropAbi,
  signer,
);

// Get entropy fee and open packs
const entropyFee = await dropContract.getEntropyFee();
const tokenIds = [1, 2, 3]; // Your pack token IDs
const tx = await dropContract.openPacks(tokenIds, { value: entropyFee });
await tx.wait();

// Wait for RarityAssigned event (may take a few blocks for VRF callback)
```

### Sell Packs Back (Claim Offer)

After opening, you can sell your cards back to the contract for tokens based on rarity:

```solidity
// Sell single card
function sellAndClaimOffer(uint256 tokenId) external;

// Sell multiple cards at once
function sellAndClaimOfferBatch(uint256[] calldata tokenIds) external;
```

**Example with ethers.js:**

```javascript
const dropAbi = [
  "function sellAndClaimOffer(uint256 tokenId)",
  "function sellAndClaimOfferBatch(uint256[] calldata tokenIds)",
  "function LEGENDARY_OFFER() view returns (uint256)",
];
const dropContract = new ethers.Contract(
  pack.game.dropContractAddress,
  dropAbi,
  signer,
);

// Check legendary offer value
const legendaryOffer = await dropContract.LEGENDARY_OFFER();
console.log(
  "Legendary cards pay:",
  ethers.formatEther(legendaryOffer),
  "tokens",
);

// Sell a card back
const tx = await dropContract.sellAndClaimOffer(tokenId);
await tx.wait();
```

### Buy/Sell Tokens

Trade the pack's ERC20 token on the bonding curve or Uniswap:

```solidity
// Buy tokens with ETH
function buy(uint256 tokenAmount, address recipient) external payable;
function buy(uint256 tokenAmount, address recipient, address referrer, address originReferrer) external payable;

// Sell tokens for ETH
function sell(uint256 tokensToSell, address recipient, uint256 minPayoutSize) external returns (uint256);
function sell(uint256 tokensToSell, address recipient, uint256 minPayoutSize, address referrer, address originReferrer) external returns (uint256);
```

**Example with ethers.js:**

```javascript
const tokenAbi = [
  "function buy(uint256 tokenAmount, address recipient) payable",
  "function sell(uint256 tokensToSell, address recipient, uint256 minPayoutSize) returns (uint256)",
  "function getEthBuyQuote(uint256 ethAmount) view returns (uint256)",
  "function getTokenSellQuote(uint256 tokenAmount) view returns (uint256)",
];
const tokenContract = new ethers.Contract(
  pack.game.tokenAddress,
  tokenAbi,
  signer,
);

// Buy tokens with 0.01 ETH
const ethAmount = ethers.parseEther("0.01");
const expectedTokens = await tokenContract.getEthBuyQuote(ethAmount);
const buyTx = await tokenContract.buy(expectedTokens, signer.address, {
  value: ethAmount,
});
await buyTx.wait();

// Sell 1000 tokens (with 1% slippage protection)
const tokensToSell = ethers.parseEther("1000");
const expectedEth = await tokenContract.getTokenSellQuote(tokensToSell);
const minPayout = (expectedEth * 99n) / 100n; // 1% slippage
const sellTx = await tokenContract.sell(
  tokensToSell,
  signer.address,
  minPayout,
);
await sellTx.wait();
```

### Full Workflow Example

Here's a complete workflow to mint, open, check rarity, and optionally sell:

```javascript
import { ethers } from "ethers";

async function mintAndRevealPack(packSlug, apiKey) {
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();

  // 1. Get pack details from API
  const res = await fetch(
    `https://build.vibechain.com/vibe/boosterbox/contractAddress/${packSlug}`,
    { headers: { "API-KEY": apiKey } },
  );
  const { game } = await res.json();

  // 2. Connect to contracts
  const dropContract = new ethers.Contract(
    game.dropContractAddress,
    [
      "function mint(uint256) payable",
      "function getMintPrice(uint256) view returns (uint256)",
      "function openPacks(uint256[]) payable",
      "function getEntropyFee() view returns (uint256)",
      "function getTokenRarity(uint256) view returns (tuple(uint8,uint256,bytes32))",
      "function sellAndClaimOffer(uint256)",
      "event BoosterDropsMinted(address indexed, uint256, uint256 startTokenId, uint256 endTokenId)",
    ],
    signer,
  );

  // 3. Mint 1 pack
  const mintPrice = await dropContract.getMintPrice(1);
  const mintTx = await dropContract.mint(1, { value: mintPrice });
  const mintReceipt = await mintTx.wait();

  // Get minted token ID from event
  const mintEvent = mintReceipt.logs.find((log) => {
    try {
      return (
        dropContract.interface.parseLog(log)?.name === "BoosterDropsMinted"
      );
    } catch {
      return false;
    }
  });
  const parsed = dropContract.interface.parseLog(mintEvent);
  const tokenId = parsed.args.startTokenId;
  console.log("Minted token ID:", tokenId);

  // 4. Open the pack
  const entropyFee = await dropContract.getEntropyFee();
  const openTx = await dropContract.openPacks([tokenId], { value: entropyFee });
  await openTx.wait();
  console.log("Pack opened! Waiting for rarity...");

  // 5. Wait and check rarity (poll or listen for RarityAssigned event)
  await new Promise((r) => setTimeout(r, 30000)); // Wait 30s for VRF
  const rarity = await dropContract.getTokenRarity(tokenId);
  const rarityNames = ["", "Common", "Rare", "Epic", "Legendary", "Mythic"];
  console.log("Card rarity:", rarityNames[rarity[0]]);

  // 6. Optionally sell back
  if (rarity[0] >= 4) {
    // Legendary or Mythic
    console.log("Keeping this rare card!");
  } else {
    const sellTx = await dropContract.sellAndClaimOffer(tokenId);
    await sellTx.wait();
    console.log("Sold card for tokens!");
  }
}
```

---

## BoosterBoxes (NFTs)

### Get a single boosterbox

```bash
curl "https://build.vibechain.com/vibe/boosterbox/?tokenId=1&contractAddress=0xCONTRACT_ADDRESS" \
  -H "API-KEY: YOUR_API_KEY"
```

Query parameters:

- `tokenId` - The token ID (required)
- `contractAddress` - The contract address (required)
- `chainId` - Chain ID (default: 8453)
- `includeMetadata` - Include token metadata (default: false)
- `includeContractDetails` - Include contract details (default: false)

**Response:**

```json
{
  "success": true,
  "boosterBox": {
    "tokenId": 123,
    "contractAddress": "0x...",
    "chainId": 8453,
    "owner": "0x...",
    "status": "rarity_assigned",
    "rarity": 3,
    "randomValue": "123456789...",
    "tokenSpecificRandomness": "0xabc123...",
    "mintedAt": "2025-01-28T12:00:00Z",
    "openedAt": "2025-01-28T12:05:00Z",
    "latestUpdateTimestamp": "2025-01-28T12:05:00Z",
    "metadata": {
      "name": "Rare Dragon Card",
      "description": "A powerful dragon card",
      "image": "https://...",
      "external_url": "https://vibe.market/...",
      "attributes": [
        { "trait_type": "Rarity", "value": "Super Rare" },
        { "trait_type": "Foil", "value": "Standard" },
        { "trait_type": "Wear", "value": "0.1234567890" }
      ]
    }
  }
}
```

**BoosterBox Status Values:**

- `minted` - Pack is minted but not yet opened
- `rarity_assigned` - Pack has been opened and rarity revealed
- `burned` - Pack has been sold back to contract

### Get boosterboxes by range

```bash
curl "https://build.vibechain.com/vibe/boosterbox/range?contractAddress=0xCONTRACT&startTokenId=1&endTokenId=100" \
  -H "API-KEY: YOUR_API_KEY"
```

Query parameters:

- `contractAddress` - The contract address (required)
- `tokenIds` - Comma-separated list of token IDs
- `startTokenId` - Start of token ID range
- `endTokenId` - End of token ID range
- `status` - Filter by status: `minted`, `rarity_assigned`, `burned`
- `rarity` - Filter by rarity (0-4)
- `page`, `limit` - Pagination
- `sortBy`, `sortOrder` - Sorting (default: `latestUpdateTimestamp`, `desc`)
- `includeMetadata` - Include card metadata (default: false)
- `includeContractDetails` - Include pack details (default: false)

**Response:**

```json
{
  "success": true,
  "boosterBoxes": [
    {
      "tokenId": 1,
      "contractAddress": "0x...",
      "owner": "0x...",
      "status": "rarity_assigned",
      "rarity": 0,
      "mintedAt": "2025-01-28T12:00:00Z",
      "openedAt": "2025-01-28T12:05:00Z"
    },
    {
      "tokenId": 2,
      "contractAddress": "0x...",
      "owner": "0x...",
      "status": "minted",
      "rarity": null,
      "mintedAt": "2025-01-28T12:10:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "totalPages": 2
  }
}
```

### Get boosterboxes by owner

```bash
curl "https://build.vibechain.com/vibe/boosterbox/owner/0xOWNER_ADDRESS" \
  -H "API-KEY: YOUR_API_KEY"
```

Query parameters:

- `contractAddress` - Filter by contract
- `chainId` - Filter by chain
- `status` - Filter by status
- `rarity` - Filter by rarity (0-4)
- `gameId` - Filter by game ID
- `groupBy` - Group results by `contract`
- `groupCommonRarity` - Group rarity=0 items by contract
- `includeMetadata` - Include metadata
- `includeContractDetails` - Include contract details

### Get recent boosterboxes

```bash
curl "https://build.vibechain.com/vibe/boosterbox/recent?limit=20" \
  -H "API-KEY: YOUR_API_KEY"
```

Query parameters:

- `limit` - Number of results (default: 20, max: 100)
- `cursor` - Pagination cursor
- `contractAddress` - Filter by contract
- `status` - Filter by status
- `rarityGreaterThan` - Minimum rarity filter
- `includeMetadata` - Include metadata (default: true)

---

## Metadata & Odds

### Get all metadata for a contract

```bash
curl "https://build.vibechain.com/vibe/boosterbox/metadata?contractAddress=0xCONTRACT" \
  -H "API-KEY: YOUR_API_KEY"
```

### Get metadata for a specific token

```bash
curl "https://build.vibechain.com/vibe/boosterbox/metadata/SLUG/TOKEN_ID" \
  -H "API-KEY: YOUR_API_KEY"
```

### Get all metadata with odds

```bash
curl "https://build.vibechain.com/vibe/boosterbox/contractAddress/CONTRACT_OR_SLUG/all-metadata" \
  -H "API-KEY: YOUR_API_KEY"
```

**Response:**

```json
{
  "success": true,
  "metadata": [
    {
      "name": "Common Card",
      "description": "A basic card",
      "imageUrl": "https://...",
      "rarity": 0,
      "startId": 1,
      "endId": 1000,
      "odds": 0.80,
      "oddsFormatted": "80%"
    },
    {
      "name": "Legendary Card",
      "description": "An extremely rare card",
      "imageUrl": "https://...",
      "rarity": 4,
      "startId": 1001,
      "endId": 1010,
      "odds": 0.01,
      "oddsFormatted": "1%"
    }
  ],
  "totalTokens": 1010,
  "contractDetails": { ... }
}
```

---

## Rarity

### Get token rarity by transaction

```bash
curl "https://build.vibechain.com/vibe/boosterbox/rarity?transactionHash=0xTX_HASH&contractAddress=0xCONTRACT" \
  -H "API-KEY: YOUR_API_KEY"
```

**Response:**

```json
{
  "success": true,
  "rarity": 3,
  "rarityName": "Super Rare",
  "tokenId": 123,
  "randomValue": "123456789...",
  "tokenSpecificRandomness": "0xabc123..."
}
```

### Rarity Levels

| Level | Name       |
| ----- | ---------- |
| 0     | Common     |
| 1     | Uncommon   |
| 2     | Rare       |
| 3     | Super Rare |
| 4     | Legendary  |

---

## ETH Price

### Get current ETH price

```bash
curl "https://build.vibechain.com/vibe/boosterbox/eth-price" \
  -H "API-KEY: YOUR_API_KEY"
```

Response:

```json
{
  "success": true,
  "price": 3245.67,
  "priceFormatted": "$3,245.67",
  "lastUpdated": "2025-01-28T12:00:00Z"
}
```

---

## Response Format

Success:

```json
{
  "success": true,
  "data": {...}
}
```

Error:

```json
{
  "success": false,
  "message": "Error description"
}
```

---

## Pagination

List endpoints support pagination:

- `page` - Page number (default: 1)
- `limit` - Results per page (varies by endpoint)
- Some endpoints use `cursor` for cursor-based pagination

Response includes:

```json
{
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "totalPages": 3
  }
}
```

---

## Default Chain

The default chain is **Base** (chainId: 8453). Include `chainId` parameter to query other chains.

---

## Everything You Can Do

| Action                | What it does                            |
| --------------------- | --------------------------------------- |
| **Browse packs**      | Discover available trading card packs   |
| **View featured**     | See trending and popular packs          |
| **Check ownership**   | See what boosterboxes an address owns   |
| **View metadata**     | See card artwork, names, and attributes |
| **Check odds**        | View drop rates for different rarities  |
| **Track rarities**    | See which cards are Common to Legendary |
| **Get prices**        | Check current ETH price in USD          |
| **Filter by rarity**  | Find specific rarity cards              |
| **Search by creator** | Find packs made by a specific creator   |
| **Mint packs**        | Buy new booster packs with ETH          |
| **Open packs**        | Reveal your card's rarity with VRF      |
| **Sell cards**        | Sell cards back to contract for tokens  |
| **Buy tokens**        | Purchase pack tokens on bonding curve   |
| **Sell tokens**       | Sell tokens for ETH                     |
| **Read contracts**    | Query on-chain data directly            |

---

## Your Human Can Ask Anytime

Your human can prompt you to do anything on vibe.market:

- "Check what packs are trending on vibe.market"
- "Show me my boosterboxes"
- "What are the odds for this pack?"
- "Find legendary cards in this collection"
- "How much is ETH right now?"
- "Show me packs created by this address"
- "Mint 3 packs from [pack-name]"
- "Open my unopened packs"
- "What's the legendary offer for this pack?"
- "Sell my common cards back"
- "Buy $50 worth of this pack's token"
- "What's the current token price on the bonding curve?"

---

## Support

For API support or to report issues, contact the vibe.market team at [gm@vibechain.com](mailto:gm@vibechain.com).