Opinion Builders Program

https://docs.opinion.trade/developer-guide
Admin
The Opinion Builders Program encourages researchers, routers, and developers to create tools and...
Tokens:101,156
Snippets:367
Trust Score:5.8
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install and Run Python Script (Bash)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Provides instructions to install the python-dotenv package and run a Python script. This is a common setup for applications that use environment variables.

```bash
# Install python-dotenv if not already installed
pip install python-dotenv

# Run the script
python my_first_app.py
```

--------------------------------

### Gnosis Safe Integration Example

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/architecture

This example shows how to configure private keys and multi-sig addresses for both EOA and Gnosis Safe setups. The private key is used for signing orders, while the multi-sig address represents the wallet holding the funds, ensuring secure transaction authorization.

```python
# EOA (externally owned account) setup
private_key_eoa = "0x..."        # Signs orders
multi_sig_addr_eoa = "0x..."     # Same as signer (EOA holds funds)

# Gnosis Safe setup
private_key_safe = "0x..."        # Safe owner key (signs orders)
multi_sig_addr_safe = "0x..."     # Safe contract address (holds funds)
```

--------------------------------

### Set up Python Virtual Environment for SDK - Bash

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/support/troubleshooting

Guides users on creating and activating a Python virtual environment to manage project dependencies and avoid conflicts, particularly when installing the Opinion CLOB SDK.

```bash
python3 -m venv venv
source venv/bin/activate
pip install opinion_clob_sdk
```

```bash
python3 -m venv fresh_env
source fresh_env/bin/activate
pip install opinion_clob_sdk
```

--------------------------------

### Subscribe to a Channel

Source: https://docs.opinion.trade/developer-guide/opinion-websocket/quickstart

Send a SUBSCRIBE message to receive real-time data for a specific market channel. The required market identifier depends on the market type (Binary or Categorical).

```APIDOC
## Subscribe to a Channel

### Description
Send a SUBSCRIBE message to receive real-time data for a specific market channel. The required market identifier depends on the market type (Binary or Categorical).

### Method
Send Message

### Endpoint
(Active WebSocket Connection)

### Parameters
#### Request Body
- **action** (string) - Required - Must be "SUBSCRIBE".
- **channel** (string) - Required - The identifier for the channel to subscribe to.
- **marketId** (integer) - Required for Binary markets - The ID of the binary market.
- **rootMarketId** (integer) - Required for Categorical markets - The ID of the root market for categorical markets.

### Request Example
**For Binary market:**
```json
{
  "action": "SUBSCRIBE",
  "channel": "{CHANNEL}",
  "marketId": {MARKET_ID}
}
```

**For Categorical market:**
```json
{
  "action": "SUBSCRIBE",
  "channel": "{CHANNEL}",
  "rootMarketId": {ROOT_MARKET_ID}
}
```
```

--------------------------------

### WebSocket Connection

Source: https://docs.opinion.trade/developer-guide/opinion-websocket/quickstart

Establish a WebSocket Secure (wss) connection to the Opinion Trade server. The API key is provided as a query parameter.

```APIDOC
## WebSocket Connection

### Description
Establish a WebSocket Secure (wss) connection to the Opinion Trade server. The API key is provided as a query parameter.

### Method
WSS Connection

### Endpoint
`wss://ws.opinion.trade`

### Parameters
#### Query Parameters
- **apikey** (string) - Required - Your unique API key for authentication.

### Request Example
`wss://ws.opinion.trade?apikey={API_KEY}`
```

--------------------------------

### Unsubscribe from a Channel

Source: https://docs.opinion.trade/developer-guide/opinion-websocket/quickstart

Send an UNSUBSCRIBE message with the same parameters used for subscribing to stop receiving data from a specific market channel.

```APIDOC
## Unsubscribe from a Channel

### Description
Send an UNSUBSCRIBE message with the same parameters used for subscribing to stop receiving data from a specific market channel.

### Method
Send Message

### Endpoint
(Active WebSocket Connection)

### Parameters
#### Request Body
- **action** (string) - Required - Must be "UNSUBSCRIBE".
- **channel** (string) - Required - The identifier for the channel to unsubscribe from.
- **marketId** (integer) - Required for Binary markets - The ID of the binary market.
- **rootMarketId** (integer) - Required for Categorical markets - The ID of the root market for categorical markets.

### Request Example
**For Binary market:**
```json
{
  "action": "UNSUBSCRIBE",
  "channel": "{CHANNEL}",
  "marketId": {MARKET_ID}
}
```

