Poke Perps

Trade perpetual futures on Pokemon TCG card prices via the PokePerps DEX on Solana. Search cards, analyze prices, simulate trades, open/close leveraged long/short positions, and manage portfolios. Use when the user asks about Pokemon card trading, perpetual futures, or PokePerps.

PokePerps AI Agent Skill

Platform: PokePerps — Decentralized Perpetual Futures Exchange for Pokemon TCG Card Prices Blockchain: Solana (mainnet-beta) Backend API: https://backend.pokeperps.fun WebSocket: wss://backend.pokeperps.fun/ws/trading Program ID: 8hH5CWo14R5QhaFUuXpxJytchS6NgrhRLHASyVeriEvN Collateral: USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)

PokePerps lets you trade perpetual futures contracts on real Pokemon Trading Card Game card prices. Prices are sourced from TCGPlayer marketplace in real-time and published on-chain via an Ed25519-signed oracle.

MCP Server (Recommended)

The easiest way for AI agents to interact with PokePerps is via the Model Context Protocol (MCP) server.

Read-only mode (no wallet required):

json

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

With trade execution (requires Solana keypair):

json

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

MCP Environment Variables

Variable	Description	Default
POKEPERPS_KEYPAIR	Path to Solana keypair JSON	(none - read-only mode)
POKEPERPS_API_URL	Backend API URL	https://backend.pokeperps.fun
POKEPERPS_RPC_URL	Solana RPC URL	https://api.mainnet-beta.solana.com

MCP Tools

Read-only tools (always available):

Tool	Description
get_market_movers	Top gainers, losers, and most volatile cards
get_portfolio	Complete portfolio with computed PnL for a wallet
get_trading_signals	Pre-computed trading signals and recommendations
prepare_trade	Validate a trade before opening (margin, fees, risks)
simulate_trade	Simulate PnL scenarios at different price levels
search_cards	Search Pokemon cards by name
get_card_details	Full card info with listings, sales, history
batch_get_cards	Fetch up to 50 cards in one request
get_tradable_products	List all product IDs with active markets
get_trading_config	Trading parameters (leverage, fees, etc.)

Execution tools (require POKEPERPS_KEYPAIR):

Tool	Description
open_position	Open a new long/short position
close_position	Close an existing position to realize PnL
deposit	Deposit USDC into trading account
withdraw	Withdraw USDC from trading account
get_wallet_status	Check wallet balance and execution status

MCP Resources

• pokeperps://docs/trading-guide — Trading guide and risk parameters
• pokeperps://docs/api-reference — Full OpenAPI specification

Trading Parameters

Parameter	Value
Max leverage	50x
Min position size	$1 USDC
Max position per user	$100,000 USDC
Trading fee	0.05% (5 bps) on open and close
Maintenance margin	1% (100 bps)
Liquidation fee	0.5% to liquidator + 0.5% to insurance
Funding interval	8 hours
Funding rate cap	±0.05% per interval
Oracle price max age	15 seconds
Collateral	USDC (SPL Token)

What you can do:

• Go long (bet price goes up) or short (bet price goes down)
• Use 1x–50x leverage
• Positions have no expiry (perpetual)
• Close anytime to realize PnL
• Prices track real TCGPlayer marketplace prices

Architecture

text

