FAQ

Frequently asked questions about the TypeScript SDK (@opinion-labs/opinion-clob-sdk v0.5.2).

---

Installation and Setup

How do I install the SDK?

npm install @opinion-labs/opinion-clob-sdk

The package is published on npm as @opinion-labs/opinion-clob-sdk.

What are the minimum requirements?

• Node.js: 18 or later

• TypeScript: 5.3 or later (if using TypeScript)

• The SDK is an ESM package and requires an ESM-compatible project setup.

How do I use the SDK in a CommonJS project?

The SDK is published as ESM. If your project uses CommonJS (require), use dynamic import():

async function main() {
  const { Client, CHAIN_ID_BNB_MAINNET, DEFAULT_API_HOST } = await import(
    '@opinion-labs/opinion-clob-sdk'
  );

  const client = new Client({
    host: DEFAULT_API_HOST,
    apiKey: 'YOUR_API_KEY',
    chainId: CHAIN_ID_BNB_MAINNET,
    rpcUrl: 'YOUR_RPC_URL',
    privateKey: '0xYOUR_PRIVATE_KEY',
    multiSigAddress: '0xYOUR_MULTI_SIG_ADDRESS',
  });
}

main();

Alternatively, add "type": "module" to your package.json to enable ESM.

What imports do I need?

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

// Enums
import {
  TopicType,
  TopicStatus,
  TopicStatusFilter,
  TopicSortType,
  OrderSide,
  OrderType,
} from '@opinion-labs/opinion-clob-sdk';

// Types
import type { PlaceOrderDataInput } from '@opinion-labs/opinion-clob-sdk';

// Error classes
import {
  InvalidParamError,
  OpenApiError,
  BalanceNotEnough,
  NoPositionsToRedeem,
  InsufficientGasBalance,
  ValidationException,
} from '@opinion-labs/opinion-clob-sdk';

// Builder mode (optional)
import { BuilderClient, UserClient } from '@opinion-labs/opinion-clob-sdk';

---

Configuration

Which chain IDs are supported?

Currently only BNB Chain mainnet (chain ID 56) is supported. Use the constant CHAIN_ID_BNB_MAINNET:

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

const client = new Client({
  chainId: CHAIN_ID_BNB_MAINNET, // 56
  // ...
});

What is the difference between the private key and the multi-sig address?

• Private Key (privateKey): The key of your login wallet (EOA). Used for signing orders and transactions. This wallet needs BNB for gas fees on blockchain operations.

• Multi-Sig Address (multiSigAddress): Your asset wallet (Gnosis Safe). This is where your trading funds are held. It is the address shown in "My Portfolio" on the platform.

The signer (login wallet) authorizes trades on behalf of the multi-sig (asset wallet).

How do I get an API key?

Contact the Opinion Labs team to obtain your API key for SDK access. The API key is passed in the apikey HTTP header for all API requests.

How do I find my asset wallet (multi-sig) address?

1. Log in at app.olab.xyz.

2. Click the Add Fund button on the navigation bar.

3. Click Create Your Asset Wallet if you do not have one.

4. Wait a few minutes and reopen the popup.

5. Copy the address displayed.

How do I configure a proxy?

Pass the proxyUrl option during client initialization:

const client = new Client({
  // ...
  proxyUrl: 'http://127.0.0.1:7890',
});

The proxy applies to both HTTP API calls and WebSocket connections.

Can I override the default contract addresses?

Yes, but only do so if instructed by the Opinion Labs team:

const client = new Client({
  // ...
  conditionalTokensAddress: '0x...',
  multiSendAddress: '0x...',
  feeManagerAddress: '0x...',
  ctfExchangeAddress: '0x...',
});

---

Trading

What is the difference between market orders and limit orders?

• Market order (OrderType.MARKET_ORDER): Executes immediately at the best available price. You specify how much to spend (buy) or how many shares to sell. Price is ignored.

• Limit order (OrderType.LIMIT_ORDER): Executes at your specified price or better. If the market price does not reach your limit, the order remains open until filled, canceled, or expired.

How do I specify order amounts?

There are two ways:

• By quote token (makerAmountInQuoteToken): Specify how much USDC to spend. Example: "100" means 100 USDC.

• By shares (makerAmountInBaseToken): Specify how many outcome tokens (shares). Example: "50" means 50 Yes tokens.

Rules:

Order Type	Side	Allowed Amount Field
Market	Buy	makerAmountInQuoteToken only
Market	Sell	makerAmountInBaseToken only
Limit	Buy	Either
Limit	Sell	Either

Do I need to call enableTrading() before every order?

No. You only need to call enableTrading() once per trading account. After that, your orders can be filled on-chain.