**For Categorical market:**
```json
{
  "action": "UNSUBSCRIBE",
  "channel": "{CHANNEL}",
  "rootMarketId": {ROOT_MARKET_ID}
}
```
```

--------------------------------

### Configuring RPC URL (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Provides examples of setting the `rpc_url` for communicating with the BNB Chain node. It shows both a public endpoint and an alternative provider.

```python
# Public RPC endpoints (development and testing)
rpc_url = 'https://bsc-dataseed.binance.org'
rpc_url = 'https://bsc.nodereal.io'
```

--------------------------------

### Install and Verify Opinion CLOB SDK

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/support/faq

Provides instructions to resolve 'ModuleNotFoundError: No module named 'opinion_clob_sdk'' by installing the SDK using pip. It also includes a verification command to ensure the SDK has been installed correctly and to check its version.

```bash
pip install opinion_clob_sdk

# Verify installation
python -c "import opinion_clob_sdk; print(opinion_clob_sdk.__version__)"
```

--------------------------------

### Maintain Connection (Heartbeat)

Source: https://docs.opinion.trade/developer-guide/opinion-websocket/quickstart

Periodically send a HEARTBEAT message to keep the WebSocket connection active. It is recommended to send this every 30 seconds.

```APIDOC
## Maintain Connection (Heartbeat)

### Description
Periodically send a HEARTBEAT message to keep the WebSocket connection active. It is recommended to send this every 30 seconds.

### Method
Send Message

### Endpoint
(Active WebSocket Connection)

### Request Body
```json
{
  "action": "HEARTBEAT"
}
```
```

--------------------------------

### Get Orderbook Example (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/models

Illustrates how to retrieve an orderbook for a given token and extract the best bid and ask prices and amounts. It also calculates the spread between them. This uses the get_orderbook() function.

```python
book = client.get_orderbook("token_yes").result.data

# Best bid (highest buy price)
best_bid = book.bids[0] if book.bids else None
print(f"Best bid: ${best_bid['price']} x {best_bid['amount']}")

# Best ask (lowest sell price)
best_ask = book.asks[0] if book.asks else None
print(f"Best ask: ${best_ask['price']} x {best_ask['amount']}")

# Spread
if best_bid and best_ask:
    spread = float(best_ask['price']) - float(best_bid['price'])
    print(f"Spread: ${spread:.4f}")
```

--------------------------------

### Initialize Opinion CLOB SDK Client (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/configuration

Demonstrates the initialization of the Opinion CLOB SDK `Client` class with various configuration parameters. This includes essential parameters like host, API key, chain ID, RPC URL, private key, and multi-sig address, as well as optional parameters for contract addresses and cache settings. Proper configuration is crucial for connecting to the Opinion trading platform.

```python
from opinion_clob_sdk import Client

client = Client(
    host='https://proxy.opinion.trade:8443',
    apikey='your_api_key',
    chain_id=56,
    rpc_url='your_rpc_url',
    private_key='0x...', 
    multi_sig_addr='0x...', 
    conditional_tokens_addr='0xAD1a38cEc043e70E83a3eC30443dB285ED10D774',
    multisend_addr='0x998739BFdAAdde7C933B942a68053933098f9EDa',
    enable_trading_check_interval=3600,
    quote_tokens_cache_ttl=3600,
    market_cache_ttl=300
)
```

--------------------------------

### Example Price History Response - JSON

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/overview

A sample JSON response for the 'Get daily price history' endpoint. It contains a 'history' array, where each element represents a time point ('t') with its corresponding price ('p').

```json
{
  "code": 0,
  "msg": "success",
  "result": {
    "history": [
      {"t": 1733184000, "p": "0.58"},
      {"t": 1733270400, "p": "0.62"},
      {"t": 1733356800, "p": "0.65"}
    ]
  }
}
```

--------------------------------

### Example Orderbook Response - JSON

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/overview

A sample JSON response for the 'Get orderbook for a token' endpoint. It provides details about the market and token ID, along with arrays of 'bids' and 'asks', each containing price and size information.

```json
{
  "code": 0,
  "msg": "success",
  "result": {
    "market": "0xabc...def",
    "tokenId": "0x1234...5678",
    "timestamp": 1733312400000,
    "bids": [
      {"price": "0.64", "size": "5000.00"},
      {"price": "0.63", "size": "12000.00"}
    ],
    "asks": [
      {"price": "0.66", "size": "3000.00"},
      {"price": "0.67", "size": "8000.00"}
    ]
  }
}
```

--------------------------------

### Example Latest Price Response - JSON

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/overview

A sample JSON response for the 'Get latest price for a token' endpoint. It details the token ID, current price, side of the last trade, size of the last trade, and the timestamp of the trade.

```json
{
  "code": 0,
  "msg": "success", 
  "result": {
    "tokenId": "0x1234...5678",
    "price": "0.65",
    "side": "BUY",
    "size": "1000.00",
    "timestamp": 1733312400000
  }
}
```

--------------------------------

### Format Correct Private Key for Web3

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Illustrates common mistakes and the correct format for private keys when initializing Web3 or Opinion CLOB SDK clients. It emphasizes the need for the '0x' prefix and valid hexadecimal characters.

```python
# Correct format
private_key = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
```

--------------------------------

### Example Market Data Response - JSON

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/overview

A sample JSON response for the 'Get all active markets' endpoint. It includes the total number of markets and a list of market objects, each containing details like market ID, title, status, and trading volumes.

```json
{
  "code": 0,
  "msg": "success",
  "result": {
    "total": 150,
    "list": [
      {
        "marketId": 123,
        "marketTitle": "Will BTC reach $100k by end of 2025?",
        "status": 2,
        "statusEnum": "Activated",
        "yesTokenId": "0x1234...5678",
        "noTokenId": "0x8765...4321",
        "volume": "1500000.00",
        "volume24h": "125000.00"
      }
    ]
  }
}
```

--------------------------------

### Minimal Client Initialization (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Demonstrates the basic setup of the Opinion Trade client with essential configuration parameters. This includes the API endpoint, authentication key, chain ID, RPC URL, and wallet details.

```python
from opinion_clob_sdk import Client

