Models

This page documents the enums, data types, response structures, and exception types used in the TypeScript SDK (@opinion-labs/opinion-clob-sdk v0.5.2).

---

Enums

TopicType

Market type for filtering.

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

Value	Numeric	Description
TopicType.BINARY	0	Binary (Yes/No) markets
TopicType.CATEGORICAL	1	Categorical (multiple outcome) markets
TopicType.ALL	2	All market types

TopicStatus

Market lifecycle status.

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

Value	Numeric	Description
TopicStatus.CREATED	1	Market has been created but is not yet active
TopicStatus.ACTIVATED	2	Market is active and open for trading
TopicStatus.RESOLVING	3	Market is in the resolution process
TopicStatus.RESOLVED	4	Market has been resolved with a final outcome
TopicStatus.FAILED	5	Market creation or resolution failed
TopicStatus.DELETED	6	Market has been deleted

TopicStatusFilter

Status filter for querying markets via getMarkets().

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

Value	String	Description
TopicStatusFilter.ALL	""	Return all markets regardless of status
TopicStatusFilter.ACTIVATED	"activated"	Only active/tradable markets
TopicStatusFilter.RESOLVED	"resolved"	Only resolved markets

TopicSortType

Sorting options for market listings.

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

Value	Numeric	Description
TopicSortType.BY_TIME_DESC	1	Sort by creation time (newest first)
TopicSortType.BY_CUTOFF_TIME_ASC	2	Sort by cutoff time (soonest first)
TopicSortType.BY_VOLUME_DESC	3	Sort by total volume (highest first)
TopicSortType.BY_VOLUME_ASC	4	Sort by total volume (lowest first)
TopicSortType.BY_VOLUME_24H_DESC	5	Sort by 24h volume (highest first)
TopicSortType.BY_VOLUME_24H_ASC	6	Sort by 24h volume (lowest first)
TopicSortType.BY_VOLUME_7D_DESC	7	Sort by 7d volume (highest first)
TopicSortType.BY_VOLUME_7D_ASC	8	Sort by 7d volume (lowest first)

OrderSide

Order direction.

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

Value	Numeric	Description
OrderSide.BUY	0	Buy order
OrderSide.SELL	1	Sell order

OrderType

Order execution type.

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

Value	Numeric	Description
OrderType.MARKET_ORDER	1	Market order (executed at best available price)
OrderType.LIMIT_ORDER	2	Limit order (executed at specified price or better)

---

Data Types

PlaceOrderDataInput

The input type used when placing orders via placeOrder() or placeOrdersBatch().

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

const orderData: PlaceOrderDataInput = {
  marketId: 57,
  tokenId: 'YOUR_TOKEN_ID',
  side: OrderSide.BUY,
  orderType: OrderType.LIMIT_ORDER,
  price: '0.6',
  makerAmountInQuoteToken: '100',  // 100 USDT
};

Field	Type	Required	Description
marketId	number	Yes	Market ID / Topic ID
tokenId	string	Yes	Token ID of the CTF ERC1155 asset (e.g., Yes token ID)
side	OrderSide	Yes	OrderSide.BUY or OrderSide.SELL
orderType	OrderType	Yes	OrderType.MARKET_ORDER or OrderType.LIMIT_ORDER
price	string	Yes	Price per outcome token (e.g., "0.5" for 50 cents). Required for limit orders; set to any value for market orders.
makerAmountInQuoteToken	string	No	Amount in quote token (e.g., "100" USDC). Use for buy orders or when specifying by dollar value.
makerAmountInBaseToken	string	No	Amount in outcome tokens (e.g., "50" Yes tokens). Use for sell orders or when specifying by share count.

Amount rules:

• You must provide exactly one of makerAmountInQuoteToken or makerAmountInBaseToken.

• For market buy orders: only makerAmountInQuoteToken is allowed.

• For market sell orders: only makerAmountInBaseToken is allowed.

• For limit orders: either field is accepted.

ClientConfig

