prob-sdk

A TypeScript SDK for interacting with the Prob prediction market platform. This SDK provides a comprehensive interface for trading, managing positions, querying market data, and more.

Features

- Order Management: Create, sign, submit, and cancel limit and market orders
- Market Data: Query orderbooks, prices, price history, and market information
- Position Management: Query, split, merge, and redeem positions
- Trade History: Access trading activity, PnL, and trade records
- Event & Market Queries: Search and retrieve events and markets
- Authentication: Support for L1 (wallet signature), L2 (API key)
- Safe Proxy Wallet: Built-in support for Safe proxy wallet operations

Changelog

See CHANGELOG.md for a detailed list of changes and version history.

Install

To use this SDK in your project, install the main package:

``bash


Using pnpm

pnpm add @prob/clob

Using npm

npm install @prob/clob

Using yarn

yarn add @prob/clob
`

Package Structure

This is a monorepo containing three main packages:

- @prob/clob: Main SDK package for CLOB (Central Limit Order Book) operations
- @prob/core: Core utilities including exchange configs, ABIs, and token operations
- @prob/types: TypeScript type definitions shared across packages

Quick Start

$3

First, create a wallet client and then create the CLOB client:

`typescript
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { bsc } from 'viem/chains'
import { createClobClient } from '@prob/clob'

// Create a wallet client
const account = privateKeyToAccount('0x...' as 0x${string})
const wallet = createWalletClient({
chain: bsc,
transport: http(),
account: account,
})

// Create the CLOB client
const client = createClobClient({
chainId: bsc.id,
wallet: wallet,
})

// For methods that require authentication (order operations, trades, etc.),
// generate an API key first. The API key will be automatically stored in the client.
await client.generateApiKey()
`

Note:
- L1 authentication (wallet signature) is automatically handled when you provide a wallet to the client.
- Methods that use l1AuthHttpClient or l2AuthHttpClient require calling generateApiKey() first. These include:
- Order operations: postOrder, postOrders, getOrder, getOpenOrders, cancelOrder, cancelOrders, cancelAllOrders
- Trade operations: getTrades
- API key management: getApiKey, deleteApiKey
- Info: getTokenIdsForEvent
- Public methods (like getMarkets, getOrderBook, getEvents) don't require authentication.

$3

`typescript
// Get markets (public, no authentication required)
const markets = await client.getMarkets({ eventId: '162' })

// Get orderbook (public, no authentication required)
const orderbook = await client.getOrderBook({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
})

// Get current positions (requires authentication, ensure generateApiKey() was called)
const positions = await client.getCurrentPositions({ eventId: '162' })
`

API Reference

$3

| Auth Type | Description | Requirements |
|-----------|-------------|--------------|
| No Auth | Public API, can be called directly | No setup required |
| L1 Auth | Requires wallet signature authentication | Provide wallet when creating client |
| L2 Auth | Requires API Key authentication | Call generateApiKey() to generate API Key |

$3

#### API Key Management

| Method | Description | Auth Required |
|--------|-------------|---------------|
| generateApiKey() | Generate API Key | L1 Auth |
| getApiKey() | Get current API Key | L1 Auth |
| deleteApiKey() | Delete API Key | L2 Auth |
| refreshApiKey() | Refresh API Key | L2 Auth |

#### Order Operations

| Method | Description | Auth Required |
|--------|-------------|---------------|
| createOrder() | Create order object | No Auth |
| createMarketOrder() | Create market order | No Auth |
| createLimitOrder() | Create limit order | No Auth |
| signOrder() | Sign order | No Auth (local operation) |
| signOrderStruct() | Sign order struct | No Auth (local operation) |
| postOrder() | Submit single order | L2 Auth |
| postSignedOrder() | Submit signed order | L2 Auth |
| postOrders() | Submit multiple orders | L2 Auth |
| postSignedOrders() | Submit multiple signed orders | L2 Auth |
| getOrder() | Get single order | L2 Auth |
| getOpenOrders() | Get open orders list | L2 Auth |
| cancelOrder() | Cancel single order | L2 Auth |
| cancelOrders() | Cancel multiple orders | L2 Auth |
| cancelAllOrders() | Cancel all orders | L2 Auth |

#### Market Data Queries

| Method | Description | Auth Required |
|--------|-------------|---------------|
| getOrderBook() | Get orderbook | No Auth |
| getPrice() | Get single token price | No Auth |
| getPrices() | Get multiple prices | No Auth |
| getMidpoint() | Get midpoint price | No Auth |
| getPricesHistory() | Get price history | No Auth |

#### Position Management

| Method | Description | Auth Required |
|--------|-------------|---------------|
| getCurrentPositions() | Get current positions | No Auth |
| getClosedPositions() | Get closed positions | No Auth |
| getPendingPositions() | Get pending positions | No Auth |
| getPositionValue() | Get position value | No Auth |
| splitPosition() | Split position | Requires wallet (on-chain operation) |
| createSplitPositionCalldata() | Create split position calldata | No Auth (local operation) |
| mergePosition() | Merge position | Requires wallet (on-chain operation) |
| createMergePositionCalldata() | Create merge position calldata | No Auth (local operation) |
| redeemPosition() | Redeem position | Requires wallet (on-chain operation) |
| createRedeemPositionCalldata() | Create redeem position calldata | No Auth (local operation) |

#### Trade History

| Method | Description | Auth Required |
|--------|-------------|---------------|
| getActivity() | Get trading activity | No Auth |
| getPnL() | Get profit and loss data | No Auth |
| getTrades() | Get trade records | L2 Auth |

#### Event and Market Queries

| Method | Description | Auth Required |
|--------|-------------|---------------|
| getEvents() | Get events list | No Auth |
| getEventById() | Get event by ID | No Auth |
| getEventBySlug() | Get event by slug | No Auth |
| getEventTags() | Get event tags | No Auth |
| getMarkets() | Get markets list | No Auth |
| getMarketById() | Get market by ID | No Auth |
| getMarketByPolymarketId() | Get market by Polymarket ID | No Auth |
| getMarketByBscQuestionId() | Get market by BSC Question ID | No Auth |
| search() | Search events and markets | No Auth |
| getTokenIdsForEvent() | Get token IDs for event | L2 Auth |

#### Safe Proxy Wallet Operations

| Method | Description | Auth Required |
|--------|-------------|---------------|
| checkSafeProxyWalletExists() | Check if Safe proxy wallet exists | Requires wallet (on-chain query) |
| signSafeProxyTx() | Sign Safe proxy transaction | Requires wallet (local operation) |
| proxyApproveCollateralIfNeeded() | Approve collateral if needed | Requires wallet (on-chain operation) |
| proxyApproveCollateral() | Approve collateral | Requires wallet (on-chain operation) |
| proxyApproveCollateralSync() | Approve collateral synchronously | Requires wallet (on-chain operation) |
| proxyExecuteTx() | Execute transaction via proxy | Requires wallet (on-chain operation) |
| getSafeProxyNonce() | Get Safe proxy nonce | Requires wallet (on-chain query) |

Main API Usage Examples

$3

#### Fee
actually we have fees on order, can see the details here and api docs

can calculate fee through this function
`typescript

