{"skill":{"slug":"pokeperps","displayName":"Poke Perps","summary":"Trade perpetual futures on Pokemon TCG card prices via the PokePerps DEX on Solana. Search cards, analyze prices, simulate trades, open/close leveraged long/...","description":"---\nname: pokeperps\ndescription: 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.\nlicense: BUSL-1.1\ncompatibility: Requires network access to https://backend.pokeperps.fun. Optional Solana keypair for trade execution.\nmetadata:\n  author: ankushKun\n  version: \"1.0\"\n  website: https://pokeperps.fun\n  blockchain: solana\n---\n\n# PokePerps AI Agent Skill\n\n> **Platform**: [PokePerps](https://pokeperps.fun) — Decentralized Perpetual Futures Exchange for Pokemon TCG Card Prices\n> **Blockchain**: Solana (mainnet-beta)\n> **Backend API**: `https://backend.pokeperps.fun`\n> **WebSocket**: `wss://backend.pokeperps.fun/ws/trading`\n> **Program ID**: `8hH5CWo14R5QhaFUuXpxJytchS6NgrhRLHASyVeriEvN`\n> **Collateral**: USDC (`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`)\n\nPokePerps 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.\n\n## MCP Server (Recommended)\n\nThe easiest way for AI agents to interact with PokePerps is via the **Model Context Protocol (MCP) server**.\n\n**Read-only mode** (no wallet required):\n```json\n{\n  \"mcpServers\": {\n    \"pokeperps\": {\n      \"command\": \"npx\",\n      \"args\": [\"@pokeperps/mcp\"]\n    }\n  }\n}\n```\n\n**With trade execution** (requires Solana keypair):\n```json\n{\n  \"mcpServers\": {\n    \"pokeperps\": {\n      \"command\": \"npx\",\n      \"args\": [\"@pokeperps/mcp\"],\n      \"env\": {\n        \"POKEPERPS_KEYPAIR\": \"/path/to/your/keypair.json\"\n      }\n    }\n  }\n}\n```\n\n### MCP Environment Variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `POKEPERPS_KEYPAIR` | Path to Solana keypair JSON | (none - read-only mode) |\n| `POKEPERPS_API_URL` | Backend API URL | `https://backend.pokeperps.fun` |\n| `POKEPERPS_RPC_URL` | Solana RPC URL | `https://api.mainnet-beta.solana.com` |\n\n### MCP Tools\n\n**Read-only tools** (always available):\n\n| Tool | Description |\n|---|---|\n| `get_market_movers` | Top gainers, losers, and most volatile cards |\n| `get_portfolio` | Complete portfolio with computed PnL for a wallet |\n| `get_trading_signals` | Pre-computed trading signals and recommendations |\n| `prepare_trade` | Validate a trade before opening (margin, fees, risks) |\n| `simulate_trade` | Simulate PnL scenarios at different price levels |\n| `search_cards` | Search Pokemon cards by name |\n| `get_card_details` | Full card info with listings, sales, history |\n| `batch_get_cards` | Fetch up to 50 cards in one request |\n| `get_tradable_products` | List all product IDs with active markets |\n| `get_trading_config` | Trading parameters (leverage, fees, etc.) |\n\n**Execution tools** (require `POKEPERPS_KEYPAIR`):\n\n| Tool | Description |\n|---|---|\n| `open_position` | Open a new long/short position |\n| `close_position` | Close an existing position to realize PnL |\n| `deposit` | Deposit USDC into trading account |\n| `withdraw` | Withdraw USDC from trading account |\n| `get_wallet_status` | Check wallet balance and execution status |\n\n### MCP Resources\n\n- `pokeperps://docs/trading-guide` — Trading guide and risk parameters\n- `pokeperps://docs/api-reference` — Full OpenAPI specification\n\n## Trading Parameters\n\n| Parameter | Value |\n|---|---|\n| Max leverage | 50x |\n| Min position size | $1 USDC |\n| Max position per user | $100,000 USDC |\n| Trading fee | 0.05% (5 bps) on open and close |\n| Maintenance margin | 1% (100 bps) |\n| Liquidation fee | 0.5% to liquidator + 0.5% to insurance |\n| Funding interval | 8 hours |\n| Funding rate cap | ±0.05% per interval |\n| Oracle price max age | 15 seconds |\n| Collateral | USDC (SPL Token) |\n\n**What you can do:**\n- Go **long** (bet price goes up) or **short** (bet price goes down)\n- Use 1x–50x leverage\n- Positions have no expiry (perpetual)\n- Close anytime to realize PnL\n- Prices track real TCGPlayer marketplace prices\n\n## Architecture\n\n```\nAgent (you)\n  │\n  ├── REST API (https://backend.pokeperps.fun/api/...)\n  │     ├── Read-only: card data, prices, markets, positions\n  │     └── Transaction builders: returns params for Solana transactions\n  │\n  ├── WebSocket (wss://backend.pokeperps.fun/ws/trading)\n  │     └── Real-time price updates, position events\n  │\n  └── Solana RPC (https://api.mainnet-beta.solana.com)\n        └── Sign & send transactions built from API params\n```\n\nThe backend does NOT sign or submit transactions. It provides instruction data and account addresses. You build, sign, and submit transactions client-side.\n\n## Key API Endpoints\n\nBase URL: `https://backend.pokeperps.fun`\n\n### Card Discovery\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/cards/search?q={query}&limit={1-50}` | Search cards by name |\n| GET | `/api/dashboard?limit={1-200}` | Top tradable cards + biggest mover |\n| GET | `/api/cards/{product_id}` | Full card details |\n| GET | `/api/cards/{product_id}/bundle` | All card data in one call |\n| GET | `/api/cards/{product_id}/history?range=month` | Price history |\n| GET | `/api/cards/{product_id}/signals` | Trading signals & recommendations |\n| POST | `/api/cards/batch` | Fetch up to 50 cards at once |\n\n### Trading\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/trading/tradable` | All tradable product IDs |\n| GET | `/api/trading/config` | Trading parameters |\n| GET | `/api/trading/exchange` | Exchange state |\n| GET | `/api/trading/market/{product_id}` | Market state |\n| GET | `/api/trading/market/{product_id}/stats` | Market statistics |\n| GET | `/api/trading/account/{wallet}` | User account |\n| GET | `/api/trading/account/{wallet}/positions` | User positions |\n| GET | `/api/trading/portfolio/{wallet}` | Full portfolio with computed PnL |\n| GET | `/api/trading/prepare-trade/{id}?wallet=X&side=Y&size=Z&leverage=W` | Pre-trade validation |\n| POST | `/api/trading/simulate` | Trade simulation with scenarios |\n| GET | `/api/trading/analytics/movers?limit={1-50}` | Top gainers, losers, volatile |\n\n### Transaction Builders\n\n| Method | Path | Description |\n|---|---|---|\n| POST | `/api/trading/tx/create-account` | Create trading account |\n| POST | `/api/trading/tx/deposit` | Deposit USDC |\n| POST | `/api/trading/tx/withdraw` | Withdraw USDC |\n| POST | `/api/trading/tx/open-position` | Open long/short position |\n| POST | `/api/trading/tx/close-position` | Close position |\n| POST | `/api/trading/tx/add-margin` | Add margin to position |\n\n### Oracle\n\n| Method | Path | Description |\n|---|---|---|\n| GET | `/api/oracle/prices` | All current oracle prices |\n| GET | `/api/oracle/router/prices` | Best available prices |\n| GET | `/api/trading/oracle/{product_id}` | Single product price |\n| POST | `/api/trading/oracle/prices` | Batch oracle prices |\n\nSee [references/API.md](references/API.md) for full request/response schemas.\n\n## Optimized Trading Flow\n\n```\n1. GET /api/trading/analytics/movers       → Find opportunities\n2. POST /api/cards/batch                   → Fetch details for candidates\n3. GET /api/cards/{id}/signals             → Get trading recommendation\n4. GET /api/trading/prepare-trade/{id}     → Validate trade\n5. POST /api/trading/tx/open-position      → Execute trade\n6. GET /api/trading/portfolio/{wallet}     → Monitor positions\n```\n\nThis uses **6 API calls** instead of 15+ in the traditional flow.\n\n## PnL Calculation\n\n```\nmargin = size / leverage\nfee = size * 0.0005  (0.05% on open, same on close)\n\nFor long:\n  unrealized_pnl = size * (current_price - entry_price) / entry_price\n  liquidation_price = entry_price * (1 - (margin - maintenance_margin) / size)\n\nFor short:\n  unrealized_pnl = size * (entry_price - current_price) / entry_price\n  liquidation_price = entry_price * (1 + (margin - maintenance_margin) / size)\n\nMaintenance margin = size * 0.01 (1%)\n```\n\n## Decision-Making Signals\n\nUse `/api/cards/{id}/signals` for pre-computed analysis:\n\n**Bullish (go long):**\n- Positive `change_24h` with high `activity_score`\n- Recent sales trending above `market_price`\n- Decreasing listing count (supply shrinking)\n- High short OI relative to long (potential short squeeze)\n\n**Bearish (go short):**\n- Negative `change_24h` and `change_30d`\n- Recent sales trending below `market_price`\n- Increasing listing count (supply growing)\n- High long OI relative to short (potential long squeeze)\n\n## WebSocket\n\nConnect to `wss://backend.pokeperps.fun/ws/trading`:\n\n```json\n{ \"type\": \"subscribe\", \"products\": [123456], \"accounts\": [\"YourWallet\"] }\n{ \"type\": \"ping\" }\n```\n\nEvents: `price_update`, `position_opened`, `position_closed`, `market_stats`, `account_update`\n\n## Rate Limits\n\n| Limit | Value |\n|---|---|\n| Global API rate limit | 300 requests/min per IP |\n| Oracle price signing | 2 per 10 seconds per IP per product |\n| WebSocket connections | 25 per IP, 1000 total |\n| Max batch product IDs | 200 per request |\n\n## Error Codes\n\n| Code | Name | Meaning |\n|---|---|---|\n| 6012 | InvalidAmount | Zero or negative amount |\n| 6013 | InsufficientBalance | Not enough USDC |\n| 6014 | ExchangePaused | Exchange is paused |\n| 6015 | InvalidLeverage | Outside 1-50 range |\n| 6016 | PositionTooSmall | Below $1 minimum |\n| 6018 | MarketInactive | Market disabled |\n| 6019 | MaxOpenInterestExceeded | OI at capacity |\n| 6030 | OraclePriceStale | Price older than 15s |\n| 6031 | PositionTooLarge | Above $100k max |\n| 6035 | InvalidEd25519Instruction | Ed25519 precompile malformed |\n\nSee [references/API.md](references/API.md) for full error reference.\n\n## Agent Best Practices\n\n### Minimize API Calls\n\n| Instead of... | Use... |\n|---|---|\n| `GET /account` + `GET /positions` + oracle calls | `GET /api/trading/portfolio/{wallet}` (1 call) |\n| Multiple `GET /api/cards/{id}` calls | `POST /api/cards/batch` (1 call for up to 50) |\n| 5+ calls to validate a trade | `GET /api/trading/prepare-trade/{id}` (1 call) |\n| Scanning all cards for movers | `GET /api/trading/analytics/movers` (1 call) |\n\n### Position Management\n\n1. Check `riskStatus` before opening new positions — avoid if `warning` or `danger`\n2. Use `distanceToLiquidation` for stop-loss (conservative: close if <10%, moderate: <5%)\n3. Monitor `fundingDirection` — avoid positions that pay funding\n4. Check `wouldExceedOI` before large trades\n\n### Security\n\n- Always verify PDAs client-side before signing transactions\n- Never expose private keys in API calls\n- Validate `oracleAge` < 15 seconds before trading\n- Check `canTrade` from `prepare-trade` before proceeding\n\n## Additional References\n\n- [references/API.md](references/API.md) — Full API request/response schemas\n- [references/TRANSACTIONS.md](references/TRANSACTIONS.md) — On-chain transaction construction, PDA derivation, Ed25519 signing\n- [references/EXAMPLES.md](references/EXAMPLES.md) — Complete code examples (TypeScript, Python, cURL)\n","topics":["Trading"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":283,"installsAllTime":10,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771444803791,"updatedAt":1778991521993},"latestVersion":{"version":"1.0.0","createdAt":1771444803791,"changelog":"Initial release of pokeperps — trade perpetual futures on Pokémon TCG card prices.\n\n- Allows searching Pokémon cards and analyzing real-time price data.\n- Simulate trades, open/close leveraged long or short positions, and manage portfolios.\n- Supports up to 50x leverage, with no expiry on positions (perpetual contracts).\n- Integrated with PokePerps DEX on Solana and requires network access.\n- Includes pre-trade validation, PnL calculation, and portfolio monitoring tools.\n- Offers both read-only and trade execution modes (via Solana keypair).\n- Accessible documentation and API reference for further integration.","license":null},"metadata":null,"owner":{"handle":"ankushkun","userId":"s17cd24vzz5bzyr6ytbg5yek6d885t3n","displayName":"Ankush Singh","image":"https://avatars.githubusercontent.com/u/50258860?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779932736416}}