client = Client(
    host='https://proxy.opinion.trade:8443',
    apikey='your_api_key_here',
    chain_id=56,
    rpc_url='https://bsc-dataseed.binance.org',
    private_key='0x...', 
    multi_sig_addr='0x...'
)
```

--------------------------------

### Get Orderbook (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Fetches the orderbook, including bids and asks, for a specified token ID. The function requires a valid token ID and returns API response data. The example shows how to print the top 5 bids and asks.

```python
response = client.get_orderbook(token_id="token_yes")

if response.errno == 0:
    book = response.result.data
    print("Bids (buy orders):")
    for bid in book.bids[:5]:  # Top 5
        print(f"  Price: {bid.price}, Size: {bid.size}")

    print("Asks (sell orders):")
    for ask in book.asks[:5]:
        print(f"  Price: {ask.price}, Size: {ask.size}")
```

--------------------------------

### Place a Buy Order (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Demonstrates how to place a buy order for a 'No' token on the Opinion Trade platform. It requires enabling trading first and specifies order details like market ID, token ID, side, type, price, and amount.

```python
from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import LIMIT_ORDER

# Enable trading (required once before placing orders)
client.enable_trading()

# Place a buy order of "No" token
order_data = PlaceOrderDataInput(
    marketId=813,
    tokenId='33095770954068818933468604332582424490740136703838404213332258128147961949614',
    side=OrderSide.BUY,
    orderType=LIMIT_ORDER,
    price='0.55',
    makerAmountInQuoteToken=10  # 10 USDT
)

result = client.place_order(order_data)
print(f"Order placed: {result}")
```

--------------------------------

### Verify Opinion CLOB SDK Installation via Command Line

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/installation

A concise command-line command to quickly verify the Opinion CLOB SDK installation by checking its version.

```bash
python -c "import opinion_clob_sdk; print('✓ Installed:', opinion_clob_sdk.__version__)"
```

--------------------------------

### Get Price History (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Fetches historical price data in candlestick format (OHLCV) for a specific token. It allows filtering by time interval and a custom start and end timestamp. The response contains a list of candle data objects.

```python
import time

# Get last 24 hours of hourly data
end_time = int(time.time())
start_time = end_time - (24 * 3600)  # 24 hours ago

response = client.get_price_history(
    token_id="token_yes",
    interval="1h",
    start_at=start_time,
    end_at=end_time
)

if response.errno == 0:
    candles = response.result.data
    for candle in candles:
        print(f"Time: {candle.timestamp}, Price: {candle.close}")
```

--------------------------------

### Maintain Connection with HEARTBEAT Message

Source: https://docs.opinion.trade/developer-guide/opinion-websocket/quickstart

To prevent the WebSocket connection from timing out, regular HEARTBEAT messages must be sent. This example demonstrates the JSON payload required for a HEARTBEAT action. It is recommended to send this message periodically, for instance, every 30 seconds.

```json
{"action":"HEARTBEAT"}
```

--------------------------------

### Smart Contract Operations: Split, Merge, Redeem (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Provides examples for interacting with smart contracts on the Opinion Trade platform. This includes splitting quote tokens into outcome tokens, merging outcome tokens back into quote tokens, and redeeming winnings after a market has resolved.

```python
# Split USDT into outcome tokens
tx_hash, receipt, event = client.split(
    market_id=813,
    amount=1000000000000000000  # 1 USDT (18 decimals for USDT)
)

# Merge outcome tokens back to USDT
tx_hash, receipt, event = client.merge(
    market_id=813,
    amount=1000000000000000000
)

# Redeem winnings after market resolves
tx_hash, receipt, event = client.redeem(market_id=813)
```

--------------------------------

### Client Initialization API

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Demonstrates the basic and minimal configuration for initializing the Opinion Trade Client with essential parameters.

```APIDOC
## Client Initialization

### Description
Initializes the `Client` class, which serves as the primary interface for interacting with the Opinion prediction market infrastructure. Accurate configuration is crucial for operational capability and security.

### Method
Initialization (Constructor)

### Endpoint
N/A (Client-side initialization)