const limitOrder = await client.createLimitOrder({...})
const marketOrder = await client.createMarketOrder({...})

const feeAmount = client.calculateFee(limitOrder)
const feeAmount = client.calculateFee(marketOrder, pricePerShare)

`

#### Create and Submit a Limit Order

`typescript
import { OrderSide, LimitTimeInForce } from '@prob/clob'

const order = await client.createLimitOrder({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
price: 0.6,
size: 100,
side: OrderSide.Buy,
timeInForce: LimitTimeInForce.GTC,
})

const { orderId } = await client.postOrder(order)
console.log('Order created:', orderId)
`

#### Create and Submit a Market Order

`typescript
const marketOrder = await client.createMarketOrder({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
value: 100, // 100 USDT
side: OrderSide.Buy,
})

await client.postOrder(marketOrder)
`

#### Get Open Orders

`typescript
// Get all open orders for an event
const openOrders = await client.getOpenOrders({ eventId: '162' })

// Get open orders for specific tokens
const tokenOrders = await client.getOpenOrders({
tokenIds: [
'74342822607920627529671190134784974807193804148539661920621719393105547397621',
],
})

// Get a specific order
const order = await client.getOrder({
orderId: '123',
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
})
`

#### Cancel Orders

`typescript
// Cancel a single order
await client.cancelOrder({ orderId: '123', tokenId: '...' })

// Cancel multiple orders
await client.cancelOrders({
tokenId: '...',
orderIds: ['123', '456'],
})

// Cancel all orders
await client.cancelAllOrders({ eventId: '162' })
`

$3

#### Get Prices

`typescript
// Get current price for a token
const price = await client.getPrice({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
})

// Get prices for multiple tokens
const prices = await client.getPrices({
tokenIds: [
'74342822607920627529671190134784974807193804148539661920621719393105547397621',
'109502175175535116549611025410934749011537522542042437183890832452933730647182',
],
})

// Get price history
const priceHistory = await client.getPricesHistory({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
startTime: Date.now() - 86400000, // 24 hours ago
endTime: Date.now(),
})
`

#### Get Orderbook

`typescript
const orderbook = await client.getOrderBook({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
})
`

#### Get Midpoint Price

`typescript
const midpoint = await client.getMidpoint({
tokenId: '74342822607920627529671190134784974807193804148539661920621719393105547397621',
})
`

$3

#### Get Positions

`typescript
// Get current positions
const currentPositions = await client.getCurrentPositions({ eventId: '162' })

// Get closed positions
const closedPositions = await client.getClosedPositions({ eventId: '162' })

// Get pending positions
const pendingPositions = await client.getPendingPositions({ eventId: '162' })

