Quick Start

Get up and running with the Opinion CLOB TypeScript SDK in minutes. This guide will walk you through your first integration.

Prerequisites

Before starting, ensure you have:

• Node.js 18+ installed

• Opinion CLOB TypeScript SDK installed (Installation Guide)

• API credentials from Opinion Labs:

  • API Key

  • Private Key (for signing orders)

  • Multi-sig wallet address (create on https://app.opinion.trade)

  • RPC URL (BNB Chain mainnet)

Need credentials? Fill out this short application form to get your API key.

5-Minute Quickstart

1

Set Up Environment

Create a .env file in your project directory:

.env

# .env file
API_KEY=your_api_key_here
RPC_URL=https://bsc-dataseed.binance.org
PRIVATE_KEY=0x1234567890abcdef...
MULTI_SIG_ADDRESS=0xYourWalletAddress...

2

Initialize the Client

Create a new TypeScript file (my_first_app.ts):

my_first_app.ts (initialization)

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, // 56
  rpcUrl: process.env.RPC_URL!,
  privateKey: process.env.PRIVATE_KEY! as `0x${string}`,
  multiSigAddress: process.env.MULTI_SIG_ADDRESS! as `0x${string}`,
});

console.log('Client initialized successfully!');

3

Fetch Market Data

Add market data fetching:

fetch-markets.ts

import { TopicStatusFilter } from '@opinion-labs/opinion-clob-sdk';

// Get all active markets
const marketsResponse = await client.getMarkets({
  status: TopicStatusFilter.ACTIVATED,
  page: 1,
  limit: 10,
});

// Parse the response
if (marketsResponse.errno === 0) {
  const markets = marketsResponse.result.list;
  console.log(`\nFound ${markets.length} active markets:`);

  for (const market of markets.slice(0, 3)) {
    console.log(`  - Market #${market.market_id}: ${market.market_title}`);
    console.log(`    Status: ${market.status}`);
  }
} else {
  console.error(`Error: ${marketsResponse.errmsg}`);
}

4

Get Market Details

// Get details for a specific market
const marketId = markets[0].market_id;

const marketDetail = await client.getMarket(marketId);
if (marketDetail.errno === 0) {
  const market = marketDetail.result.data;
  console.log(`\nMarket Details for #${marketId}:`);
  console.log(`  Title: ${market.market_title}`);
  console.log(`  Question ID: ${market.question_id}`);
  console.log(`  Quote Token: ${market.quote_token}`);
  console.log(`  Chain ID: ${market.chain_id}`);
}

5

Check Orderbook

const tokenId = 'your_token_id_here'; // Replace with actual token ID

try {
  const orderbook = await client.getOrderbook(tokenId);
  if (orderbook.errno === 0) {
    console.log(`\nOrderbook for token ${tokenId}:`);
    console.log('Orderbook:', JSON.stringify(orderbook.result, null, 2));
  }
} catch (e) {
  console.log(`  (Skip if token_id not set: ${e})`);
}

6

Complete Example

Here is the full my_first_app.ts combining all the steps above:

my_first_app.ts

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

