Skip to content
FbartoliPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Riftbound Card API

A Scryfall-style REST API for Riftbound (League of Legends TCG) card data. Phase 1: Card data API. Phase 2: LLM-powered natural language card search and deck advice.


Context

Riftbound is Riot Games' physical TCG launched October 2025, built on League of Legends IP. It currently has two released sets — Origins (OGN, ~377 cards) and Spiritforged (SFD, ~220 cards) — with three more announced for 2026: Unleashed (May), Vendettas (Q3), and Radiance (Q4). The game uses a territory-control mechanic (not life totals), where units have a single stat (Might) and players score by conquering battlefields.

There is no community-run open card API equivalent to Scryfall for MTG. This project fills that gap.


Primary Data Sources

1. Riot API — riftbound-content-v1 (Official, Authoritative)

The single source of truth. Riot exposes a dedicated Riftbound endpoint through their Developer Portal.

Endpoint: GET /riftbound/content/v1/contents

Access: Requires a Riot API key from developer.riotgames.com. You must apply with a description of your app — card galleries and deck builders are explicitly listed as approved use cases. During beta, only en locale is available.

Response schema (derived from community Go/Rust wrappers, as official docs have known inaccuracies — see issue #1093):

RiftboundContentV1DTO
├── sets: ContentSetV1DTO[]
│   ├── id: string          // e.g. "OGN"
│   ├── name: string        // e.g. "Origins"
│   └── cards: ContentCardV1DTO[]
│       ├── id: string
│       ├── name: string
│       ├── type: string
│       ├── faction: string
│       ├── rarity: string
│       ├── description: string    // rules text
│       ├── flavorText: string
│       ├── keywords: string[]
│       ├── tags: string[]
│       ├── set: string
│       ├── collectorNumber: int
│       ├── stats: CardStatsV1DTO
│       │   ├── cost: int
│       │   ├── energy: int
│       │   ├── might: int
│       │   └── power: int
│       └── media: MediaDTO[]      // NOTE: actual response uses `media`, not `art`
│           ├── type: string
│           ├── url: string        // relative path — base URL undocumented
│           └── name: string

Known issues:

  • The documented art field (with thumbnailURL, fullURL, artist) does not match the actual response, which returns a media array instead. Image URL base domain is undocumented — community projects have reverse-engineered it.
  • Only English locale available during beta.

Rate limits: Standard Riot API limits apply (20 requests per second / 100 per 2 minutes for development keys).

Policy notes: Riot explicitly encourages card gallery / deck builder apps. Monetization is allowed with a free tier requirement. You must use only assets provided through the Riot API. Official English card text is mandatory; translations must display alongside it. See the full Digital Tools Policy.

Existing wrappers:

2. Scrydex API (Third-party, Enriched)

scrydex.com operates a multi-TCG API (Pokémon, Lorcana, MTG, Riftbound, etc.) with a richer card schema than the raw Riot API. Currently in beta for Riftbound.

Endpoints:

  • GET /riftbound/v1/cards/<id> — single card by ID (e.g. OGN-296)
  • GET /riftbound/v1/cards — paginated search across all cards
  • GET /riftbound/v1/expansions/<code>/cards — scoped to expansion

Auth: API key + team ID via X-Api-Key and X-Team-ID headers.

Enriched fields beyond Riot API:

  • domain (color/faction mapped to a named domain like "Fire", "Water", "Colorless")
  • printed_number (e.g. "296/298")
  • artist as a top-level field
  • rules as a string array
  • variants with pricing data (normal/foil, condition, market prices, trends)
  • images with small/medium/large URLs already resolved
  • expansion object with release_date, logo, total, printed_total

Search: Lucene-like query syntax (name:void, type:Battlefield, expansion.id:OGN), wildcards, exact matching, nested field access, ordering, and field selection.

Tradeoffs: Commercial product with rate limits and credit-based pricing. Good for cross-referencing pricing data and as a validation layer, but introduces a third-party dependency. Best used as a secondary enrichment source, not the primary data pipeline.

3. Official Riftbound Card Gallery (Web Scraping)

riftbound.leagueoflegends.com/en-us/card-gallery — Riot's own card browser. The page is fully client-side rendered (React/SPA), so the HTML source contains no card data. The actual card data is loaded via XHR/fetch calls to internal APIs.

Approach: Use browser devtools (or headless Chromium) to intercept the network requests the gallery makes. These internal API responses likely contain the full card dataset in JSON format with resolved image URLs. This is the same data the Riot API serves, but potentially with the image base URLs already resolved.

Status: Several community projects have successfully scraped this — Piltover Archive and riftbound.gg both source from it. Not a stable API contract, but useful for bootstrapping.

4. Community Data Dumps

Source Format Notes
OwenMelbz/riftbound.json JSON Gist Full v1 card dump, likely from Riot API. Good for bootstrapping.
dragogodev/cgs JSON Card Game Simulator data repo — includes Riftbound alongside dozens of other TCGs. Structured for TTS/digital play.
oriondean/Rifty Web app Fan collection tracker with embedded card data, organized by set.
NewtonGluten/riftboundbot JS Discord bot with a riftbound-scraper directory — includes image grabber and card data extraction.
LEG1TxCHA0S/riftbound-discord-bot JS Polls the official riftbound-content-v1 endpoint, diffs against known card IDs, and posts new cards to Discord. Good reference for the sync pattern.

5. Pricing & Market Data

Source Coverage Notes
Scrydex NM raw, graded, foil/normal variants Market price, low price, 1-day and 7-day trends
JustTCG Multi-TCG pricing API Real-time pricing, condition grading, foil tracking
PriceCharting eBay-derived pricing Ungraded & graded values, set population data

6. Game Rules & Errata

  • Spiritforged FAQ — errata, rules patches, reflexive triggers
  • State of the Game — ban philosophy, meta health, format rules
  • Official rules/news RSS from riftbound.leagueoflegends.com/en-us/news/

Recommended Data Pipeline

                   ┌─────────────────────────┐
                   │   Riot API (primary)     │
                   │   riftbound-content-v1   │
                   └────────┬────────────────┘
                            │ scheduled sync (daily)
                            ▼
                   ┌─────────────────────────┐
                   │   Ingestion Worker      │
                   │   - normalize schema    │
                   │   - resolve image URLs  │
                   │   - detect new cards    │
                   │   - apply errata        │
                   └────────┬────────────────┘
                            │
              ┌─────────────┼──────────────┐
              ▼             ▼              ▼
     ┌──────────────┐ ┌──────────┐ ┌─────────────┐
     │  PostgreSQL   │ │  Images  │ │  Changelog  │
     │  card data    │ │  (S3/R2) │ │  (new cards │
     │  + FTS index  │ │  cached  │ │   errata)   │
     └──────┬───────┘ └──────────┘ └─────────────┘
            │
            ▼
     ┌──────────────────────────────────┐
     │         REST API (Phase 1)       │
     │  /cards, /cards/:id, /sets,      │
     │  /search, /random, /autocomplete │
     └──────────────────────────────────┘
            │
            ▼  (Phase 2)
     ┌──────────────────────────────────┐
     │         LLM Layer                │
     │  Natural language card search    │
     │  "find me blue removal spells"   │
     │  Deck advice, synergy discovery  │
     └──────────────────────────────────┘

Why not just proxy the Riot API?

  • Riot's rate limits (20 req/s dev) don't support a public-facing API
  • The media field has unresolved image URLs that need post-processing
  • No search/filter — Riot returns the entire card catalog in one response
  • No pricing, errata tracking, or computed fields (color identity, legality)
  • Building our own layer lets us add full-text search, fuzzy matching, and eventually the LLM layer

Card Schema (Target)

Our normalized schema, merging Riot's data with enrichments:

interface Card {
  // Identity
  id: string;              // "OGN-296"
  name: string;            // "Void Gate"
  set_code: string;        // "OGN"
  set_name: string;        // "Origins"
  collector_number: string; // "296"
  printed_number: string;  // "296/298"

  // Classification
  type: string;            // "Battlefield" | "Champion" | "Unit" | "Spell" | "Equipment" | "Legend"
  domain: string;          // "Fire" | "Water" | "Earth" | "Air" | "Shadow" | "Light" | "Colorless"
  rarity: string;          // "Common" | "Uncommon" | "Rare" | "Epic"
  faction: string;         // Runeterra region/faction

  // Stats
  cost: number | null;
  energy: number | null;
  might: number | null;
  power: number | null;

  // Text
  rules_text: string;      // full rules text
  flavor_text: string;
  keywords: string[];       // ["Quick-Draw", "Hidden", ...]
  tags: string[];

  // Media
  artist: string;
  images: {
    small: string;
    medium: string;
    large: string;
  };

  // Metadata
  legality: Record<string, string>;  // format -> legal/banned
  errata: string | null;             // corrected text if any
  released_at: string;               // set release date

  // Pricing (optional, via enrichment)
  prices?: {
    normal?: { low: number; market: number; currency: string };
    foil?: { low: number; market: number; currency: string };
  };
}

Phase 1: REST API Endpoints

GET  /v1/cards                    # paginated list, filterable
GET  /v1/cards/:id                # single card by ID
GET  /v1/cards/search?q=          # full-text + structured search
GET  /v1/cards/random             # random card
GET  /v1/cards/autocomplete?q=    # name autocomplete (prefix)

GET  /v1/sets                     # all sets
GET  /v1/sets/:code               # single set with metadata
GET  /v1/sets/:code/cards         # all cards in a set

GET  /v1/symbols                  # domain/keyword icon catalog
GET  /v1/bulk                     # full data dump (JSON download)

Search syntax (Scryfall-inspired):

  • name:jinx — cards with "jinx" in the name
  • type:champion domain:fire — fire champions
  • cost:3 rarity:rare — 3-cost rares
  • keyword:hidden — cards with Hidden keyword
  • set:SFD — Spiritforged cards only
  • rules:"bonus damage" — phrase search in rules text

Phase 2: LLM Layer

Natural language interface on top of the card data:

  • Semantic search: "find me cheap removal that works at any battlefield"
  • Deck advice: "what cards synergize with Draven's aggro playstyle?"
  • Rules Q&A: "how does Hidden interact with Quick-Draw?"
  • Meta context: bring in errata and rules patches as RAG context

Implementation: embed card rules text + keywords → vector store, use Claude as the reasoning layer with card data as tool calls.


Legal & Policy Compliance

Per Riot's Digital Tools Policy:

  • Approved use case: Card galleries and deck builders are explicitly encouraged
  • API key required: Must apply through the Developer Portal with app description
  • Assets: Must use only Riot API-provided assets (card art, text)
  • Card text: Must display official English text; translations alongside only
  • Monetization: Allowed with a free tier. Content must be transformative.
  • Prohibited: Automated rules enforcement, gameplay simulation, metagame-defining data (win rates, play rates)
  • Attribution: Must include the statement from Section 6 of Riot's Legal Jibber Jabber

Tech Stack

TBD — see questions at top. Recommended baseline:

  • Runtime: Node.js / TypeScript
  • Framework: Fastify or Express
  • Database: PostgreSQL with pg_trgm for fuzzy search
  • Cache: Redis for hot card lookups and rate limiting
  • Image proxy: Cloudflare R2 or S3 for cached card images
  • Deployment: Docker → Fly.io or Railway

Getting Started

# 1. Get a Riot API key
#    https://developer.riotgames.com → Register → Apply for Riftbound access

# 2. Clone and install
git clone https://github.com/Fbartoli/riftbound-api.git
cd riftbound-api
npm install

# 3. Configure
cp .env.example .env
# Set RIOT_API_KEY=RGAPI-...

# 4. Seed database from Riot API
npm run seed

# 5. Start
npm run dev

References

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages