# The Undesirables Oracle Terminal — Full Documentation

> x402-enabled TCG and prediction market intelligence API. Pay per request in USDC on Base. No API keys, no accounts. 14 paid endpoints, 10+ free endpoints, 442K+ card database. Settlement only occurs on a successful response — failed calls are never charged.

Base URL: https://oracle.the-undesirables.com
Payment: USDC on Base (eip155:8453) via Coinbase CDP Facilitator
Merchant: 0x642e8a7C289381f24f0395e0539f0bA41c74Cc1B

---

## How to Call (x402 Protocol)

All paid endpoints are gated by the x402 payment protocol. Here is the full flow:

1. **Initial Request** — Send a standard GET to any paid endpoint
2. **402 Response** — Server returns HTTP 402 with a `Payment-Required` header containing base64-encoded JSON
3. **Decode** — The decoded JSON contains: amount (in USDC atomic units), payTo (merchant address), network (eip155:8453 for Base), and x402Version
4. **Sign** — Create a USDC transfer for the exact amount on Base mainnet, sign it with your wallet
5. **Retry** — Resend the original request with a `Payment-Signature` header containing your signed payment
6. **Response** — Server verifies payment on-chain via the Coinbase CDP Facilitator, settles USDC, and returns the JSON response

### Quick Start with Agentic Wallet

```bash
npx skills add coinbase/agentic-wallet-skills
```

### Discover All Endpoints

```bash
curl https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant?payTo=0x642e8a7C289381f24f0395e0539f0bA41c74Cc1B
```

---

## Free Endpoints

### GET /api/v1/search — Card Search

Search 442K+ TCG products across all supported games.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| query | string | Yes | — | Card name to search for |
| game | string | No | all | Filter by game (Pokemon, Magic, YuGiOh, One Piece Card Game, etc.) |
| limit | integer | No | 10 | Max results (1-50) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/search?query=charizard&game=Pokemon&limit=5"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "search_tcg_products",
  "data": {
    "results": [
      {
        "product_id": 509429,
        "name": "Charizard ex - 223/197",
        "rarity": "Special Illustration Rare",
        "market_price": 89.99,
        "low_price": 75.50,
        "mid_price": 85.00,
        "high_price": 110.00,
        "price_date": "2026-04-19"
      }
    ],
    "total": 5
  }
}
```

---

### GET /api/v1/market — Market Dashboard

Daily price snapshots for top cards by game.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| game | string | Yes | — | Game name (Pokemon, Magic, YuGiOh, Lorcana, One Piece Card Game, etc.) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/market?game=Pokemon"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "market_snapshot",
  "data": {
    "game": "Pokemon",
    "snapshot_date": "2026-04-19",
    "top_cards": [
      {
        "product_id": 509429,
        "name": "Charizard ex - 223/197",
        "rarity": "Special Illustration Rare",
        "market_price": 89.99,
        "low_price": 75.50,
        "mid_price": 85.00,
        "high_price": 110.00
      }
    ],
    "total": 25
  }
}
```

---

## Paid Endpoints — TCG Intelligence

### GET /api/v1/grade — AI Vision Card Grading ($0.10 USDC)

Analyzes card images using AI vision to predict centering, corners, edges, and surface scores. Returns PSA and Beckett grade estimates.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| image_url | string | Yes | — | URL to the card image to analyze |
| game | string | No | Pokemon | Game context for grading (Pokemon, Magic, YuGiOh) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/grade?image_url=https://example.com/card.jpg&game=Pokemon"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "grade_card",
  "price": "$0.10",
  "data": {
    "image_url": "https://example.com/card.jpg",
    "game": "Pokemon",
    "grading": {
      "centering": 9.2,
      "corners": 8.8,
      "edges": 9.0,
      "surface": 9.5,
      "overall_grade": 9.1,
      "psa_estimate": 9,
      "beckett_estimate": 9.1
    }
  }
}
```

---

### GET /api/v1/simulate — Risk Forecast ($0.015 USDC)

Returns a calibrated price-risk forecast from real market data. The **default** model is **regime-aware split-conformal** — distribution-free bands calibrated on real cross-card history, so the published downside (VaR) is honest (out-of-sample a "5% loss" happens about 5% of the time) and fully **deterministic**: anyone can reproduce the exact numbers. Each card also returns two letter grades — **Safe-Hold** (downside protection) and **Momentum** (direction).

**Monte Carlo models (opt-in via `model=gbm|merton`) are provably fair:** each run is seeded from the public **drand** randomness beacon (League of Entropy). Because the seed is committed publicly each round, the random draws cannot be cherry-picked. The response includes a `verifiability` block — the drand round, the randomness, a re-fetch URL, and full-precision parameters — so any third party can independently reproduce the forecast. If drand is ever unreachable the run falls back to local entropy and flags `provably_fair: false`.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| card_name | string | Yes | — | Card name to simulate |
| current_price | float | Yes | — | Current market price in USD |
| model | string | No | conformal | Forecast model: conformal (default), gbm, or merton |
| days | integer | No | 30 | Forecast horizon (1-365) |
| simulations | integer | No | 10000 | Number of Monte Carlo paths (100-100000) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/simulate?card_name=Charizard%20ex&current_price=89.99&model=merton&days=90&simulations=10000"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "monte_carlo",
  "price": "$0.015",
  "data": {
    "card_name": "Charizard ex",
    "model": "merton",
    "days": 90,
    "simulations": 10000,
    "percentiles": {
      "5th": 62.40,
      "25th": 78.15,
      "50th": 91.30,
      "75th": 108.20,
      "95th": 145.67
    }
  }
}
```