async function main() {
  // Initialize client
  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}`,
  });
  console.log('Client initialized successfully!');

  // Get active markets
  const marketsResponse = await client.getMarkets({
    status: TopicStatusFilter.ACTIVATED,
    limit: 5,
  });

  if (marketsResponse.errno === 0) {
    const markets = marketsResponse.result.list;
    console.log(`\nFound ${markets.length} active markets\n`);

    // Display markets
    markets.forEach((market, i) => {
      console.log(`${i + 1}. ${market.market_title}`);
      console.log(`   Market ID: ${market.market_id}`);
      console.log();
    });

    // Get details for first market
    if (markets.length > 0) {
      const firstMarket = markets[0];
      const detail = await client.getCategoricalMarket(firstMarket.market_id);

      if (detail.errno === 0) {
        const m = detail.result.data;
        console.log(`Details for '${m.market_title}':`);
        console.log(`  Status: ${m.status}`);
        console.log(`  Question ID: ${m.question_id}`);
        console.log(`  Quote Token: ${m.quote_token}`);
      }
    }
  } else {
    console.error(`Error fetching markets: ${marketsResponse.errmsg}`);
  }
}

main();

Run Your App

# Install dotenv if not already installed
npm install dotenv

# Run the script
npx tsx my_first_app.ts

Expected Output:

Client initialized successfully!

Found 5 active markets

1. Will Bitcoin reach $100k by end of 2025?
   Market ID: 1

2. Will AI surpass human intelligence by 2030?
   Market ID: 2

...

Details for 'Will Bitcoin reach $100k by end of 2025?':
  Status: 2
  Condition ID: 0xabc123...
  Quote Token: 0xdef456...

Next Steps

Now that you've fetched market data, explore more advanced features:

Trading

Learn how to place orders:

place-order.ts

import { OrderSide, OrderType, type PlaceOrderDataInput } from '@opinion-labs/opinion-clob-sdk';

// Enable trading (required once before placing orders)
await client.enableTrading();

// Place a buy order of "No" token
const orderData: PlaceOrderDataInput = {
  marketId: 813,
  tokenId: '33095770954068818933468604332582424490740136703838404213332258128147961949614',
  side: OrderSide.BUY,
  orderType: OrderType.LIMIT_ORDER,
  price: '0.55',
  makerAmountInQuoteToken: '10', // 10 USDT
};

const result = await client.placeOrder(orderData);
console.log('Order placed:', result);

See Placing Orders for detailed examples.

Position Management

Track your positions:

positions.ts

// Get balances
const balances = await client.getMyBalances();

// Get positions
const positions = await client.getMyPositions({ limit: 20 });

// Get trade history
const trades = await client.getMyTrades({ marketId: 813 });

See Managing Positions for more.

Smart Contract Operations

Interact with blockchain:

contract-ops.ts

// Split USDT into outcome tokens
const splitResult = await client.split(813, BigInt('1000000000000000000')); // 1 USDT

// Merge outcome tokens back to USDT
const mergeResult = await client.merge(813, BigInt('1000000000000000000'));

// Redeem winnings after market resolves
const redeemResult = await client.redeem(813);

See Contract Operations for details.

Common Patterns

Error Handling

Always check response status:

error-handling.ts

const response = await client.getMarkets();

if (response.errno === 0) {
  // Success
  const markets = response.result.list;
} else {
  // Error
  console.error(`Error ${response.errno}: ${response.errmsg}`);
}

Using Try-Catch

try-catch.ts

import { InvalidParamError, OpenApiError } from '@opinion-labs/opinion-clob-sdk';

try {
  const market = await client.getMarket(123);
} catch (e) {
  if (e instanceof InvalidParamError) {
    console.error(`Invalid parameter: ${e.message}`);
  } else if (e instanceof OpenApiError) {
    console.error(`API error: ${e.message}`);
  } else {
    console.error(`Unexpected error: ${e}`);
  }
}

Pagination

For large datasets:

pagination.ts

let page = 1;
const allMarkets: any[] = [];

while (true) {
  const response = await client.getMarkets({ page, limit: 20 });
  if (response.errno !== 0) break;

  const markets = response.result.list;
  allMarkets.push(...markets);

  if (markets.length < 20) break;
  page++;
}

console.log(`Total markets: ${allMarkets.length}`);

Configuration Tips

Cache Settings

Optimize performance with caching:

cache-config.ts

const client = new Client({
  // ... other params ...
  marketCacheTtl: 300,              // Cache markets for 5 minutes
  quoteTokensCacheTtl: 3600,        // Cache quote tokens for 1 hour
  enableTradingCheckInterval: 3600,  // Check trading status hourly
});

Set to 0 to disable caching:

disable-cache.ts

const client = new Client({
  // ... other params ...
  marketCacheTtl: 0,  // Disable market caching
});

Chain Selection

For production deployment, ensure you're using the correct configuration:

chain-selection.ts

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

const client = new Client({
  host: DEFAULT_API_HOST,
  chainId: CHAIN_ID_BNB_MAINNET, // 56
  rpcUrl: 'https://bsc-dataseed.binance.org',
  // ... other params ...
});

Resources

• API Reference: All Supported Methods

• Configuration Guide: Configuration

• Core Concepts: Architecture

• Troubleshooting: Common Issues

---

Ready to build? Explore the API Reference to see all available methods!