Skip to main content

Balance & Allowance Types

BalanceAllowanceParams

Parameters for querying balance and allowance.
interface BalanceAllowanceParams {
  asset_type: AssetType;
  token_id?: string;
}

enum AssetType {
  COLLATERAL = "COLLATERAL",
  CONDITIONAL = "CONDITIONAL"
}
asset_type
AssetType
required
Type of asset (COLLATERAL or CONDITIONAL)
token_id
string
Token ID (required for CONDITIONAL assets)

Example

// Query USDC collateral balance
const collateralParams: BalanceAllowanceParams = {
  asset_type: AssetType.COLLATERAL
};

// Query conditional token balance
const conditionalParams: BalanceAllowanceParams = {
  asset_type: AssetType.CONDITIONAL,
  token_id: "0x123..."
};

BalanceAllowanceResponse

Response containing balance and allowance information.
interface BalanceAllowanceResponse {
  balance: string;
  allowance: string;
}
balance
string
required
Current token balance (in wei/smallest unit)
allowance
string
required
Approved allowance for the CLOB contract (in wei/smallest unit)

Example

const response: BalanceAllowanceResponse = {
  balance: "1000000000",    // 1000 USDC (6 decimals)
  allowance: "1000000000000" // Large allowance
};

Fee Types

FeeRates

Mapping of token IDs to their fee rates.
interface FeeRates {
  [tokenId: string]: number;
}
Each value represents the fee rate in basis points (bps) for the corresponding token.

Example

const feeRates: FeeRates = {
  "0x123...": 5,   // 0.05% fee (5 basis points)
  "0x456...": 10   // 0.10% fee (10 basis points)
};

Rewards Types

UserEarning

Daily earnings for a user on a specific market.
interface UserEarning {
  date: string;
  condition_id: string;
  asset_address: string;
  maker_address: string;
  earnings: number;
  asset_rate: number;
}
date
string
required
Date of the earnings (ISO 8601 format)
condition_id
string
required
Market condition ID
asset_address
string
required
Reward asset address
maker_address
string
required
Maker’s address
earnings
number
required
Earnings amount for the day
asset_rate
number
required
Exchange rate of the asset

TotalUserEarning

Total earnings across all markets for a user.
interface TotalUserEarning {
  date: string;
  asset_address: string;
  maker_address: string;
  earnings: number;
  asset_rate: number;
}
date
string
required
Date of the earnings
asset_address
string
required
Reward asset address
maker_address
string
required
Maker’s address
earnings
number
required
Total earnings for the day
asset_rate
number
required
Exchange rate of the asset

RewardsPercentages

Mapping of markets to their reward percentage allocations.
interface RewardsPercentages {
  [market: string]: number;
}

Example

const percentages: RewardsPercentages = {
  "0xabc...": 25.5,  // 25.5% of rewards
  "0xdef...": 30.0   // 30.0% of rewards
};

Token

Token information with price.
interface Token {
  token_id: string;
  outcome: string;
  price: number;
}
token_id
string
required
Token/asset ID
outcome
string
required
Outcome name (e.g., “Yes”, “No”)
price
number
required
Current price

RewardsConfig

Configuration for a rewards program.
interface RewardsConfig {
  asset_address: string;
  start_date: string;
  end_date: string;
  rate_per_day: number;
  total_rewards: number;
}
asset_address
string
required
Address of the reward token
start_date
string
required
Start date of the rewards program
end_date
string
required
End date of the rewards program
rate_per_day
number
required
Daily reward distribution rate
total_rewards
number
required
Total amount of rewards in the program

MarketReward

Reward information for a specific market.
interface MarketReward {
  condition_id: string;
  question: string;
  market_slug: string;
  event_slug: string;
  image: string;
  rewards_max_spread: number;
  rewards_min_size: number;
  tokens: Token[];
  rewards_config: RewardsConfig[];
}
condition_id
string
required
Market condition ID
question
string
required
Market question
market_slug
string
required
URL slug for the market
event_slug
string
required
URL slug for the event
image
string
required
Market image URL
rewards_max_spread
number
required
Maximum spread allowed for rewards eligibility
rewards_min_size
number
required
Minimum order size for rewards eligibility
tokens
Token[]
required
Array of tokens in this market
rewards_config
RewardsConfig[]
required
Array of reward configurations

Earning