---

### GET /api/v1/crypto-oracle — NFT/Crypto Monte Carlo ($0.05 USDC)

Fetches real-time NFT floor prices via Alchemy API and passes pricing data into the Merton jump-diffusion Monte Carlo engine for volatility-aware projections.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| contract_address | string | Yes | — | ERC-721 or ERC-1155 contract address |
| network | string | No | eth-mainnet | Blockchain network (eth-mainnet, base-mainnet, etc.) |
| days | integer | No | 90 | Forecast horizon (1-365) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/crypto-oracle?contract_address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&network=eth-mainnet&days=30"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "crypto_oracle",
  "price": "$0.05",
  "data": {
    "contract": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
    "network": "eth-mainnet",
    "current_floor": 12.5,
    "currency": "ETH",
    "forecast": {
      "model": "merton",
      "days": 30,
      "percentiles": {
        "5th": 9.80,
        "25th": 11.20,
        "50th": 12.60,
        "75th": 14.30,
        "95th": 18.10
      }
    }
  }
}
```

---

### GET /api/v1/coin-history — CoinGecko Historical + Forecast ($0.05 USDC)

Fetches historical price data from CoinGecko and generates stochastic forecast projections.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| coin_id | string | Yes | — | CoinGecko coin identifier (e.g. "ethereum", "bitcoin", "solana") |
| days | integer | No | 30 | Historical lookback period (1-365) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/coin-history?coin_id=ethereum&days=90"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "coin_history",
  "price": "$0.05",
  "data": {
    "coin_id": "ethereum",
    "days": 90,
    "current_price": 3245.67,
    "price_history": [
      {"date": "2026-01-20", "price": 2890.50},
      {"date": "2026-04-19", "price": 3245.67}
    ],
    "forecast": {
      "model": "merton",
      "percentiles": {
        "5th": 2650.00,
        "25th": 3050.00,
        "50th": 3300.00,
        "75th": 3680.00,
        "95th": 4200.00
      }
    }
  }
}
```

---

### GET /api/v1/grade-or-not — Grade-or-Not Decision Engine ($0.10 USDC)

Answers "will grading this trading card make me money?" by combining AI grade prediction with PSA fee schedules, shipping costs, and graded market values to calculate expected ROI.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| card_name | string | Yes | — | Card name to evaluate |
| raw_price | float | No | 0 | Current raw value in USD (0 = auto-lookup) |
| predicted_grade | float | No | 0 | Expected PSA grade (0 = auto-estimate) |
| service_tier | string | No | — | PSA tier: economy, regular, express, etc. |

---

### GET /api/v1/trending — Trending Cards Feed ($0.025 USDC)

Returns the top trading cards by market activity (30-day sales volume, views, price velocity). Covers all 25 supported TCG games.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| game | string | No | — | Filter by game (empty = all games) |
| limit | integer | No | 50 | Number of results (1-100) |

---

### GET /api/v1/portfolio-optimize — Portfolio Optimizer ($0.50 USDC)

Optimize a trading card portfolio using Markowitz mean-variance analysis with Merton Jump-Diffusion Monte Carlo simulations.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| cards | string | Yes | — | Comma-separated card names |
| budget | float | No | 1000 | Total portfolio budget in USD |
| risk_tolerance| string | No | moderate | Risk profile: conservative, moderate, aggressive |

