Opinion.trade MCP Server

# Opinion.trade MCP Server Model Context Protocol (MCP) server for [Opinion.trade](https://opinion.trade) - a decentralized prediction markets platform on BNB Chain. ## Features ### Dual-Mode Operation - **Read-Only Mode**: Market data access with API key only - **Trading Mode**: Full trading capabilities with private key for EIP712 signing ### Available Tools (13 Total) #### Public API Tools (6 - API key only) 1. `get_markets` - List prediction markets with filtering 2. `get_market_details` - Get detailed market information 3. `get_token_price` - Current token/outcome prices 4. `get_orderbook` - Order book depth (bids/asks) 5. `get_price_history` - Historical OHLCV data 6. `search_markets` - Search markets by keyword #### Trading Tools (7 - Requires private key) 7. `place_order` - Place limit/market orders with EIP712 signing 8. `cancel_order` - Cancel specific order 9. `cancel_all_orders` - Cancel all open orders 10. `get_open_orders` - List user's open orders 11. `get_positions` - Get positions with P&L 12. `get_trade_history` - Executed trades history 13. `get_balances` - Account balances (available + locked) ## Installation ### Prerequisites - Python 3.10 or higher - Opinion.trade API key ([Get one here](https://docs.opinion.trade/)) ### Install from source ```bash # Clone or navigate to the directory cd mcp-opinion-trade # Install in development mode pip install -e . ``` ## Configuration ### 1. Create .env file ```bash cp .env.example .env ``` ### 2. Configure environment variables **Minimum configuration (read-only mode):** ```bash OPINION_API_KEY=your_api_key_here ``` **Full configuration (trading mode):** ```bash # Required OPINION_API_KEY=your_api_key_here # Trading mode (optional) OPINION_PRIVATE_KEY=0x... # Your Ethereum private key # Network (optional) OPINION_CHAIN_ID=56 # 56=BNB mainnet, 97=BNB testnet ``` ### 3. Configure Claude Code Add to your Claude Code MCP settings: ```json { "mcpServers": { "opinion-trade": { "command": "python", "args": ["-m", "mcp_opinion"], "env": { "OPINION_API_KEY": "your_api_key_here" } } } } ``` Or use the installed command: ```json { "mcpServers": { "opinion-trade": { "command": "mcp-opinion-trade" } } } ``` ## Usage Examples ### Read-Only Mode (Market Data) ``` User: What are the top prediction markets on Opinion.trade? Claude: Let me check the top markets on Opinion.trade. → Uses get_markets tool User: What's the current price for token ABC123? Claude: I'll get the current price for that token. → Uses get_token_price tool User: Show me the orderbook for token XYZ789 Claude: I'll fetch the orderbook depth. → Uses get_orderbook tool ``` ### Trading Mode (Requires Private Key) ``` User: Place a limit buy order for 100 units of token ABC123 at price 0.55 Claude: I'll place that limit buy order for you. → Uses place_order tool with EIP712 signing User: What are my current positions? Claude: Let me get your open positions. → Uses get_positions tool User: Cancel all my open orders Claude: I'll cancel all your open orders. → Uses cancel_all_orders tool ``` ## Security Best Practices ### API Keys - Never commit your `.env` file to version control - Store API keys securely using environment variables - Rotate API keys periodically ### Private Keys - **NEVER** share your private key - **NEVER** commit private keys to version control - Use hardware wallets for production trading - Consider using a dedicated trading wallet with limited funds - The private key is used for EIP712 signing (not transmitted to API) ### Environment - Use `.env` files for local development - Use secure secret management for production - Verify you're on the correct network (mainnet vs testnet) ## Architecture ### Dual-Mode Design The server automatically detects trading mode based on private key presence: ```python # Read-only mode (API key only) config = OpinionConfig(api_key="...", private_key=None) # → Only 6 public API tools available # Trading mode (API key + private key) config = OpinionConfig(api_key="...", private_key="0x...") # → All 13 tools available (6 public + 7 trading) ``` ### Components - **PublicClient**: Handles market data via REST API (httpx) - **TradingClient**: Wraps `opinion_clob_sdk` for trading with EIP712 signing - **OpinionConfig**: Environment-based configuration with validation - **Pydantic Models**: Type-safe request validation - **MCP Server**: Tool registration and routing with error handling ## API Response Format Opinion.trade API responses follow this structure: ```json { "code": 0, "msg": "success", "result": { "data": {...} // or "list": [...] } } ``` - `code`: 0 for success, non-zero for errors - `msg`: Human-readable message - `result`: Contains either `data` (single object) or `list` (array) ## Error Handling The server provides detailed error messages: ```json { "error": "Order placement failed: Insufficient balance", "error_code": "INSUFFICIENT_BALANCE", "status_code": 400, "is_error": true } ``` Common error codes: - `VALIDATION_ERROR`: Invalid input parameters - `API_ERROR`: Opinion.trade API error - `TRADING_DISABLED`: Trading tools called without private key - `INTERNAL_ERROR`: Unexpected server error ## Development ### Running Tests ```bash # Install development dependencies pip install -e ".[dev]" # Run tests pytest # Run with coverage pytest --cov=mcp_opinion --cov-report=term-missing ``` ### Code Formatting ```bash # Format code black src/ # Lint code ruff check src/ ``` ## Troubleshooting ### "API key is required" error - Ensure `OPINION_API_KEY` is set in `.env` - Verify `.env` file is in the project root directory - Check that `python-dotenv` is installed ### "Trading tools not available" error - Set `OPINION_PRIVATE_KEY` in `.env` to enable trading mode - Ensure private key starts with `0x` - Verify private key corresponds to a funded BNB Chain wallet ### "opinion-clob-sdk not found" error - Install the SDK: `pip install opinion-clob-sdk>=0.4.1` - Verify it's listed in your `requirements.txt` or `pyproject.toml` ### Network errors - Check your internet connection - Verify API host is reachable: `https://proxy.opinion.trade:8443` - Check if Opinion.trade API is operational ## Resources - [Opinion.trade Documentation](https://docs.opinion.trade/) - [Opinion.trade SDK](https://github.com/opinion-labs/opinion-clob-sdk) - [BNB Chain](https://www.bnbchain.org/) - [Model Context Protocol](https://modelcontextprotocol.io/) ## License MIT License - See LICENSE file for details ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Disclaimer This is an unofficial MCP server for Opinion.trade. Use at your own risk. Always verify transactions before signing. The authors are not responsible for any losses incurred through the use of this software. --- **Version**: 0.1.0 **Status**: Beta **Chain**: BNB Chain (Chain ID: 56)