PokePerps

A decentralized perpetual futures exchange for trading Pokemon card prices on Solana.

Website: https://pokeperps.fun
API Docs: https://pokeperps.fun/docs
MCP Server: @pokeperps/mcp

Overview

PokePerps enables traders to go long or short on Pokemon card prices with up to 50x leverage. Prices are sourced from TCGPlayer marketplace data and published on-chain via Solana oracle feeds. All trading is non-custodial with positions, margin, and settlement handled entirely by smart contracts.

Key Features

• Perpetual Futures - No expiry dates, no settlement. Trade continuously.
• Up to 50x Leverage - Amplify exposure with configurable leverage.
• Real-Time Pricing - TCGPlayer market prices updated every 30 seconds.
• Non-Custodial - Funds remain in your Solana wallet. Smart contracts handle everything.
• AI Agent Integration - MCP server for Claude and other AI agents to trade programmatically.

Architecture

TCGPlayer.com                    Solana Blockchain
(card prices)                    (settlement layer)
      │                                │
      │ scrape every 30s               │
      v                                v
┌──────────┐    publish prices    ┌──────────────┐
│ Backend  │ ──────────────────> │   On-Chain   │
│ (Elysia) │                     │   Program    │
│          │ <────────────────── │              │
│          │    read state       │ (positions)  │
└────┬─────┘                     └──────────────┘
     │ REST + WebSocket                 ^
     v                                  │ sign txs
┌──────────┐                            │
│ Frontend │ ───────────────────────────┘
│ (React)  │   Phantom wallet
└──────────┘

Project Structure

Directory	Description	Documentation
backend/	API server and oracle keeper (Bun + Elysia)	README
frontend/	Trading interface (React + Tailwind)	README
program/	Solana on-chain program (Rust + Pinocchio)	README
mcp-server/	MCP server for AI agents	README
APIs/	TCGPlayer API reference	README

Quick Start

Prerequisites

• Bun (latest)
• Rust + cargo-build-sbf (for program development)
• Solana CLI

Development Setup

# Clone the repository
git clone https://github.com/ankushKun/pokeperps.git
cd pokeperps

# Copy environment configuration
cp .env.example .env
# Edit .env with your RPC URLs and keypair paths

# Install dependencies
cd backend && bun install && cd ..
cd frontend && bun install && cd ..

# Start backend (port 8001)
cd backend && bun run dev

# Start frontend (port 3001) - in another terminal
cd frontend && bun run dev

Build Program

cd program
cargo build-sbf
SBF_OUT_DIR=target/deploy cargo test

Live URLs

Resource	URL
Website	https://pokeperps.fun
Trading App	https://pokeperps.fun/app
API Documentation	https://pokeperps.fun/docs
OpenAPI Spec	https://backend.pokeperps.fun/api/docs/json
AI Agent Guide	https://pokeperps.fun/SKILL.md
LLMs Guide	https://pokeperps.fun/llms.txt
Backend API	https://backend.pokeperps.fun

AI Agent Integration

PokePerps provides two ways for AI agents to interact with the platform:

Security: Use a dedicated trading wallet with only the funds you intend to trade. Your keypair never leaves your machine - all signing is done locally.

MCP Server (Recommended)

Claude Code

claude mcp add pokeperps -- npx -y @pokeperps/mcp

For trade execution, pass your keypair:

claude mcp add pokeperps -e POKEPERPS_KEYPAIR=/path/to/keypair.json -- npx -y @pokeperps/mcp

Omit POKEPERPS_KEYPAIR for read-only mode (search cards, check prices, no trading).

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pokeperps": {
      "command": "npx",
      "args": ["-y", "@pokeperps/mcp"],
      "env": {
        "POKEPERPS_KEYPAIR": "/path/to/keypair.json"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "pokeperps": {
      "command": "npx",
      "args": ["-y", "@pokeperps/mcp"]
    }
  }
}

SKILL.md

Alternatively, agents can fetch instructions from https://pokeperps.fun/SKILL.md which contains comprehensive trading documentation.

Program Addresses

Network	Program ID
Mainnet	8hH5CWo14R5QhaFUuXpxJytchS6NgrhRLHASyVeriEvN
Devnet	AzYLMDPsNDvzb8ShhVzNWBVv6k9ogCKpqdjWMhnkATdz

USDC Mint (Mainnet): EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Technology Stack

Component	Technology
Program	Rust + Pinocchio
Backend	TypeScript + Elysia + SQLite
Frontend	React 19 + Tailwind v4 + shadcn/ui
Wallet	Phantom Connect
Runtime	Bun

Configuration

The project uses a single .env file at the root. See .env.example for all available options.

Key variables:

Variable	Description
SOLANA_RPC_URL	Solana RPC endpoint (backend)
PROGRAM_ID	On-chain program address
USDC_MINT	USDC token mint
KEEPER_KEYPAIR_PATH	Oracle keeper keypair
BUN_PUBLIC_SOLANA_RPC_URL	Solana RPC (frontend)

License

Business Source License 1.1 (BUSL-1.1), non-commercial use only. Automatically changes to GNU GPLv3 on 2030-02-18.

Author

Built by @ankushKun_