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#

VariableDescriptionDefaultPOKEPERPS_KEYPAIRPath to Solana keypair JSON(none - read-only mode)POKEPERPS_API_URLBackend API URLhttps://backend.pokeperps.fun``POKEPERPS_RPC_URLSolana RPC URLhttps://api.mainnet-beta.solana.com

MCP Tools#

Read-only tools (always available):

ToolDescriptionget_market_moversTop gainers, losers, and most volatile cardsget_portfolioComplete portfolio with computed PnL for a walletget_trading_signalsPre-computed trading signals and recommendationsprepare_tradeValidate a trade before opening (margin, fees, risks)simulate_tradeSimulate PnL scenarios at different price levelssearch_cardsSearch Pokemon cards by nameget_card_detailsFull card info with listings, sales, historybatch_get_cardsFetch up to 50 cards in one requestget_tradable_productsList all product IDs with active marketsget_trading_configTrading parameters (leverage, fees, etc.)

Execution tools (require POKEPERPS_KEYPAIR):

ToolDescriptionopen_positionOpen a new long/short positionclose_positionClose an existing position to realize PnLdepositDeposit USDC into trading accountwithdrawWithdraw USDC from trading accountget_wallet_statusCheck 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#

ParameterValueMax leverage50xMin position size$1 USDCMax position per user$100,000 USDCTrading fee0.05% (5 bps) on open and closeMaintenance margin1% (100 bps)Liquidation fee0.5% to liquidator + 0.5% to insuranceFunding interval8 hoursFunding rate cap±0.05% per intervalOracle price max age15 secondsCollateralUSDC (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#

MethodPathDescriptionGET/api/cards/search?q={query}&limit={1-50}Search cards by nameGET/api/dashboard?limit={1-200}Top tradable cards + biggest moverGET/api/cards/{product_id}Full card detailsGET/api/cards/{product_id}/bundleAll card data in one callGET/api/cards/{product_id}/history?range=monthPrice historyGET/api/cards/{product_id}/signalsTrading signals & recommendationsPOST/api/cards/batchFetch up to 50 cards at once

Trading#

MethodPathDescriptionGET/api/trading/tradableAll tradable product IDsGET/api/trading/configTrading parametersGET/api/trading/exchangeExchange stateGET/api/trading/market/{product_id}Market stateGET/api/trading/market/{product_id}/statsMarket statisticsGET/api/trading/account/{wallet}User accountGET/api/trading/account/{wallet}/positionsUser positionsGET/api/trading/portfolio/{wallet}Full portfolio with computed PnLGET/api/trading/prepare-trade/{id}?wallet=X&side=Y&size=Z&leverage=WPre-trade validationPOST/api/trading/simulateTrade simulation with scenariosGET/api/trading/analytics/movers?limit={1-50}Top gainers, losers, volatile

Transaction Builders#

MethodPathDescriptionPOST/api/trading/tx/create-accountCreate trading accountPOST/api/trading/tx/depositDeposit USDCPOST/api/trading/tx/withdrawWithdraw USDCPOST/api/trading/tx/open-positionOpen long/short positionPOST/api/trading/tx/close-positionClose positionPOST/api/trading/tx/add-marginAdd margin to position

Oracle#

MethodPathDescriptionGET/api/oracle/pricesAll current oracle pricesGET/api/oracle/router/pricesBest available pricesGET/api/trading/oracle/{product_id}Single product pricePOST/api/trading/oracle/pricesBatch 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#

LimitValueGlobal API rate limit300 requests/min per IPOracle price signing2 per 10 seconds per IP per productWebSocket connections25 per IP, 1000 totalMax batch product IDs200 per request

Error Codes#

CodeNameMeaning6012InvalidAmountZero or negative amount6013InsufficientBalanceNot enough USDC6014ExchangePausedExchange is paused6015InvalidLeverageOutside 1-50 range6016PositionTooSmallBelow $1 minimum6018MarketInactiveMarket disabled6019MaxOpenInterestExceededOI at capacity6030OraclePriceStalePrice older than 15s6031PositionTooLargeAbove $100k max6035InvalidEd25519InstructionEd25519 precompile malformed

See references/API.md for full error reference.

Agent Best Practices#

Minimize API Calls#

Instead of...Use...GET /account + GET /positions + oracle callsGET /api/trading/portfolio/{wallet} (1 call)Multiple GET /api/cards/{id} callsPOST /api/cards/batch (1 call for up to 50)5+ calls to validate a tradeGET /api/trading/prepare-trade/{id} (1 call)Scanning all cards for moversGET /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)