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 filtering
get_market_details - Get detailed market information
get_token_price - Current token/outcome prices
get_orderbook - Order book depth (bids/asks)
get_price_history - Historical OHLCV data
search_markets - Search markets by keyword

Trading Tools (7 - Requires private key)

place_order - Place limit/market orders with EIP712 signing
cancel_order - Cancel specific order
cancel_all_orders - Cancel all open orders
get_open_orders - List user's open orders
get_positions - Get positions with P&L
get_trade_history - Executed trades history
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

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)