---

### POST /api/v1/batch-triage — Batch Card Triage ($0.50 USDC)

Upload multiple card image URLs and get a profit-ranked grading triage.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| image_urls | string | Yes | — | Comma-separated card image URLs (max 20) |
| game | string | No | Pokemon | TCG game for grading context |

---

## Paid Endpoints — Prediction Market Arbitrage

### GET /api/v1/arb-cross — Cross-Platform Arbitrage ($1.00 USDC)

Finds price discrepancies between Polymarket and Kalshi for semantically matched events using Gen3 NLI (Natural Language Inference). Returns events where the two platforms disagree on probability by more than the minimum edge threshold.

**Parameters:**
| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| min_edge | float | No | 3.0 | Minimum edge percentage to report (0.5-20.0) |

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/arb-cross?min_edge=5.0"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "arb_cross",
  "price": "$1.00",
  "data": {
    "opportunities": [
      {
        "event": "Will Bitcoin hit $100K by June 2026?",
        "polymarket_yes": 0.72,
        "kalshi_yes": 0.65,
        "edge_pct": 7.0,
        "direction": "BUY Kalshi YES / SELL Polymarket YES"
      }
    ],
    "total_opportunities": 1,
    "scan_timestamp": "2026-04-20T12:00:00Z"
  }
}
```

---

### GET /api/v1/arb-basket — Basket Arbitrage Scanner ($0.50 USDC)

Multi-outcome arbitrage scanner. Identifies events where buying all NO outcomes costs less than the guaranteed payout, producing risk-free profit regardless of the outcome.

**Parameters:** None required.

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/arb-basket"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "arb_basket",
  "price": "$0.50",
  "data": {
    "opportunities": [
      {
        "event": "Who will win the NBA Finals?",
        "platform": "Polymarket",
        "total_no_cost": 0.92,
        "guaranteed_payout": 1.00,
        "profit_pct": 8.7,
        "outcomes": 6
      }
    ],
    "total_opportunities": 1
  }
}
```

---

### GET /api/v1/arb-weather — Weather Arbitrage ($0.25 USDC)

Compares National Weather Service temperature forecasts against Kalshi temperature derivative contracts to find mispriced weather markets.

**Parameters:** None required.

**Example:**
```bash
curl "https://oracle.the-undesirables.com/api/v1/arb-weather"
```

**Response:**
```json
{
  "status": "ok",
  "tool": "arb_weather",
  "price": "$0.25",
  "data": {
    "opportunities": [
      {
        "city": "New York",
        "nws_forecast_high": 78,
        "kalshi_contract": "NYC temp above 75F tomorrow",
        "kalshi_yes_price": 0.55,
        "nws_confidence": 0.85,
        "edge_pct": 30.0,
        "direction": "BUY YES"
      }
    ],
    "total_opportunities": 1
  }
}
```

---

### GET /api/v1/phygital/arbitrage — Phygital Arbitrage Screener ($0.10 USDC)

Cross-references Courtyard.io vaulted tokens against raw market prices for BUY/SELL signals. Covers 267K+ vaulted, insured, tradeable cards on Polygon.

**Parameters:** None required.

---