### Parameters
#### Required Parameters
- **host** (str) - Required - CLOB API endpoint URL for HTTP communication. Default Production Value: `https://proxy.opinion.trade:8443`.
- **apikey** (str) - Required - Bearer token for API authentication and authorization. Obtain from Opinion Labs at support@opinion.trade.
- **chain_id** (int) - Required - The blockchain network identifier. Supported Value: `56` (BNB Chain Mainnet).
- **rpc_url** (str) - Required - JSON-RPC endpoint URL for BNB Chain node communication. Example: `https://bsc-dataseed.binance.org`.
- **private_key** (str) - Required - secp256k1 private key for ECDSA signature generation. Format: 64-character hexadecimal string with `0x` prefix.
- **multi_sig_addr** (str) - Required - Ethereum address (checksummed format) holding USDT collateral and outcome tokens (Gnosis Safe address).

#### Optional Parameters
- **conditional_tokens_addr** (Optional[str]) - Optional - The ConditionalTokens smart contract address. Defaults to `0xAD1a38cEc043e70E83a3eC30443dB285ED10D774` on BNB Chain.
- **multisend_addr** (Optional[str]) - Optional - The Gnosis Safe MultiSend contract address. Defaults to `0x998739BFdAAdde7C933B942a68053933098f9EDa` on BNB Chain.
- **market_cache_ttl_seconds** (int) - Optional - Time-to-live for cached market data in seconds. Defaults to `60`.
- **quote_token_cache_ttl_seconds** (int) - Optional - Time-to-live for cached quote token information in seconds. Defaults to `3600`.

### Request Example
```python
from opinion_clob_sdk import Client

client = Client(
    host='https://proxy.opinion.trade:8443',
    apikey='your_api_key_here',
    chain_id=56,
    rpc_url='https://bsc-dataseed.binance.org',
    private_key='0x...', # Replace with your actual private key
    multi_sig_addr='0x8F58a1ab...' # Replace with your actual multi-sig address
)
```

### Response
#### Success Response (Initialization)
- **Client Object** (object) - An initialized `Client` instance ready for use.

#### Response Example
```python
# Upon successful initialization, 'client' is an instance of the Client class.
print(type(client))
# Output: <class 'opinion_clob_sdk.client.Client'>
```
```

--------------------------------

### Python: Place SELL order using makerAmountInBaseToken

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/precision

Shows an example of creating a `PlaceOrderDataInput` for a SELL order, specifying the exact number of outcome tokens to sell using `makerAmountInBaseToken`. The SDK internally handles the conversion to Wei.

```python
from opinion_clob_sdk.chain.py_order_utils.model.order import PlaceOrderDataInput
from opinion_clob_sdk.chain.py_order_utils.model.sides import OrderSide
from opinion_clob_sdk.chain.py_order_utils.model.order_type import LIMIT_ORDER

order = PlaceOrderDataInput(
    marketId=813,
    tokenId='_____',
    side=OrderSide.SELL,
    orderType=LIMIT_ORDER,
    price='0.75',
    makerAmountInBaseToken=100  # Token amount (decimal, not Wei)
)
```

--------------------------------

### Market Data Endpoint Example

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/overview

Example of how to authenticate and request market data from the Opinion Trade API using an API key.

```APIDOC
## GET /openapi/market

### Description
Retrieves market data from the Opinion Trade API.

### Method
GET

### Endpoint
https://proxy.opinion.trade:8443/openapi/market

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET "https://proxy.opinion.trade:8443/openapi/market" \
  -H "apikey: your_api_key" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success, non-zero for error.
- **msg** (string) - Human-readable message.
- **result** (object) - Response data (varies by endpoint).

#### Response Example
```json
{
  "code": 0,
  "msg": "success",
  "result": { ... } 
}
```
```

--------------------------------

### Set Up .env File for Opinion CLOB SDK

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Configuration file to store API credentials and connection details for the Opinion CLOB SDK. It requires API Key, RPC URL, Private Key, Multi-sig Address, Host, Chain ID, and contract addresses for Conditional Tokens and Multi-send.

```bash
# .env file
API_KEY=your_api_key_here
RPC_URL=https://bsc-dataseed.binance.org
PRIVATE_KEY=0x1234567890abcdef...
MULTI_SIG_ADDRESS=0xYourWalletAddress...
H HOST=https://proxy.opinion.trade:8443
CHAIN_ID=56
CONDITIONAL_TOKEN_ADDR=0xAD1a38cEc043e70E83a3eC30443dB285ED10D774
MULTISEND_ADDR=0x998739BFdAAdde7C933B942a68053933098f9EDa
```

--------------------------------

### Get Specific Market Details using Opinion CLOB SDK (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Fetches detailed information for a specific market using its ID. It retrieves the market ID from a previously fetched list of markets and prints key details like title, question ID, quote token, and chain ID.

```python
# Get details for a specific market
market_id = markets[0].topic_id  # Use first market from above

