Skip to main content

Type definitions

All types are exported from @contextwtf/sdk and can be imported directly:
import type { Market, Order, Position, Balance } from "@contextwtf/sdk"

Market

interface Market {
  id: string
  question: string
  shortQuestion: string
  oracle: string
  outcomeTokens: string[]
  outcomePrices: OutcomePrice[]
  creator: string
  creatorProfile: { username: string | null; avatarUrl: string | null } | null
  volume: string
  volume24h: string
  participantCount: number
  resolutionStatus: "none" | "pending" | "resolved"
  status: "active" | "pending" | "resolved" | "closed"
  createdAt: string
  deadline: string
  resolutionCriteria: string
  resolvedAt: string | null
  payoutPcts: number[] | null
  metadata: MarketMetadata
  outcome: number | null
  contractAddress: string | null
}

interface OutcomePrice {
  outcomeIndex: number
  bestBid: number | null
  bestAsk: number | null
  spread: number | null
  midPrice: number | null
  lastPrice: number | null
  currentPrice: number | null
}

interface MarketMetadata {
  slug: string | null
  criteria: string
  startTime: number      // unix timestamp
  endTime: number        // unix timestamp
  shortSummary: string | null
  mediaHash: string | null
  sourceAccounts: {
    platform: string
    userId: string
    username: string
    displayName: string | null
    profileImageUrl: string | null
  }[]
  categories: string[] | null
}

Order

interface Order {
  nonce: string            // hex, unique identifier
  marketId: string
  trader: string           // address
  outcomeIndex: number
  side: 0 | 1              // 0 = Buy, 1 = Sell
  price: string            // numeric string (6 decimals)
  size: string             // numeric string (6 decimals)
  type: "limit" | "market"
  status: "open" | "filled" | "cancelled" | "expired" | "voided"
  insertedAt: string       // ISO 8601
  filledSize: string
  remainingSize: string
  percentFilled: number    // 0-100
  voidedAt: string | null
  voidReason:
    | "UNFILLED_MARKET_ORDER"
    | "UNDER_COLLATERALIZED"
    | "MISSING_OPERATOR_APPROVAL"
    | null
}

Quotes

interface Quotes {
  marketId: string
  yes: QuoteSide
  no: QuoteSide
  spread: number | null     // in cents
  timestamp: string
}

interface QuoteSide {
  bid: number | null        // cents
  ask: number | null        // cents
  last: number | null       // cents
}

Orderbook

interface Orderbook {
  marketId: string
  bids: OrderbookLevel[]
  asks: OrderbookLevel[]
  timestamp: string
}

interface OrderbookLevel {
  price: number             // cents
  size: number              // contracts
}

Position

interface Position {
  tokenAddress: string
  balance: string
  settlementBalance: string
  walletBalance: string
  outcomeIndex: number
  outcomeName: string
  marketId: string
  netInvestment: string
  currentValue: string
  tokensRedeemed: string
}

Balance

interface Balance {
  address: string
  usdc: UsdcBalance
  outcomeTokens: OutcomeTokenBalance[]
}

interface UsdcBalance {
  tokenAddress: string
  balance: string
  settlementBalance: string
  walletBalance: string
}

interface OutcomeTokenBalance {
  tokenAddress: string
  marketId: string
  outcomeIndex: number
  outcomeName: string
  balance: string
  settlementBalance: string
  walletBalance: string
}

Portfolio stats

interface PortfolioStats {
  currentPortfolioValue: string
  currentPortfolioPercentChange: number
}

Claimable

interface ClaimableResponse {
  positions: ClaimablePosition[]
  markets: ClaimableMarket[]
  totalClaimable: string
}

interface ClaimablePosition {
  tokenAddress: string
  balance: string
  settlementBalance: string
  walletBalance: string
  outcomeIndex: number
  outcomeName: string | null
  marketId: string
  netInvestment: string
  claimableAmount: string
}

interface ClaimableMarket {
  id: string
  outcomeTokens: string[]
  outcomeNames: string[]
  payoutPcts: string[]
}

Oracle

interface OracleData {
  lastCheckedAt: string | null
  confidenceLevel: string | null
  evidenceCollected: {
    postsCount: number
    relevantPosts: string[]
  }
  sourcesMonitored: string[]
  summary: {
    decision: string
    shortSummary: string
    expandedSummary: string
  }
}

interface OracleQuote {
  id: number
  status: string
  probability: number | null
  confidence: "low" | "medium" | "high" | null
  reasoning: string | null
  referenceMarketsCount: number
  createdAt: string
  completedAt: string | null
}

Simulate

// Market-level simulation (ctx.markets.simulate)
interface SimulateResult {
  marketId: string
  side: string
  amount: number
  amountType: string
  estimatedContracts: number
  estimatedAvgPrice: number
  estimatedSlippage: number
}

// Order-level simulation (ctx.orders.simulate)
interface OrderSimulateResult {
  levels: OrderSimulateLevel[]
  summary: {
    fillSize: string
    fillCost: string
    takerFee: string
    weightedAvgPrice: string
    totalLiquidityAvailable: string
    percentFillable: number
    slippageBps: number
  }
  collateral: {
    balance: string
    outcomeTokenBalance: string
    requiredForFill: string
    isSufficient: boolean
  }
  warnings: string[]
}

interface OrderSimulateLevel {
  price: string
  sizeAvailable: string
  cumulativeSize: string
  takerFee: string
  cumulativeTakerFee: string
  collateralRequired: string
  cumulativeCollateral: string
  makerCount: number
}

Wallet

interface WalletStatus {
  address: string
  ethBalance: bigint
  usdcAllowance: bigint
  isOperatorApproved: boolean
  needsApprovals: boolean
}

Activity

interface ActivityItem {
  type: string
  timestamp: string
  marketId?: string
  data?: unknown
}

interface ActivityResponse {
  marketId: string | null
  activity: ActivityItem[]
  pagination?: {
    cursor: string | null
    hasMore: boolean
  }
}

Price history

interface PriceHistory {
  prices: PricePoint[]
  startTime: number
  endTime: number
  interval: number
}

interface PricePoint {
  time: number       // unix timestamp
  price: number      // cents
}

type PriceTimeframe = "1h" | "6h" | "1d" | "1w" | "1M" | "all"