Earnings information for a specific asset.
interface Earning {
  asset_address: string;
  earnings: number;
  asset_rate: number;
}
asset_address
string
required
Reward asset address
earnings
number
required
Earnings amount
asset_rate
number
required
Exchange rate of the asset

UserRewardsEarning

Detailed rewards earning information for a user.
interface UserRewardsEarning {
  condition_id: string;
  question: string;
  market_slug: string;
  event_slug: string;
  image: string;
  rewards_max_spread: number;
  rewards_min_size: number;
  market_competitiveness: number;
  tokens: Token[];
  rewards_config: RewardsConfig[];
  maker_address: string;
  earning_percentage: number;
  earnings: Earning[];
}
condition_id
string
required
Market condition ID
question
string
required
Market question
market_slug
string
required
URL slug for the market
event_slug
string
required
URL slug for the event
image
string
required
Market image URL
rewards_max_spread
number
required
Maximum spread allowed for rewards
rewards_min_size
number
required
Minimum order size for rewards
market_competitiveness
number
required
Competitiveness score for the market
tokens
Token[]
required
Array of tokens
rewards_config
RewardsConfig[]
required
Array of reward configurations
maker_address
string
required
Maker’s address
earning_percentage
number
required
User’s percentage of total earnings
earnings
Earning[]
required
Array of earnings by asset

Order Scoring Types

OrderScoringParams

Parameters for checking if an order is eligible for rewards.
interface OrderScoringParams {
  order_id: string;
}
order_id
string
required
Order ID to check

OrderScoring

Response indicating if an order is eligible for rewards.
interface OrderScoring {
  scoring: boolean;
}
scoring
boolean
required
Whether the order is eligible for rewards scoring

OrdersScoringParams

Parameters for checking multiple orders.
interface OrdersScoringParams {
  orderIds: string[];
}
orderIds
string[]
required
Array of order IDs to check

OrdersScoring

Mapping of order IDs to their scoring eligibility.
type OrdersScoring = { [orderId in string]: boolean };

Example

const scoring: OrdersScoring = {
  "0x123...": true,
  "0x456...": false,
  "0x789...": true
};

Builder Types

BuilderTrade

Trade information from the builder API.
interface BuilderTrade {
  id: string;
  tradeType: string;
  takerOrderHash: string;
  builder: string;
  market: string;
  assetId: string;
  side: string;
  size: string;
  sizeUsdc: string;
  price: string;
  status: string;
  outcome: string;
  outcomeIndex: number;
  owner: string;
  maker: string;
  transactionHash: string;
  matchTime: string;
  bucketIndex: number;
  fee: string;
  feeUsdc: string;
  err_msg?: string | null;
  createdAt: string | null;
  updatedAt: string | null;
}
id
string
required
Unique trade identifier
tradeType
string
required
Type of trade
takerOrderHash
string
required
Hash of the taker order
builder
string
required
Builder address
market
string
required
Market condition ID
assetId
string
required
Asset/token ID
side
string
required
Trade side (BUY or SELL)
size
string
required
Trade size in tokens
sizeUsdc
string
required
Trade size in USDC
price
string
required
Execution price
status
string
required
Trade status
outcome
string
required
Outcome name
outcomeIndex
number
required
Outcome index
owner
string
required
Owner address
maker
string
required
Maker address
transactionHash
string
required
Transaction hash
matchTime
string
required
When the trade was matched
bucketIndex
number
required
Bucket index for time aggregation
fee
string
required
Fee amount in tokens
feeUsdc
string
required
Fee amount in USDC
err_msg
string | null
Error message if the trade failed
createdAt
string | null
Creation timestamp
updatedAt
string | null
Last update timestamp

Notification Types

Notification

Generic notification structure.
interface Notification {
  type: number;
  owner: string;
  payload: any;
}
type
number
required
Notification type identifier
owner
string
required
Notification owner address
payload
any
required
Notification payload data

DropNotificationParams

Parameters for dropping/dismissing notifications.
interface DropNotificationParams {
  ids: string[];
}
ids
string[]
required
Array of notification IDs to drop

Heartbeat Type

HeartbeatResponse

Response from heartbeat endpoint.
interface HeartbeatResponse {
  readonly heartbeat_id: string;
  readonly error?: string;
}
heartbeat_id
string
required
Unique heartbeat identifier
error
string
Error message if the heartbeat failed

Build docs developers (and LLMs) love