Provides tools for interacting with Opinion.trade prediction markets on BNB Chain, including market data access, order placement, position management, and trading operations with EIP712 signing support
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Opinion.trade MCP Server show me my current positions and P&L"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) server for Opinion.trade - a decentralized prediction markets platform on BNB Chain.
Read-Only Mode: Market data access with API key only
Trading Mode: Full trading capabilities with private key for EIP712 signing
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
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)
Related MCP server: predictfun-mcp
Python 3.10 or higher
Opinion.trade API key (Get one here)
# Clone or navigate to the directory
cd mcp-opinion-trade
# Install in development mode
pip install -e .cp .env.example .envMinimum configuration (read-only mode):
OPINION_API_KEY=your_api_key_hereFull 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 testnetAdd 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"
}
}
}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 toolUser: 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 toolNever commit your .env file to version control
Store API keys securely using environment variables
Rotate API keys periodically
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)
Use .env files for local development
Use secure secret management for production
Verify you're on the correct network (mainnet vs testnet)
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)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
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)
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
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=mcp_opinion --cov-report=term-missing# Format code
black src/
# Lint code
ruff check src/Ensure OPINION_API_KEY is set in .env
Verify .env file is in the project root directory
Check that python-dotenv is installed
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
Install the SDK: pip install opinion-clob-sdk>=0.4.1
Verify it's listed in your requirements.txt or pyproject.toml
Check your internet connection
Verify API host is reachable: https://proxy.opinion.trade:8443
Check if Opinion.trade API is operational
MIT License - See LICENSE file for details
Contributions are welcome! Please feel free to submit a Pull Request.
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)
Get detailed information about a specific market by ID
| Name | Required | Description | Default |
|---|---|---|---|
| market_id | Yes | Market ID to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves information, implying a read-only operation, but lacks details on error handling (e.g., invalid IDs), rate limits, authentication needs, or response format. This is a significant gap for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy to parse quickly, with zero wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes (e.g., market name, status, tokens), potential errors, or behavioral traits like idempotency. For a tool with no structured data beyond the input schema, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'market_id' fully documented in the schema. The description adds no additional parameter semantics beyond implying retrieval by ID, so it meets the baseline of 3 where the schema does the heavy lifting without extra value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get detailed information') and target resource ('about a specific market by ID'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'get_markets' (which likely lists multiple markets) or 'get_orderbook' (which focuses on order data), missing explicit sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a valid market ID, or compare it to siblings like 'get_markets' for listing markets or 'search_markets' for finding markets by criteria, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List prediction markets with filtering options (limit, offset, status)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum markets to return (1-500) | |
| offset | No | Offset for pagination | |
| status | No | Filter by status (active/closed/all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions filtering options but fails to describe key behaviors: whether this is a read-only operation, how pagination works with limit/offset, what the default status filter is, or what the return format looks like. This is inadequate for a tool with three parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List prediction markets') followed by the key features ('with filtering options'). Every word earns its place with zero wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three parameters, no output schema, no annotations), the description is incomplete. It doesn't explain the return format, pagination behavior, or how filtering interacts with sibling tools. For a list operation with filtering, more context is needed to help the agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds no additional meaning beyond what's in the schema—it merely lists the parameter names without explaining their relationships or usage context. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List prediction markets') and resource ('prediction markets'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'search_markets' or 'get_market_details', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_markets' or 'get_market_details'. It mentions filtering options but doesn't explain when filtering by status or pagination is appropriate, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get order book (bids/asks) for a token
| Name | Required | Description | Default |
|---|---|---|---|
| token_id | Yes | Token ID for orderbook | |
| depth | No | Number of price levels (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get order book (bids/asks) for a token', which implies a read-only operation, but doesn't specify any behavioral traits such as rate limits, authentication requirements, error handling, or what the output format looks like (e.g., structure of bids/asks). For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly. Every word earns its place by conveying essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (read operation with 2 parameters) and the absence of both annotations and an output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., format of order book data), potential errors, or any behavioral constraints. For a tool that likely returns structured financial data, this lack of context makes it harder for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with both parameters ('token_id' and 'depth') fully documented in the input schema. The description adds no additional meaning beyond what the schema provides—it doesn't explain parameter interactions, usage examples, or edge cases. With high schema coverage, the baseline is 3, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'order book (bids/asks) for a token', which specifies what the tool does. It distinguishes from siblings like 'get_market_details' or 'get_price_history' by focusing specifically on order book data rather than general market information or historical prices. However, it doesn't explicitly differentiate from all siblings (e.g., 'get_markets' might also provide order book data), so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, context for usage, or comparisons to sibling tools like 'get_market_details' or 'get_token_price'. The agent must infer usage based on the tool name and description alone, which is insufficient for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get historical price data (OHLCV) for a token
| Name | Required | Description | Default |
|---|---|---|---|
| token_id | Yes | Token ID for price history | |
| timeframe | No | Timeframe for OHLCV data | 1h |
| limit | No | Number of data points (1-1000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a read operation ('Get'), but doesn't mention rate limits, authentication needs, data freshness, or error handling. For a data-fetching tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by specifying the data type (OHLCV) and resource (token), making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of fetching historical financial data, no annotations, and no output schema, the description is incomplete. It doesn't explain the return format (e.g., array of OHLCV objects), pagination, or data limitations, leaving gaps that could hinder an AI agent's effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters (token_id, timeframe, limit) with descriptions, enums, and constraints. The description adds no additional parameter semantics beyond implying OHLCV data structure, aligning with the baseline score when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('historical price data (OHLCV) for a token'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_token_price' (which might provide current price) or 'get_market_details' (which might offer broader market info), missing full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_token_price' for current prices or 'get_markets' for market listings. There's no mention of prerequisites, context, or exclusions, leaving usage entirely implied from the tool name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current price for a specific token/outcome
| Name | Required | Description | Default |
|---|---|---|---|
| token_id | Yes | Token ID for price lookup |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool gets 'current price' but doesn't explain what 'current' means (e.g., real-time, delayed, cached), whether it requires authentication, rate limits, error conditions, or the format of the returned price. This leaves significant gaps for a tool that likely interacts with external data sources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of price data (which can vary by source, timing, and format), no annotations, and no output schema, the description is insufficient. It doesn't cover behavioral aspects like data freshness, potential errors, or return structure, leaving the agent under-informed for reliable use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'token_id' clearly documented. The description adds no additional parameter details beyond implying it's for 'a specific token/outcome,' which aligns with the schema but doesn't provide extra semantic value. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get current price') and the resource ('for a specific token/outcome'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'get_price_history' or 'get_market_details' which might also provide price-related information, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_price_history' (for historical data) or 'get_market_details' (which might include price among other details). It lacks explicit when/when-not instructions or named alternatives, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search markets by keyword or phrase
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| limit | No | Maximum results (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the search functionality but does not disclose behavioral traits such as permissions needed, rate limits, pagination, or what the output format looks like (e.g., list of market objects). This is inadequate for a search tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It is appropriately sized and front-loaded, clearly stating the tool's purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., search scope, result format) and does not compensate for the missing structured data, making it insufficient for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters ('query' and 'limit'). The description adds no additional meaning beyond what the schema provides, such as examples of search queries or context for the limit. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and target resource ('markets'), with a specific method ('by keyword or phrase'). It distinguishes from siblings like 'get_markets' (likely unfiltered listing) and 'get_market_details' (specific lookup), though not explicitly. However, it lacks full sibling differentiation, such as not mentioning 'get_markets' as a broader alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'get_markets' or 'get_market_details'. The description implies usage for keyword-based searches but does not specify contexts, exclusions, or prerequisites, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_market_detailsget_marketsget_orderbookget_price_historyget_token_pricesearch_marketsScored across 6 tools
Each tool has a clearly distinct purpose with no ambiguity: get_market_details focuses on a specific market, get_markets lists markets, get_orderbook shows bids/asks, get_price_history provides historical data, get_token_price gives current price, and search_markets enables keyword search. The descriptions reinforce these distinct roles, making misselection unlikely.
All tools follow a consistent verb_noun pattern using snake_case (e.g., get_market_details, get_orderbook, search_markets). The naming is predictable and readable throughout the set, with no deviations in style or convention.
With 6 tools, the count is well-scoped for a prediction market server, covering core functionalities like listing, searching, and retrieving market and price data. Each tool earns its place without feeling excessive or insufficient for the domain.
The tool surface provides strong coverage for querying and analyzing prediction markets, including market details, listings, order books, and price data. A minor gap exists in the lack of tools for creating or trading on markets (e.g., place_order, create_market), but agents can still perform comprehensive read-only operations effectively.
Read-only Polymarket sports and esports data: wallet grades on settled P&L, large trades, markets.
Live prediction markets: Polymarket + Kalshi prices, odds, order books. Pay-per-call USDC, no key.
Keyless prediction-market data across 12 venues plus paper-trading of crypto spot, futures, and PM.
Trade, orderbook, and volatility data for prediction markets and crypto derivatives.