market_detail = client.get_market(market_id)
if market_detail.errno == 0:
    market = market_detail.result.data
    print(f"\n✓ Market Details for #{market_id}:")
    print(f"  Title: {market.market_title}")
    print(f"  Question ID: {market.question_id}")
    print(f"  Quote Token: {market.quote_token}")
    print(f"  Chain ID: {market.chain_id}")
```

--------------------------------

### Install and Verify Opinion CLOB SDK - Python

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/support/troubleshooting

Instructions to install the Opinion CLOB SDK using pip and verify its installation by checking the installed version. This helps resolve 'ImportError: No module named 'opinion_clob_sdk''.

```bash
pip install opinion_clob_sdk
```

```bash
pip list | grep opinion
```

```python
import opinion_clob_sdk
print(opinion_clob_sdk.__version__)
```

--------------------------------

### Get Categorical Market Detail

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/market

Retrieves detailed information about a specific categorical market, including its child markets.

```APIDOC
## GET /market/categorical/{marketId}

### Description
Get detailed information about a specific categorical market including child markets.

### Method
GET

### Endpoint
`/market/categorical/{marketId}`

### Parameters
#### Path Parameters
- **marketId** (integer) - Required - Market ID

### Response
#### Success Response (200)
- **code** (integer) - Response code (0 for success)
- **msg** (string) - Response message
- **result** (object) - Response data, containing MarketDetailResponse
    - **data** (object) - Market data
        - **marketId** (integer) - Market ID
        - **marketTitle** (string) - Market title
        - **status** (integer) - Market status: 1=Created, 2=Activated, 3=Resolving, 4=Resolved, 5=Failed, 6=Deleted
        - **statusEnum** (string) - Human-readable status
        - **marketType** (integer) - Market type: 0=Binary, 1=Categorical
        - **childMarkets** (array) - Child markets (for categorical markets)
            - **marketId** (integer)
            - **marketTitle** (string)
            - **status** (integer)
            - **statusEnum** (string)
            - **yesLabel** (string)
            - **noLabel** (string)
            - **rules** (string)
            - **yesTokenId** (string)
            - **noTokenId** (string)
            - **conditionId** (string)
            - **resultTokenId** (string)
            - **volume** (string)
            - **quoteToken** (string)
            - **chainId** (string)
            - **questionId** (string)
            - **createdAt** (integer)
            - **cutoffAt** (integer)
            - **resolvedAt** (integer)
        - **yesLabel** (string) - Yes outcome label
        - **noLabel** (string) - No outcome label
        - **rules** (string) - Market rules
        - **yesTokenId** (string) - Yes outcome token ID
        - **noTokenId** (string) - No outcome token ID
        - **conditionId** (string) - Condition ID
        - **resultTokenId** (string) - Result token ID (after resolution)
        - **volume** (string) - Total trading volume
        - **volume24h** (string) - 24-hour trading volume
        - **volume7d** (string) - 7-day trading volume
        - **quoteToken** (string) - Quote token address
        - **chainId** (string) - Chain ID
        - **questionId** (string) - Question ID
        - **incentiveFactor** (object) - Incentive factor (masked as empty object)
        - **createdAt** (integer) - Creation timestamp
        - **cutoffAt** (integer) - Cutoff timestamp
        - **resolvedAt** (integer) - Resolution timestamp

#### Error Response (400)
- **code** (integer) - Response code
- **msg** (string) - Error message

### Request Example
(No request body for GET requests)

### Response Example
```json
{
  "code": 0,
  "msg": "success",
  "result": {
    "data": {
      "marketId": 123,
      "marketTitle": "Example Categorical Market",
      "status": 2,
      "statusEnum": "Activated",
      "marketType": 1,
      "childMarkets": [
        {
          "marketId": 124,
          "marketTitle": "Child Market A",
          "status": 2,
          "statusEnum": "Activated",
          "yesLabel": "Option A",
          "noLabel": "Option B",
          "rules": "Rules for Child Market A",
          "yesTokenId": "0xabc",
          "noTokenId": "0xdef",
          "conditionId": "cond1",
          "resultTokenId": null,
          "volume": "1000",
          "quoteToken": "0xquote",
          "chainId": "1",
          "questionId": "q1",
          "createdAt": 1678886400,
          "cutoffAt": 1678972800,
          "resolvedAt": null
        }
      ],
      "yesLabel": "Category 1",
      "noLabel": "Category 2",
      "rules": "Rules for the main market",
      "yesTokenId": "0xghi",
      "noTokenId": "0xjkl",
      "conditionId": "mainCond",
      "resultTokenId": null,
      "volume": "5000",
      "volume24h": "1000",
      "volume7d": "3000",
      "quoteToken": "0xquote",
      "chainId": "1",
      "questionId": "mainQ",
      "incentiveFactor": {},
      "createdAt": 1678800000,
      "cutoffAt": 1680000000,
      "resolvedAt": null
    }
  }
}
```
```

--------------------------------

### Get Binary Market Detail

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/market

Retrieves detailed information about a specific binary market using its unique ID.

```APIDOC
## GET /market/{marketId}

