Opinion.trade MCP Server
Model Context Protocol (MCP) server for 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)
get_markets- List prediction markets with filteringget_market_details- Get detailed market informationget_token_price- Current token/outcome pricesget_orderbook- Order book depth (bids/asks)get_price_history- Historical OHLCV datasearch_markets- Search markets by keyword
Trading Tools (7 - Requires private key)
place_order- Place limit/market orders with EIP712 signingcancel_order- Cancel specific ordercancel_all_orders- Cancel all open ordersget_open_orders- List user's open ordersget_positions- Get positions with P&Lget_trade_history- Executed trades historyget_balances- Account balances (available + locked)
Installation
Prerequisites
- Python 3.10 or higher
- Opinion.trade API key (Get one here)
Install from source
# Clone or navigate to the directory
cd mcp-opinion-trade
# Install in development mode
pip install -e .
Configuration
1. Create .env file
cp .env.example .env
2. Configure environment variables
Minimum configuration (read-only mode):
OPINION_API_KEY=your_api_key_here
Full configuration (trading mode):
# 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:
{
"mcpServers": {
"opinion-trade": {
"command": "python",
"args": ["-m", "mcp_opinion"],
"env": {
"OPINION_API_KEY": "your_api_key_here"
}
}
}
}
Or use the installed command:
{
"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
.envfile 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
.envfiles 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:
# 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_sdkfor 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:
{
"code": 0,
"msg": "success",
"result": {
"data": {...} // or "list": [...]
}
}
code: 0 for success, non-zero for errorsmsg: Human-readable messageresult: Contains eitherdata(single object) orlist(array)
Error Handling
The server provides detailed error messages:
{
"error": "Order placement failed: Insufficient balance",
"error_code": "INSUFFICIENT_BALANCE",
"status_code": 400,
"is_error": true
}
Common error codes:
VALIDATION_ERROR: Invalid input parametersAPI_ERROR: Opinion.trade API errorTRADING_DISABLED: Trading tools called without private keyINTERNAL_ERROR: Unexpected server error
Development
Running Tests
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=mcp_opinion --cov-report=term-missing
Code Formatting
# Format code
black src/
# Lint code
ruff check src/
Troubleshooting
"API key is required" error
- Ensure
OPINION_API_KEYis set in.env - Verify
.envfile is in the project root directory - Check that
python-dotenvis installed
"Trading tools not available" error
- Set
OPINION_PRIVATE_KEYin.envto 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.txtorpyproject.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
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)
