Skill: ankushkun/pokeperps (version 1.0.0)

--- name: pokeperps description: 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. license: BUSL-1.1 compatibility: Requires network access to https://backend.pokeperps.fun. Optional Solana keypair for trade execution. metadata: author: ankushKun version: "1.0" website: https://pokeperps.fun blockchain: solana --- # PokePerps AI Agent Skill > **Platform**: [PokePerps](https://pokeperps.fun) — 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**: [REDACTED_SECRET] > **Collateral**: USDC ([REDACTED_SECRET]) 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 ``` 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](references/API.md) for full request/response schemas. ## Optimized Trading Flow ``` 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 ``` 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](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](references/API.md) — Full API request/response schemas - [references/TRANSACTIONS.md](references/TRANSACTIONS.md) — On-chain transaction construction, PDA derivation, Ed25519 signing - [references/EXAMPLES.md](references/EXAMPLES.md) — Complete code examples (TypeScript, Python, cURL)


Security scan verdicts — ClawScan: suspicious | static analysis:  | VirusTotal: suspicious | SkillSpector: suspicious (HIGH)