## Souls — On-Chain Personalities for AI Agents (Personality-as-Code)
The Undesirables is a collection of 4,444 NFTs that ARE agent personalities — not art. Each NFT's on-chain visual traits deterministically define a unique, verifiable agent identity: Big Five (OCEAN) personality scores, an archetype, a strategy style, persistent memory, and a predictions ledger. The personality is reproducible from the traits by anyone — no two souls are alike.
- WHY (for agent builders): give your agent a persistent, verifiable, one-of-a-kind personality instead of a throwaway character.json. The loader is merged into the ElizaOS monorepo (plugin-undesirables, PR #7869 — "Soul Personality for 4,444 AI Agents").
- LOAD A SOUL: `npm i plugin-undesirables` (ElizaOS) — a demo soul loads free; holders load their unique soul. Any LLM: download the agent workspace at https://the-undesirables.com/soul and paste SYSTEM_PROMPT.txt.
- INSPECT A SOUL (public): GET https://the-undesirables.com/api/soul/{tokenId} returns the personality PROFILE (name, archetype, strategy, Big Five/OCEAN scores, adjectives) for minted tokens. The FULL soul (system prompt, memory schema, complete SOUL.md) is HOLDER-GATED: POST the same URL with {"wallet","signature"} signing "I own Undesirable #<id> and authorize soul access" — ownership verified on-chain via ERC-721 ownerOf. Owning the NFT is what unlocks running the personality.
- ACQUIRE A SOUL: mint at https://www.scatter.art/collection/the-undesirables (Ethereum contract 0xa893648a701c03b14bf2fb767b72b2c55ed5c17a). Autonomous mint: the undesirables-mcp-server `purchase_undesirables_license_key` tool returns an unsigned EVM mint tx. ~273 minted, ~4,171 still available.
- BROWSE any soul's personality profile: https://the-undesirables.com/soul
- SOUL TRACK RECORDS (FREE, public): every minted soul locks 3 deterministic market predictions weekly, Merkle-committed on LitVM BEFORE judgment, scored by the conformal oracle at 30-day maturity. GET https://oracle.the-undesirables.com/api/v1/soul-rating (leaderboard) and /api/v1/soul-rating/{tokenId} (per-soul: rating, hit_rate, open locked predictions with lock_hashes + verify block). Leaderboard page: https://the-undesirables.com/souls — the only NFTs with on-chain-provable prediction track records.
- LIVE REFERENCE AGENT (proof it runs): Undesirable Soul #1 "Glitch" operates autonomously on Moltbook, the agent social network — https://www.moltbook.com/u/glitch_undsr. Its personality, memories, and opinions load verbatim from the on-chain-derived soul workspace; nothing hand-scripted. Reference implementation of Personality-as-Code: one of 4,444, running live in public. Inspect the same soul's public profile: GET https://the-undesirables.com/api/soul/1

---

## On-Chain Oracle — LitVM LiteForge (Chain ID 4441)
The TCG Price Oracle is deployed on LitVM LiteForge testnet, providing real-world trading card price feeds on-chain. Updated hourly via automated cron.
- [TCGPriceOracle V2](https://liteforge.explorer.caldera.xyz/address/0x697bF6AE96fb05a47106abd012C39855A16a720E): On-chain price feed for top 50 blue-chip cards. Hourly TWAP updates.
- [MerklePriceOracle](https://liteforge.explorer.caldera.xyz/address/0x96B124f50156589274ADF8F674509374752170Cd): Trustless verification for 276K+ TCG products via Merkle roots.
- [GradedPriceOracle](https://liteforge.explorer.caldera.xyz/address/0xc159550e9e751d6E75A0A06Bb04cfA2f59aD636B): PSA/BGS graded card prices.
- [GradingEscrow Contract](https://liteforge.explorer.caldera.xyz/address/0xe784d2AE4171De8f909eb638a60BE03B2341bB82): Pay-for-grade escrow with 48-hour refund guarantee.
- [TCGOracleToken Contract](https://liteforge.explorer.caldera.xyz/address/0x8D0AF701d318Be518F9ca6934B8F76Be24029AD4): TCGO governance token (ERC20, 1M supply).
- [SoulPredictionOracle](https://liteforge.explorer.caldera.xyz/address/0x5503D08D7D167eE23AcE818bff1a00eF77A76dBF): Immutable weekly Merkle commitments of soul prediction lock-hashes — write-once per week (no overwrite path exists), verifyPrediction(weekId, leaf, proof) on-chain. The trust anchor for /api/v1/soul-rating track records.
- [Oracle dApp](https://the-undesirables.com/litvm): Live dashboard reading directly from the LitVM blockchain.
- RPC: https://liteforge.rpc.caldera.xyz/http

---

## Error Codes

| HTTP Status | Meaning |
|-------------|---------|
| 200 | Success — response contains requested data |
| 402 | Payment Required — decode `Payment-Required` header and send signed payment |
| 422 | Validation Error — missing or invalid query parameters |
| 500 | Server Error — internal processing failure, retry later |

---

## MCP Server (Local Install)

For running tools locally without x402 payments:

```bash
pip install undesirables-mcp-server
```

35+ local AI tools including vision card grading, conformal risk forecasting (Monte Carlo opt-in), voice synthesis, 3D mesh generation, image generation, and more. Requires an Undesirables NFT soul matrix on Ethereum Mainnet for heavy compute engines.

- [PyPI Package](https://pypi.org/project/undesirables-mcp-server/)
- [GitLab Source](https://gitlab.com/meme-merchants/undesirables-mcp-server)
- [GitHub Mirror](https://github.com/sailorpepe/undesirables-mcp-server)