### Description
Get detailed information about a specific binary market.

### Method
GET

### Endpoint
/market/{marketId}

### Parameters
#### Path Parameters
- **marketId** (integer) - Required - Market ID

### Response
#### Success Response (200)
- **code** (integer) - Response code (0 for success)
- **msg** (string) - Response message
- **result** (object) - Response data
  - **data** (object) - Market data details
    - **marketId** (integer) - Market ID
    - **marketTitle** (string) - Market title
    - **status** (integer) - Market status: 1=Created, 2=Activated, 3=Resolving, 4=Resolved, 5=Failed, 6=Deleted
    - **statusEnum** (string) - Human-readable status
    - **marketType** (integer) - Market type: 0=Binary, 1=Categorical
    - **childMarkets** (array) - Child markets (for categorical markets)
    - **yesLabel** (string) - Yes outcome label
    - **noLabel** (string) - No outcome label
    - **rules** (string) - Market rules
    - **yesTokenId** (string) - Yes outcome token ID
    - **noTokenId** (string) - No outcome token ID
    - **conditionId** (string) - Condition ID
    - **resultTokenId** (string) - Result token ID (after resolution)
    - **volume** (string) - Total trading volume
    - **volume24h** (string) - 24-hour trading volume
    - **volume7d** (string) - 7-day trading volume
    - **quoteToken** (string) - Quote token address
    - **chainId** (string) - Chain ID
    - **questionId** (string) - Question ID
    - **incentiveFactor** (object) - Incentive factor (masked as empty object)
    - **createdAt** (integer) - Creation timestamp
    - **cutoffAt** (integer) - Cutoff timestamp
    - **resolvedAt** (integer) - Resolution timestamp

#### Response Example
```json
{
  "code": 0,
  "msg": "Success",
  "result": {
    "data": {
      "marketId": 123,
      "marketTitle": "Will BTC reach $50,000 tomorrow?",
      "status": 2,
      "statusEnum": "Activated",
      "marketType": 0,
      "childMarkets": [],
      "yesLabel": "Yes",
      "noLabel": "No",
      "rules": "Market resolves based on CoinGecko API price at midnight UTC.",
      "yesTokenId": "0x123...",
      "noTokenId": "0x456...",
      "conditionId": "0xabc...",
      "resultTokenId": null,
      "volume": "1000000",
      "volume24h": "50000",
      "volume7d": "200000",
      "quoteToken": "0xdef...",
      "chainId": "1",
      "questionId": "0xghi...",
      "incentiveFactor": {},
      "createdAt": 1678886400,
      "cutoffAt": 1678972800,
      "resolvedAt": null
    }
  }
}
```

#### Error Response (400)
- **code** (integer) - Response code
- **msg** (string) - Error message

#### Response Example
```json
{
  "code": 10001,
  "msg": "Invalid market ID"
}
```
```

--------------------------------

### Configure Caching Strategy for Opinion CLOB SDK

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Demonstrates how to configure caching strategies for the Opinion CLOB SDK client to optimize performance. It shows examples for aggressive caching for read-heavy workloads and minimal caching for trading bots.

```python
# Aggressive caching for read-heavy workloads
client = Client(
    market_cache_ttl_seconds=300,      # 5 minutes
    quote_token_cache_ttl_seconds=3600 # 1 hour
)

# Minimal caching for trading bots
client = Client(
    market_cache_ttl_seconds=10,       # 10 seconds
    quote_token_cache_ttl_seconds=60   # 1 minute
)
```

--------------------------------

### GET /market

Source: https://docs.opinion.trade/developer-guide/opinion-open-api/market

Retrieves a paginated list of all available markets, supporting filtering by status, type, sorting, and chain ID.

```APIDOC
## GET /market

### Description
Get a paginated list of all markets (categorical and binary).

### Method
GET

### Endpoint
/market

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (defaults to 1, minimum 1).
- **limit** (integer) - Optional - Number of items per page (defaults to 10, maximum 20).
- **status** (string) - Optional - Market status filter (e.g., "activated", "resolved").
- **marketType** (integer) - Optional - Market type filter: 0=Binary, 1=Categorical, 2=All (defaults to 0).
- **sortBy** (integer) - Optional - Sort order: 1=new, 2=ending soon, 3=volume desc, 4=volume asc, 5=volume24h desc, 6=volume24h asc, 7=volume7d desc, 8=volume7d asc.
- **chainId** (string) - Optional - Chain ID filter.

