Configuration

This guide covers how to configure the Opinion CLOB TypeScript SDK for different environments and use cases.

Client Configuration

The Client class accepts a configuration object during initialization:

example.ts

import { Client, CHAIN_ID_BNB_MAINNET, DEFAULT_API_HOST } from '@opinion-labs/opinion-clob-sdk';

const client = new Client({
  host: DEFAULT_API_HOST,
  apiKey: 'your_api_key',
  chainId: CHAIN_ID_BNB_MAINNET,  // 56
  rpcUrl: 'your_rpc_url',
  privateKey: '0x...' as `0x${string}`,
  multiSigAddress: '0x...' as `0x${string}`,
  conditionalTokensAddress: '0xAD1a38cEc043e70E83a3eC30443dB285ED10D774',
  multiSendAddress: '0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526',
  feeManagerAddress: '0xC9063Dc52dEEfb518E5b6634A6b8D624bc5d7c36',
  enableTradingCheckInterval: 3600,
  quoteTokensCacheTtl: 3600,
  marketCacheTtl: 300,
  proxyUrl: 'http://127.0.0.1:7890',  // Optional HTTP proxy
});

Required Parameters

host

Type: string Description: Opinion API host URL Default: No default (required)

import { DEFAULT_API_HOST } from '@opinion-labs/opinion-clob-sdk';
// DEFAULT_API_HOST = 'https://openapi.opinion.trade/openapi'
host: DEFAULT_API_HOST

apiKey

Type: string Description: API authentication key provided by Opinion Labs Default: No default (required)

How to obtain: fill out this short application form

apiKey: '________'

Security: Store API keys in environment variables, never in source code.

chainId

Type: number Description: Blockchain network chain ID Supported values:

56 - BNB Chain Mainnet (production)

import { CHAIN_ID_BNB_MAINNET } from '@opinion-labs/opinion-clob-sdk';
chainId: CHAIN_ID_BNB_MAINNET  // 56

rpcUrl

Type: string Description: Blockchain RPC endpoint URL Default: No default (required)

Common providers:

BNB Chain Mainnet: https://bsc-dataseed.binance.org
BNB Chain (Nodereal): https://bsc.nodereal.io

// Public RPC (rate limited)
rpcUrl: 'https://bsc-dataseed.binance.org'

// Private RPC (recommended for production)
rpcUrl: 'https://bsc.nodereal.io'

privateKey

Type: `0x${string}` Description: Private key for signing orders and transactions Format: 64-character hex string with 0x prefix

privateKey: '0x1234567890abcdef...' as `0x${string}`  // Must have 0x prefix

Critical Security:

Never commit private keys to version control
Use environment variables or secure key management systems
Ensure the associated address has BNB for gas fees
This is the signer address, may differ from multiSigAddress

multiSigAddress

Type: Address Description: Multi-signature wallet address (your assets/portfolio wallet) Format: Ethereum address (checksummed or lowercase)

multiSigAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' as `0x${string}`

Relationship to privateKey:

privateKey -> Signer address (signs orders/transactions)
multiSigAddress -> Assets address (holds funds/positions)
Can be the same address or different (e.g., hot wallet signs for cold wallet)

Where to find:

Check your Opinion platform "My Profile" section
Or use the wallet address where you hold USDT/positions

Optional Parameters

conditionalTokensAddress

Type: Address Description: ConditionalTokens contract address Default: 0xAD1a38cEc043e70E83a3eC30443dB285ED10D774 (BNB Chain mainnet) When to set: Only if using a custom deployment

multiSendAddress

Type: Address Description: Gnosis Safe MultiSend contract address Default: 0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526 When to set: Only if using a custom Gnosis Safe deployment

feeManagerAddress

Type: Address Description: Fee rate management contract address Default: 0xC9063Dc52dEEfb518E5b6634A6b8D624bc5d7c36 When to set: Only if using a custom deployment

enableTradingCheckInterval

Type: number Description: Cache duration (in seconds) for trading approval checks Default: 3600 (1 hour) Range: 0 to infinity

// Default: check approval status every hour
enableTradingCheckInterval: 3600

// Check every time (no caching)
enableTradingCheckInterval: 0

// Check daily
enableTradingCheckInterval: 86400

Impact:

Higher values -> Fewer RPC calls -> Faster performance
0 -> Always check -> Slower but always current
Recommended: 3600 (approvals rarely change)

quoteTokensCacheTtl

Type: number Description: Cache duration (in seconds) for quote token data Default: 3600 (1 hour) Range: 0 to infinity

Impact:

Quote tokens rarely change
Higher values improve performance
Recommended: 3600 or higher

marketCacheTtl

Type: number Description: Cache duration (in seconds) for market data Default: 300 (5 minutes) Range: 0 to infinity

Impact:

Markets change frequently (prices, status)
Lower values -> More current data
Recommended: 300 for balance of performance and freshness

proxyUrl

Type: string Description: HTTP proxy URL for API requests Default: undefined (no proxy)

proxyUrl: 'http://127.0.0.1:7890'

Environment Variables

Using .env Files

Create a .env file in your project root:

# .env
API_KEY=opn_prod_abc123xyz789
RPC_URL=____
PRIVATE_KEY=0x1234567890abcdef...
MULTI_SIG_ADDRESS=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
CHAIN_ID=56

Load in your code:

env-load.ts

