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)

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)

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 .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:

# 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:

{
  "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:

{
  "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

# 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_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
• Opinion.trade SDK
• BNB Chain
• Model Context Protocol

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)