Configuration options for initializing the Client.

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,
  rpcUrl: 'YOUR_RPC_URL',
  privateKey: '0xYOUR_PRIVATE_KEY',
  multiSigAddress: '0xYOUR_MULTI_SIG_ADDRESS',
});

Field	Type	Required	Description
host	string	Yes	API host URL
apiKey	string	Yes	API authentication key
chainId	number	Yes	Blockchain chain ID (56 for BNB Chain)
rpcUrl	string	Yes	RPC endpoint URL
privateKey	Hex	Yes	Private key for signing transactions
multiSigAddress	Address	Yes	Multi-signature wallet address
conditionalTokensAddress	Address	No	Conditional tokens contract address
multiSendAddress	Address	No	MultiSend contract address
feeManagerAddress	Address	No	FeeManager contract address
ctfExchangeAddress	Address	No	CTF Exchange contract address (overrides API-provided)
enableTradingCheckInterval	number	No	Cache TTL for enable trading checks in seconds (default: 3600)
quoteTokensCacheTtl	number	No	Cache TTL for quote tokens in seconds (default: 3600)
marketCacheTtl	number	No	Cache TTL for market data in seconds (default: 300)
proxyUrl	string	No	HTTP proxy URL for API requests

TransactionResult

Returned by blockchain operations (enableTrading, split, merge, redeem).

interface TransactionResult {
  txHash?: string;  // Transaction hash (undefined if no on-chain tx was needed)
  success: boolean;
}

---

Response Structure

All API methods return responses in a consistent wrapper format:

interface ApiResponse<T> {
  errno: number;   // 0 = success, non-zero = error
  errmsg: string;  // Error message (empty on success)
  result: T;       // Response payload
}

Example: Successful response

{
  "errno": 0,
  "errmsg": "",
  "result": {
    "total": 10,
    "list": [
      {
        "marketId": 5,
        "marketTitle": "Example Market",
        "status": 2,
        "statusEnum": "activated",
        "yesTokenId": "101128430008250248394161770787866737734499464157137890629662678617009651760181",
        "noTokenId": "60119751433323231793441870248949152266777555824072219518426778460783591201702",
        "yesLabel": "Yes",
        "noLabel": "No",
        "quoteToken": "0x5Fd47a476d9c8309dF84D50cfAa0AB576c28DF0D",
        "volume": "2.000000000000000000",
        "conditionId": "...",
        "cutoffAt": 1734537600,
        "createdAt": 1734515671,
        "rules": ""
      }
    ]
  }
}

Example: Error response

{
  "errno": 500,
  "errmsg": "error message",
  "result": null
}

Common errno Values

errno	Description
0	Success
1	Internal error
2	Invalid parameter
100	Invalid API key
200	Market not found
300	Order not found
301	Order cannot be canceled
303	Insufficient balance
304	Price out of range
305	Amount too small
429	Rate limit exceeded
500	Internal server error

---

Exception Types

The SDK defines custom exception classes for different error scenarios. All exceptions extend the base SdkError class.

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

Exception	When Thrown
SdkError	Base class for all SDK errors. Not thrown directly.
InvalidParamError	Invalid parameters passed to SDK methods (e.g., invalid marketId, missing required fields, price out of range).
OpenApiError	API call failures (e.g., network errors, unexpected API responses, chain mismatch).
BalanceNotEnough	Insufficient token balance for an operation.
NoPositionsToRedeem	Attempting to redeem from a market with no redeemable positions.
InsufficientGasBalance	Signer wallet does not have enough gas (BNB) for a blockchain transaction.
ValidationException	Order validation failed during the order building process.

Error Handling Example

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

try {
  const result = await client.placeOrder(orderData);
} catch (error) {
  if (error instanceof InvalidParamError) {
    console.error('Invalid parameter:', error.message);
  } else if (error instanceof BalanceNotEnough) {
    console.error('Insufficient balance:', error.message);
  } else if (error instanceof OpenApiError) {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}