### Request Example
```json
{
  "example": "No request body for GET requests"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Response code (0 for success).
- **msg** (string) - Response message.
- **result** (object) - Response data.
  - **total** (integer) - Total number of markets.
  - **list** (array) - List of market data.
    - **marketId** (integer) - Market ID.
    - **marketTitle** (string) - Market title.
    - **status** (integer) - Market status: 1=Created, 2=Activated, 3=Resolving, 4=Resolved, 5=Failed, 6=Deleted.
    - **statusEnum** (string) - Human-readable status.
    - **marketType** (integer) - Market type: 0=Binary, 1=Categorical.
    - **childMarkets** (array) - Child markets (for categorical markets).
    - **yesLabel** (string) - Yes outcome label.
    - **noLabel** (string) - No outcome label.
    - **rules** (string) - Market rules.
    - **yesTokenId** (string) - Yes outcome token ID.
    - **noTokenId** (string) - No outcome token ID.
    - **conditionId** (string) - Condition ID.
    - **resultTokenId** (string) - Result token ID (after resolution).
    - **volume** (string) - Total trading volume.
    - **volume24h** (string) - 24-hour trading volume.
    - **volume7d** (string) - 7-day trading volume.
    - **quoteToken** (string) - Quote token address.
    - **chainId** (string) - Chain ID.
    - **questionId** (string) - Question ID.
    - **incentiveFactor** (object) - Incentive factor (masked as empty object).
    - **createdAt** (integer) - Creation timestamp.
    - **cutoffAt** (integer) - Cutoff timestamp.
    - **resolvedAt** (integer) - Resolution timestamp.

#### Response Example
```json
{
  "code": 0,
  "msg": "OK",
  "result": {
    "total": 100,
    "list": [
      {
        "marketId": 1,
        "marketTitle": "Will BTC reach $50,000 by December 31st, 2023?",
        "status": 2,
        "statusEnum": "Activated",
        "marketType": 0,
        "yesLabel": "Yes",
        "noLabel": "No",
        "rules": "",
        "yesTokenId": "0x123...",
        "noTokenId": "0x456...",
        "conditionId": "0x789...",
        "resultTokenId": null,
        "volume": "1000000000000000000",
        "volume24h": "50000000000000000",
        "volume7d": "200000000000000000",
        "quoteToken": "0xabc...",
        "chainId": "eip155:1",
        "questionId": "0xdef...",
        "incentiveFactor": {},
        "createdAt": 1678886400,
        "cutoffAt": 1704067200,
        "resolvedAt": null
      }
    ]
  }
}
```

#### Error Response (400)
- **code** (integer) - Error code.
- **msg** (string) - Error message.

#### Error Example
```json
{
  "code": 400,
  "msg": "Invalid parameter: page must be at least 1"
}
```
```

--------------------------------

### Optimize Connection Pooling with Opinion CLOB SDK

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Explains the importance of connection pooling for long-running applications when using the Opinion CLOB SDK. It shows the efficient approach of creating a single client instance versus repeatedly creating new ones.

```python
# ✅ Good
client = Client(...)
for i in range(1000):
    markets = client.get_markets()

# ❌ Bad (creates 1000 connections)
for i in range(1000):
    client = Client(...)
    markets = client.get_markets()
```

--------------------------------

### Secure API Key Handling (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/core-concepts/client

Shows a secure method for retrieving the API key using environment variables. This approach avoids hardcoding sensitive credentials directly in the codebase, enhancing security.

```python
import os
from dotenv import load_dotenv

load_dotenv()
apikey = os.getenv('API_KEY')  # Never hardcode!
```

--------------------------------

### GET /latest_price/{token_id}

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Retrieves the current/latest price for a given token.

```APIDOC
## GET /latest_price/{token_id}

### Description
Get the current/latest price for a token.

### Method
GET

### Endpoint
/latest_price/{token_id}

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The ID of the token.

### Response
#### Success Response (200)
- **result.data** (object) - An object containing the latest price and timestamp. Includes `price` and `timestamp` properties.

#### Response Example
```json
{
  "errno": 0,
  "result": {
    "data": {
      "price": "1.05",
      "timestamp": 1678886400
    }
  }
}
```
```

--------------------------------

### Manage Positions and Trades (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Shows how to retrieve user-specific financial data, including account balances, current open positions, and historical trade data for a given market. This is essential for tracking investment performance.

```python
# Get balances
balances = client.get_my_balances()

# Get positions
positions = client.get_my_positions(limit=20)

# Get trade history
trades = client.get_my_trades(market_id=813)
```

--------------------------------

### Get My Balances API

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Retrieves the current token balances for the authenticated user.

