Card & Order Book Data Models

Card Data Model

Each Pokémon card in the system is represented with detailed metadata to provide trading transparency and collector-friendly information.

Example Structure:

{
  "card_id": "charizard_1st_ed",
  "name": "Charizard",
  "set": "Base Set",
  "rarity": "Holo",
  "condition": "Near Mint",
  "image_url": "https://example.com/images/charizard.png",
  "price_usd": 100,
  "price_sol": 2.0,
  "history": [
    {"date": "2025-11-01", "price_usd": 95},
    {"date": "2025-11-02", "price_usd": 98},
    {"date": "2025-11-03", "price_usd": 100}
  ]
}

Field Descriptions:

• card_id – Unique identifier for the card.

• name – Name of the Pokémon card.

• set – Expansion set or edition.

• rarity – Card rarity (e.g., Holo, Rare, Ultra Rare).

• condition – Card condition (e.g., Near Mint, Lightly Played).

• image_url – URL of the card image for frontend display.

• price_usd – Current card price in USD or EUR.

• price_sol – Price converted into SOL using live exchange rate.

• history – List of historical prices for charting and analysis.

---

Order Book Data Model

The order book tracks all active bids and asks for each card. It is used to match buyers and sellers in real time.

Example Structure:

{
  "card_id": "charizard_1st_ed",
  "asks": [
    {"user": "0xABC", "price_sol": 2.1, "amount": 1},
    {"user": "0xDEF", "price_sol": 2.2, "amount": 1}
  ],
  "bids": [
    {"user": "0xXYZ", "price_sol": 1.9, "amount": 1},
    {"user": "0x123", "price_sol": 2.0, "amount": 1}
  ]
}

Field Descriptions:

• asks – List of active sell orders; price = SOL per card, amount = number of cards.

• bids – List of active buy orders; price = SOL per card, amount = number of cards.

• Matching Rules – Orders are matched by price-time priority: lowest ask meets highest bid.

---

Price Conversion to SOL

To enable on-chain trading, all card prices are converted from fiat (USD/EUR) to SOL:

price_in_sol = price_usd / sol_price_usd

Implementation Notes:

• sol_price_usd is retrieved from a reliable on-chain or off-chain oracle, e.g., CoinGecko API.

• Conversion occurs in real-time to reflect market fluctuations.

• Stored price_sol is used for frontend display, order book matching, and SOL transactions.

---

This data model ensures that:

• Users can view accurate prices in SOL.

• Order book functionality is consistent and transparent.

• Historical and real-time data can be visualized through charts and dashboards.