Agent (you)
  │
  ├── REST API (https://backend.pokeperps.fun/api/...)
  │     ├── Read-only: card data, prices, markets, positions
  │     └── Transaction builders: returns params for Solana transactions
  │
  ├── WebSocket (wss://backend.pokeperps.fun/ws/trading)
  │     └── Real-time price updates, position events
  │
  └── Solana RPC (https://api.mainnet-beta.solana.com)
        └── Sign & send transactions built from API params

The backend does NOT sign or submit transactions. It provides instruction data and account addresses. You build, sign, and submit transactions client-side.

Key API Endpoints

Base URL: https://backend.pokeperps.fun

Card Discovery

Method	Path	Description
GET	/api/cards/search?q={query}&limit={1-50}	Search cards by name
GET	/api/dashboard?limit={1-200}	Top tradable cards + biggest mover
GET	/api/cards/{product_id}	Full card details
GET	/api/cards/{product_id}/bundle	All card data in one call
GET	/api/cards/{product_id}/history?range=month	Price history
GET	/api/cards/{product_id}/signals	Trading signals & recommendations
POST	/api/cards/batch	Fetch up to 50 cards at once

Trading

Method	Path	Description
GET	/api/trading/tradable	All tradable product IDs
GET	/api/trading/config	Trading parameters
GET	/api/trading/exchange	Exchange state
GET	/api/trading/market/{product_id}	Market state
GET	/api/trading/market/{product_id}/stats	Market statistics
GET	/api/trading/account/{wallet}	User account
GET	/api/trading/account/{wallet}/positions	User positions
GET	/api/trading/portfolio/{wallet}	Full portfolio with computed PnL
GET	/api/trading/prepare-trade/{id}?wallet=X&side=Y&size=Z&leverage=W	Pre-trade validation
POST	/api/trading/simulate	Trade simulation with scenarios
GET	/api/trading/analytics/movers?limit={1-50}	Top gainers, losers, volatile

Transaction Builders

Method	Path	Description
POST	/api/trading/tx/create-account	Create trading account
POST	/api/trading/tx/deposit	Deposit USDC
POST	/api/trading/tx/withdraw	Withdraw USDC
POST	/api/trading/tx/open-position	Open long/short position
POST	/api/trading/tx/close-position	Close position
POST	/api/trading/tx/add-margin	Add margin to position

Oracle

Method	Path	Description
GET	/api/oracle/prices	All current oracle prices
GET	/api/oracle/router/prices	Best available prices
GET	/api/trading/oracle/{product_id}	Single product price
POST	/api/trading/oracle/prices	Batch oracle prices

See references/API.md for full request/response schemas.

Optimized Trading Flow

text

1. GET /api/trading/analytics/movers       → Find opportunities
2. POST /api/cards/batch                   → Fetch details for candidates
3. GET /api/cards/{id}/signals             → Get trading recommendation
4. GET /api/trading/prepare-trade/{id}     → Validate trade
5. POST /api/trading/tx/open-position      → Execute trade
6. GET /api/trading/portfolio/{wallet}     → Monitor positions

This uses 6 API calls instead of 15+ in the traditional flow.

PnL Calculation

text

margin = size / leverage
fee = size * 0.0005  (0.05% on open, same on close)

For long:
  unrealized_pnl = size * (current_price - entry_price) / entry_price
  liquidation_price = entry_price * (1 - (margin - maintenance_margin) / size)

For short:
  unrealized_pnl = size * (entry_price - current_price) / entry_price
  liquidation_price = entry_price * (1 + (margin - maintenance_margin) / size)

Maintenance margin = size * 0.01 (1%)

Decision-Making Signals

Use /api/cards/{id}/signals for pre-computed analysis:

Bullish (go long):

• Positive change_24h with high activity_score
• Recent sales trending above market_price
• Decreasing listing count (supply shrinking)
• High short OI relative to long (potential short squeeze)

Bearish (go short):

• Negative change_24h and change_30d
• Recent sales trending below market_price
• Increasing listing count (supply growing)
• High long OI relative to short (potential long squeeze)

WebSocket

Connect to wss://backend.pokeperps.fun/ws/trading:

json

{ "type": "subscribe", "products": [123456], "accounts": ["YourWallet"] }
{ "type": "ping" }

Events: price_update, position_opened, position_closed, market_stats, account_update

Rate Limits

Limit	Value
Global API rate limit	300 requests/min per IP
Oracle price signing	2 per 10 seconds per IP per product
WebSocket connections	25 per IP, 1000 total
Max batch product IDs	200 per request

Error Codes

Code	Name	Meaning
6012	InvalidAmount	Zero or negative amount
6013	InsufficientBalance	Not enough USDC
6014	ExchangePaused	Exchange is paused
6015	InvalidLeverage	Outside 1-50 range
6016	PositionTooSmall	Below $1 minimum
6018	MarketInactive	Market disabled
6019	MaxOpenInterestExceeded	OI at capacity
6030	OraclePriceStale	Price older than 15s
6031	PositionTooLarge	Above $100k max
6035	InvalidEd25519Instruction	Ed25519 precompile malformed

See references/API.md for full error reference.

Agent Best Practices

Minimize API Calls

Instead of...	Use...
GET /account + GET /positions + oracle calls	GET /api/trading/portfolio/{wallet} (1 call)
Multiple GET /api/cards/{id} calls	POST /api/cards/batch (1 call for up to 50)
5+ calls to validate a trade	GET /api/trading/prepare-trade/{id} (1 call)
Scanning all cards for movers	GET /api/trading/analytics/movers (1 call)

Position Management

1. Check riskStatus before opening new positions — avoid if warning or danger
2. Use distanceToLiquidation for stop-loss (conservative: close if <10%, moderate: <5%)
3. Monitor fundingDirection — avoid positions that pay funding
4. Check wouldExceedOI before large trades

Security

• Always verify PDAs client-side before signing transactions
• Never expose private keys in API calls
• Validate oracleAge < 15 seconds before trading
• Check canTrade from prepare-trade before proceeding

Additional References

• references/API.md — Full API request/response schemas
• references/TRANSACTIONS.md — On-chain transaction construction, PDA derivation, Ed25519 signing
• references/EXAMPLES.md — Complete code examples (TypeScript, Python, cURL)