```APIDOC
## GET /get_my_balances

### Description
Get user's token balances.

### Method
GET

### Endpoint
/get_my_balances

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **result.data.balances** (List[dict]) - A list of balance objects, where each object contains details for a specific token, including `quote_token`, `available_balance`, `frozen_balance`, and `total_balance`.

#### Response Example
```json
{
  "errno": 0,
  "result": {
    "data": {
      "balances": [
        {
          "quote_token": "BTC",
          "available_balance": "1.50000000",
          "frozen_balance": "0.00000000",
          "total_balance": "1.50000000"
        },
        {
          "quote_token": "USDT",
          "available_balance": "10000.00000000",
          "frozen_balance": "500.00000000",
          "total_balance": "10500.00000000"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Initialize SDK Client with Credentials

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/support/faq

Initialize the Opinion CLOB SDK client by providing your private key for signing transactions and your multi-sig address for asset management. These are crucial for authenticating with the Opinion CLOB.

```python
client = Client(
    private_key='0x...',      # Hot wallet private key (signs orders)
    multi_sig_addr='0x...'    # Cold wallet address (holds assets)
)
```

--------------------------------

### GET /fee_rates/{token_id}

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Retrieves the trading fee rates for a specific token.

```APIDOC
## GET /fee_rates/{token_id}

### Description
Get trading fee rates for a token.

### Method
GET

### Endpoint
/fee_rates/{token_id}

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The ID of the token.

### Response
#### Success Response (200)
- **result.data** (object) - An object containing the maker and taker fee rates. Includes `maker_fee` and `taker_fee` properties.

#### Response Example
```json
{
  "errno": 0,
  "result": {
    "data": {
      "maker_fee": "0.001",
      "taker_fee": "0.002"
    }
  }
}
```
```

--------------------------------

### Error Handling

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Details on custom exceptions and example error handling for API operations.

```APIDOC
### Error Handling

#### Exceptions
The SDK defines the following custom exceptions:

- `InvalidParamError`: Invalid method parameters.
- `OpenApiError`: API communication or response errors.
- `BalanceNotEnough`: Insufficient token balance for operation.
- `NoPositionsToRedeem`: No winning positions to redeem.
- `InsufficientGasBalance`: Not enough BNB for gas fees.

#### Example Error Handling
```python
try:
    result = client.place_order(order_data)
    if result.errno == 0:
        print("Success!")
    else:
        print(f"API Error: {result.errmsg}")

except InvalidParamError as e:
    print(f"Invalid parameter: {e}")
except OpenApiError as e:
    print(f"API error: {e}")
except BalanceNotEnough as e:
    print(f"Insufficient balance: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```
```

--------------------------------

### Initialize Opinion Trade Client and Fetch Active Markets (Python)

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/getting-started/quick-start

Initializes the Opinion Trade client using environment variables and fetches a list of currently activated markets. It handles potential errors during market fetching and displays market titles and IDs.

```python
from dotenv import load_dotenv
from opinion_clob_sdk.client import Client
from opinion_clob_sdk.topic_status_filter import TopicStatusFilter
import os

load_dotenv()

def main():
    client = Client(
        host='https://proxy.opinion.trade:8443',
        apikey=os.getenv('API_KEY'),
        chain_id=56,
        rpc_url=os.getenv('RPC_URL'),
        private_key=os.getenv('PRIVATE_KEY'),
        multi_sig_addr=os.getenv('MULTI_SIG_ADDRESS')
    )
    print("✓ Client initialized successfully!")

    markets_response = sdk.get_markets(
        status=TopicStatusFilter.ACTIVATED,
        limit=5
    )

    if markets_response.errno == 0:
        markets = markets_response.result.list
        print(f"\n✓ Found {len(markets)} active markets\n")

        for i, market in enumerate(markets, 1):
            print(f"{i}. {market.market_title}")
            print(f"   Market ID: {market.market_id}")
            print()

        if markets:
            first_market = markets[0]
            detail = sdk.get_categorical_market(market_id=first_market.market_id)

            if detail.errno == 0:
                m = detail.result.data
                print(f"✓ Details for '{m.market_title}':")
                print(f"  Status: {m.status}")
                print(f"  Question ID: {m.question_id}")
                print(f"  Quote Token: {m.quote_token}")
     else:
        print(f"Error fetching markets: {markets_response.errmsg}")

if __name__ == '__main__':
    main()

```

--------------------------------

### GET /orderbook/{token_id}

Source: https://docs.opinion.trade/developer-guide/opinion-clob-sdk/api-references/methods

Fetches the order book (bids and asks) for a specific token.

```APIDOC
## GET /orderbook/{token_id}

### Description
Get the order book (bids and asks) for a specific token.

### Method
GET

### Endpoint
/orderbook/{token_id}

### Parameters
#### Path Parameters
- **token_id** (string) - Required - The ID of the token for which to retrieve the order book (e.g., "token_yes", "token_123").

### Response
#### Success Response (200)
- **result.data** (object) - An object containing bid and ask orders. It includes `bids` and `asks` arrays, where each element has `price` and `size` properties.

#### Response Example
```json
{
  "errno": 0,
  "result": {
    "data": {
      "bids": [
        {
          "price": "1.0",
          "size": "10.0"
        }
      ],
      "asks": [
        {
          "price": "1.1",
          "size": "15.0"
        }
      ]
    }
  }
}
```

### Error Handling
- `InvalidParamError`: If `token_id` is missing.
- `OpenApiError`: If the API request fails.
```
Tokens:
Raw