import 'dotenv/config';
import { Client, CHAIN_ID_BNB_MAINNET, DEFAULT_API_HOST } from '@opinion-labs/opinion-clob-sdk';

const client = new Client({
  host: DEFAULT_API_HOST,
  apiKey: process.env.API_KEY!,
  chainId: CHAIN_ID_BNB_MAINNET,
  rpcUrl: process.env.RPC_URL!,
  privateKey: process.env.PRIVATE_KEY! as `0x${string}`,
  multiSigAddress: process.env.MULTI_SIG_ADDRESS! as `0x${string}`,
});

Using System Environment Variables

Set in shell:

# Linux/macOS
export API_KEY="opn_prod_abc123xyz789"
export RPC_URL=___
export PRIVATE_KEY="0x..."
export MULTI_SIG_ADDRESS="0x..."

# Windows (Command Prompt)
set API_KEY=opn_prod_abc123xyz789
set RPC_URL=___

# Windows (PowerShell)
$env:API_KEY="opn_prod_abc123xyz789"
$env:RPC_URL=___

Then access in your code:

const client = new Client({
  host: DEFAULT_API_HOST,
  apiKey: process.env.API_KEY!, // Throws if not set at runtime
  // ...
});

Configuration Patterns

Multi-Environment Setup

Manage different environments (dev, staging, prod):

multi-env.ts

import { Client, CHAIN_ID_BNB_MAINNET, DEFAULT_API_HOST } from '@opinion-labs/opinion-clob-sdk';

const ENVIRONMENTS = {
  production: {
    host: DEFAULT_API_HOST,
    chainId: CHAIN_ID_BNB_MAINNET,
    rpcUrl: 'https://bsc-dataseed.binance.org',
  },
} as const;

function createClient(env: 'production' = 'production') {
  const config = ENVIRONMENTS[env];
  const prefix = env.toUpperCase();

  return new Client({
    host: config.host,
    apiKey: process.env[`${prefix}_API_KEY`]!,
    chainId: config.chainId,
    rpcUrl: config.rpcUrl,
    privateKey: process.env[`${prefix}_PRIVATE_KEY`]! as `0x${string}`,
    multiSigAddress: process.env[`${prefix}_MULTI_SIG_ADDRESS`]! as `0x${string}`,
  });
}

const prodClient = createClient('production');

Factory Function

Organize configuration in a factory function:

factory.ts

import { Client, CHAIN_ID_BNB_MAINNET, DEFAULT_API_HOST } from '@opinion-labs/opinion-clob-sdk';

function createClientFromEnv(): Client {
  return new Client({
    host: DEFAULT_API_HOST,
    apiKey: process.env.API_KEY!,
    chainId: CHAIN_ID_BNB_MAINNET,
    rpcUrl: process.env.RPC_URL!,
    privateKey: process.env.PRIVATE_KEY! as `0x${string}`,
    multiSigAddress: process.env.MULTI_SIG_ADDRESS! as `0x${string}`,
    marketCacheTtl: 300,
  });
}

const client = createClientFromEnv();

Read-Only Client

For applications that only read data (no trading):

readonly.ts

// Minimal configuration for read-only access
const client = new Client({
  host: DEFAULT_API_HOST,
  apiKey: process.env.API_KEY!,
  chainId: CHAIN_ID_BNB_MAINNET,
  rpcUrl: '',
  privateKey: `0x${'00'.repeat(32)}` as `0x${string}`,
  multiSigAddress: '0x0000000000000000000000000000000000000000',
});

// Can use all GET methods
const markets = await client.getMarkets();
const market = await client.getMarket(123);
const orderbook = await client.getOrderbook('token_123');

// Cannot use trading or contract methods

Performance Tuning

High-Frequency Trading

For trading bots with frequent API calls:

hft.ts

const client = new Client({
  // ... required params ...
  marketCacheTtl: 60,
  quoteTokensCacheTtl: 3600,
  enableTradingCheckInterval: 7200,
});

Analytics/Research

For data analysis with less frequent updates:

analytics.ts

const client = new Client({
  // ... required params ...
  marketCacheTtl: 1800,
  quoteTokensCacheTtl: 86400,
  enableTradingCheckInterval: 0,
});

Real-Time Monitoring

For dashboards requiring fresh data:

realtime.ts

const client = new Client({
  // ... required params ...
  marketCacheTtl: 0,
  quoteTokensCacheTtl: 0,
  enableTradingCheckInterval: 0,
});

Smart Contract Addresses

BNB Chain Mainnet (Chain ID: 56)

The following smart contract addresses are used by the Opinion CLOB TypeScript SDK on BNB Chain mainnet:

Contract

Address

Description

ConditionalTokens

0xAD1a38cEc043e70E83a3eC30443dB285ED10D774

ERC1155 conditional tokens contract for outcome tokens

MultiSend

0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526

Gnosis Safe MultiSend contract for batch transactions

FeeManager

0xC9063Dc52dEEfb518E5b6634A6b8D624bc5d7c36

Fee rate management contract

These addresses are automatically used by the SDK when you specify chainId: 56. You only need to provide custom addresses if you are using a custom deployment.

Verification:

ConditionalTokens: View on BscScan
MultiSend: View on BscScan
FeeManager: View on BscScan

Next Steps

API Reference: All Supported Methods
Configuration Guide: Configuration
Core Concepts: Architecture
Troubleshooting: Common Issues

PreviousQuick Start

NextCore Concepts

Last updated 6 months ago