// Get position value
const positionValue = await client.getPositionValue({ eventId: '162' })
`

#### Split Position

`typescript
const conditionId = '0x3614ed5aa3d8ab73edd3364541f8c1c48104aa7d0bb081ed51f0f634edd8dad9'
const txHash = await client.splitPosition({
conditionId,
formattedAmount: '1',
})
`

#### Merge Position

`typescript
const conditionId = '0x3614ed5aa3d8ab73edd3364541f8c1c48104aa7d0bb081ed51f0f634edd8dad9'
const mergeTxHash = await client.mergePosition({
conditionId,
formattedAmount: '1',
})
`

#### Redeem Position

`typescript
const conditionId = '0x3614ed5aa3d8ab73edd3364541f8c1c48104aa7d0bb081ed51f0f634edd8dad9'
const redeemTxHash = await client.redeemPosition({
conditionId,
})
`

$3

#### Get Trading Activity

`typescript
const activity = await client.getActivity({ eventId: '162' })
`

#### Get PnL (Profit and Loss)

`typescript
const pnl = await client.getPnL({ eventId: '162' })
`

#### Get Trades

`typescript
const trades = await client.getTrades({ eventId: '162' })
`

$3

#### Get Events

`typescript
const events = await client.getEvents({ limit: 10 })
`

#### Get Event by ID or Slug

`typescript
const event = await client.getEventById({ eventId: '162' })
const eventBySlug = await client.getEventBySlug({ slug: 'event-slug' })
`

#### Get Markets

`typescript
const markets = await client.getMarkets({ eventId: '162' })
const market = await client.getMarketById({ marketId: '123' })
`

#### Search

`typescript
const results = await client.search({ query: 'bitcoin' })
`

$3

#### Subscribe to Stream Data

`typescript
// Create client with wsUrl for WebSocket stream data
const client = createClobClient({
baseUrl: 'https://api.probable.markets/public/api/v1',
wsUrl: 'wss://ws.probable.markets/public/api/v1',
chainId: 56,
wallet: wallet,
})

await client.generateApiKey()

const subscription = client.subscribeStreamData('executionReport', (data) => {
console.log('Order ID:', data.i)
console.log('Status:', data.X)
console.log('Side:', data.S)
console.log('Token ID:', data.ct)
})

subscription.on('ready', (data) => {
console.log('WebSocket ready, listenKey:', data?.listenKey)
})

subscription.on('error', (error) => {
console.error('WebSocket error:', error)
})

subscription.on('authError', (error) => {
// if api key is wrong, will auto retry 3 times then emit this event
// if call reconnect it will continue retry 3 times, and pls ensure wallet & api key get is right.
console.error('Auth error:', error)
subscription.reconnect()
})

subscription.on('close', () => {
console.log('WebSocket closed')
})

subscription.unsubscribe()
`

Parameters:

- eventType: 'executionReport' - The type of event to subscribe to
- handler: (data: ExecutionReportEvent) => void - Callback function to handle events

Events:

- ready: Emitted when WebSocket is connected and authenticated. Returns { listenKey: string }
- error: Emitted when a WebSocket error occurs. Returns Error
- authError: Emitted when authentication fails after maximum retries. Returns Error
- close: Emitted when WebSocket connection is closed

Methods:

- unsubscribe(): Unsubscribe from the stream
- reconnect(): Manually reconnect the WebSocket, should ensure api key is right

Event Types:

##### ExecutionReportEvent

`typescript
interface ExecutionReportEvent {
e: 'executionReport' // Event type
E: number // Event time
T: number // Transaction time
u: number // Trade ID
c: string // Client order ID
S: 'BUY' | 'SELL' // Side
o: 'LIMIT' | 'MARKET' // Order type
f: 'GTC' | 'IOC' | 'FOK' // Time in force
x: 'NEW' | 'CANCELED' | 'REPLACED' | 'REJECTED' | 'TRADE' | 'EXPIRED' // Execution type
X: 'NEW' | 'PARTIALLY_FILLED' | 'FILLED' | 'CANCELED' | 'PENDING_CANCEL' | 'REJECTED' | 'EXPIRED' // Order status
i: number // Order ID
t?: number // Trade ID
m: boolean // Is maker
ot: string // Original order type
O: number // Price
ct: string // Token ID
}
`




$3

#### Check if Safe Proxy Wallet Exists

`typescript
const exists = await client.checkSafeProxyWalletExists()
`

#### Approve Collateral

`typescript
// Approve collateral if needed (checks current allowance first)
await client.proxyApproveCollateralIfNeeded()

// Approve specific amount
await client.proxyApproveCollateral(BigInt(1000e6))
`

#### Execute Transaction On Chain via Proxy

`typescript
const txHash = await client.proxyExecuteTx({
to: '0x...',
data: '0x...',
value: BigInt(0),
})
`

Development

$3

1. Clone the repository
2. Install dependencies: pnpm install
3. Build all packages: pnpm build

$3

- pnpm lint: Run Biome linter
- pnpm lint:fix: Fix linting issues automatically
- pnpm test: Run tests with Vitest
- pnpm test:watch: Run tests in watch mode
- pnpm build: Build all packages

$3

This project uses Biome for code formatting and linting. The configuration is in biome.jsonc.

$3

`bash


Build clob package

pnpm --filter ./packages/clob build

Build core package

pnpm --filter ./packages/core build
`

$3

`bash


Run all tests

pnpm test

Run tests for a specific package

pnpm --filter ./packages/clob test

Run tests in watch mode

pnpm test:watch
``