Alternatively, pass checkApproval: true to placeOrder(), which will check and enable trading if needed. However, for performance, it is better to call enableTrading() once at startup.

How do I cancel orders?

// Cancel a single order
await client.cancelOrder('order_id');

// Cancel multiple orders
await client.cancelOrdersBatch(['id_1', 'id_2', 'id_3']);

// Cancel all open orders
await client.cancelAllOrders();

// Cancel all BUY orders for a specific market
await client.cancelAllOrders({ marketId: 57, side: OrderSide.BUY });

What are the order status codes?

Status	Meaning
1	Pending (open)
2	Filled
3	Canceled
4	Expired
5	Failed
6	On-chain failed

---

Smart Contracts

Which operations require gas (BNB)?

Operation	Gas Required	Description
enableTrading()	Yes	Approve token spending on-chain
split()	Yes	Convert collateral to outcome tokens
merge()	Yes	Convert outcome tokens back to collateral
redeem()	Yes	Claim winnings from resolved markets
placeOrder()	No	Off-chain signed order
cancelOrder()	No	Off-chain cancellation
getMarkets()	No	API call
All get* methods	No	API calls

What is the split/merge/redeem workflow?

1. Split: Deposit USDC into a market to receive equal amounts of Yes and No tokens.

2. Trade: Buy or sell outcome tokens on the order book.

3. Merge: Convert equal amounts of Yes and No tokens back to USDC (useful to exit both sides).

4. Redeem: After market resolution, exchange winning tokens for USDC.

What market statuses allow split and merge?

Both split() and merge() require the market to be in one of these statuses:

• ACTIVATED (2)

• RESOLVING (3)

• RESOLVED (4)

What market status is required for redeem?

Only RESOLVED (4). The market must have a final outcome before you can redeem.

---

Errors

Why do I get "Invalid parameter" errors?

Common causes:

• page is less than 1.

• limit is less than 1 or greater than 20.

• marketId is 0 or negative.

• tokenId is an empty string.

• orderId is an empty string.

• Using makerAmountInBaseToken for a market buy order (not allowed).

• Using makerAmountInQuoteToken for a market sell order (not allowed).

• Amount is less than 1 (minimum order size).

What does "Cannot split/merge/redeem on different chain" mean?

The market you are trying to interact with belongs to a different blockchain than your client is configured for. Ensure chainId is set to 56 and the market is on BNB Chain.

What does "Cannot redeem on non-resolved market" mean?

You can only redeem from markets that have been resolved (status = 4). Check the market status first:

const market = await client.getMarket(marketId);
console.log(market.result.data.status);     // Should be 4 (RESOLVED)
console.log(market.result.data.statusEnum); // Should be "resolved"

How do I handle network errors?

Wrap your calls in try/catch and check for OpenApiError:

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

try {
  const result = await client.getMarkets();
} catch (error) {
  if (error instanceof OpenApiError) {
    console.error('API error:', error.message);
    // Retry logic here
  }
}

---

Data and Precision

How are prices represented?

Prices are strings representing a value between 0 and 1. For example, "0.55" means 55 cents per outcome token. A price of "1" means the outcome is considered certain.

How are amounts represented?

• API responses: Amounts are returned as strings with full decimal precision (e.g., "887306.479964285714285714").

• placeOrder input: Use human-readable strings (e.g., "100" for 100 USDC).

• split/merge input: Use bigint in wei (e.g., BigInt(100 * 10**6) for 100 USDC with 6 decimals).

What decimal precision should I use for split/merge amounts?

It depends on the collateral token's decimals. Check with getQuoteTokens():

const tokens = await client.getQuoteTokens();
const decimal = tokens.result.list[0].decimal;  // e.g., 6 for USDC, 18 for others

// For USDC (6 decimals): 100 USDC = 100 * 10^6
const amount = BigInt(100 * 10 ** decimal);
await client.split(marketId, amount);

Why are there floating-point precision differences in prices?

The SDK uses string-based arithmetic internally to minimize floating-point issues. Prices and amounts in API responses are always strings. When performing your own calculations, avoid native floating-point math; use a library like decimal.js for precise calculations.

---

Support

Where can I find more documentation?

• SDK Documentation: https://docs.opinion.trade

• API Reference: https://openapi.opinion.trade

How do I report a bug?

• Email: [email protected]

• GitHub Issues: Open an issue on the SDK repository with:

  • SDK version (npm list @opinion-labs/opinion-clob-sdk)

  • Node.js version (node --version)

  • Full error message and stack trace

  • Minimal code to reproduce the issue

Is there a Python SDK available?

Yes. The Python SDK (opinion_clob_sdk) provides equivalent functionality. See the Python SDK documentation for details.