polybrainz_polymarket 1.0.0

A comprehensive Dart wrapper for the Polymarket API including Gamma, CLOB, Data APIs and WebSocket streams.

polybrainz_polymarket

A comprehensive Dart SDK for the Polymarket prediction market APIs.

Features

• Gamma API - Market discovery, events, tags, comments, profiles, search
• CLOB API - Order book, pricing, order management, trade history
• Data API - Positions, trades, activity, holders, leaderboard
• WebSocket - Real-time order book updates, price changes, user notifications
• Authentication - L1 (EIP-712) and L2 (HMAC-SHA256) authentication support
• Type-safe - Full Dart type safety with JSON serialization
• Error handling - Comprehensive exception hierarchy and Result types

Installation

Add to your pubspec.yaml:

dependencies:
  polybrainz_polymarket: ^1.0.0

Then run:

dart pub get

Quick Start

Public Client (No Authentication)

import 'package:polybrainz_polymarket/polybrainz_polymarket.dart';

void main() async {
  // Create a public client
  final client = PolymarketClient.public();

  // Get active events
  final events = await client.gamma.events.listEvents(
    limit: 10,
    closed: false,
  );

  for (final event in events) {
    print('${event.title} - ${event.markets.length} markets');
  }

  // Get order book for a token
  final book = await client.clob.orderbook.getOrderBook('your-token-id');
  print('Best bid: ${book.bestBid}, Best ask: ${book.bestAsk}');

  // Clean up
  client.close();
}

Authenticated Client (For Trading)

import 'package:polybrainz_polymarket/polybrainz_polymarket.dart';

void main() async {
  // Create an authenticated client
  final client = PolymarketClient.authenticated(
    credentials: ApiCredentials(
      apiKey: 'your-api-key',
      secret: 'your-secret',
      passphrase: 'your-passphrase',
    ),
    funder: '0xYourWalletAddress',
  );

  // Get your open orders
  final orders = await client.clob.orders.getOpenOrders();
  print('You have ${orders.length} open orders');

  // Get your positions
  final positions = await client.data.positions.getPositions(
    userAddress: '0xYourWalletAddress',
  );

  for (final pos in positions) {
    print('${pos.title}: ${pos.size} shares @ ${pos.avgPrice}');
  }

  client.close();
}

Real-Time Data with WebSocket

import 'package:polybrainz_polymarket/polybrainz_polymarket.dart';

void main() async {
  final client = PolymarketClient.public();

  // Connect to WebSocket
  await client.clobWebSocket.connect();

  // Subscribe to price changes
  client.clobWebSocket.subscribeToPriceChanges(['token-id-1', 'token-id-2'])
    .listen((msg) {
      for (final change in msg.priceChanges) {
        print('${change.assetId}: ${change.price}');
      }
    });

  // Subscribe to order book updates
  client.clobWebSocket.subscribeToOrderBook('token-id')
    .listen((book) {
      print('Best bid: ${book.bestBid}, Best ask: ${book.bestAsk}');
    });

  // For crypto prices
  await client.rtdsWebSocket.connect(topics: [RtdsTopic.cryptoPrices]);
  client.rtdsWebSocket.cryptoPrices.listen((msg) {
    print('BTC: ${msg.getPrice('BTC')}, ETH: ${msg.getPrice('ETH')}');
  });
}

API Reference

PolymarketClient

The main entry point for all API access.

Factory	Description
PolymarketClient.public()	Public client, no authentication
PolymarketClient.authenticated()	Authenticated client with API credentials
PolymarketClient.withPrivateKey()	Client with private key for deriving credentials

Gamma API (Market Discovery)

// Events
final events = await client.gamma.events.listEvents(limit: 100, closed: false);
final event = await client.gamma.events.getById(123);
final event = await client.gamma.events.getBySlug('event-slug');

// Markets
final markets = await client.gamma.markets.listMarkets(active: true);
final market = await client.gamma.markets.getByConditionId('condition-id');

// Tags
final tags = await client.gamma.tags.listTags();
final related = await client.gamma.tags.getRelatedTags(tagId);

// Search
final results = await client.gamma.search.search(query: 'bitcoin');

// Profiles
final profile = await client.gamma.profiles.getByAddress('0x...');

// Comments
final comments = await client.gamma.comments.listComments(
  parentEntityType: ParentEntityType.market,
  parentEntityId: 123,
);

CLOB API (Order Book & Trading)

// Order Book
final book = await client.clob.orderbook.getOrderBook('token-id');
final books = await client.clob.orderbook.getOrderBooks(['token-1', 'token-2']);

// Pricing
final price = await client.clob.pricing.getPrice('token-id', OrderSide.buy);
final midpoint = await client.clob.pricing.getMidpoint('token-id');
final spread = await client.clob.pricing.getSpread('token-id');
final history = await client.clob.pricing.getPriceHistory('token-id');

// Orders (requires authentication)
final response = await client.clob.orders.postOrder(signedOrder);
final orders = await client.clob.orders.getOpenOrders();
await client.clob.orders.cancelOrder('order-id');
await client.clob.orders.cancelAllOrders();

// Trades
final trades = await client.clob.trades.getTrades(market: 'condition-id');

Data API (Analytics)

// Positions
final positions = await client.data.positions.getPositions(
  userAddress: '0x...',
  sortBy: SortBy.value,
  sortDirection: SortDirection.desc,
);
final closed = await client.data.positions.getClosedPositions(userAddress: '0x...');

// Trades
final trades = await client.data.trades.getUserTrades(userAddress: '0x...');
final marketTrades = await client.data.trades.getMarketTrades(conditionId: 'cond-id');

// Activity
final activity = await client.data.activity.getUserActivity(
  userAddress: '0x...',
  types: [ActivityType.trade, ActivityType.redeem],
);

// Holders
final holders = await client.data.holders.getTokenHolders(tokenId: 'token-id');

// Portfolio Value
final value = await client.data.value.getValue('0x...');
print('Total: ${value.totalValue}, PnL: ${value.totalPnl}');

// Leaderboard
final leaders = await client.data.leaderboard.getLeaderboard(
  window: LeaderboardWindow.day7,
  type: LeaderboardType.profit,
);

WebSocket Streams

// CLOB WebSocket
await client.clobWebSocket.connect();

// Market data (public)
client.clobWebSocket.subscribeToMarket(['token-id']);
client.clobWebSocket.bookUpdates.listen((book) => print(book));
client.clobWebSocket.priceChanges.listen((price) => print(price));
client.clobWebSocket.lastTradePrices.listen((trade) => print(trade));

// User data (requires auth)
client.clobWebSocket.subscribeToUser(['token-id']);
client.clobWebSocket.userOrders.listen((order) => print(order));
client.clobWebSocket.userTrades.listen((trade) => print(trade));

// RTDS WebSocket
await client.rtdsWebSocket.connect(topics: [RtdsTopic.cryptoPrices, RtdsTopic.comments]);
client.rtdsWebSocket.cryptoPrices.listen((msg) => print(msg));
client.rtdsWebSocket.comments.listen((comment) => print(comment));

Authentication

Using Existing API Credentials

If you already have API credentials:

final client = PolymarketClient.authenticated(
  credentials: ApiCredentials(
    apiKey: 'your-api-key',
    secret: 'your-secret',
    passphrase: 'your-passphrase',
  ),
  funder: '0xYourWalletAddress',
);

Deriving API Credentials (Requires web3dart)

To create or derive API credentials from a private key, you'll need to implement EIP-712 signing using a library like web3dart:

final client = PolymarketClient.withPrivateKey(
  privateKey: '0xYourPrivateKey',
  walletAddress: '0xYourWalletAddress',
);

// This requires proper EIP-712 implementation
// await client.clob.auth.createOrDeriveApiKey();

Note: L1 authentication (EIP-712 signing) is implemented as a placeholder. For production use, integrate with web3dart or a similar Ethereum signing library.

Error Handling

The SDK provides typed exceptions for different error scenarios:

try {
  final orders = await client.clob.orders.getOpenOrders();
} on AuthenticationException catch (e) {
  print('Auth error: ${e.message}');
} on RateLimitException catch (e) {
  print('Rate limited, retry after: ${e.retryAfter}');
} on ApiException catch (e) {
  print('API error ${e.statusCode}: ${e.message}');
} on NetworkException catch (e) {
  print('Network error: ${e.message}');
} on PolymarketException catch (e) {
  print('Error: ${e.message}');
}

Key Concepts

Token IDs vs Condition IDs

• Condition ID: Identifies a market (e.g., "Will X happen?")
• Token ID: Identifies a specific outcome token (Yes or No)
• A market has ONE condition ID but TWO token IDs

Order Types

Type	Description
GTC	Good Till Cancelled - rests on book until filled or cancelled
GTD	Good Till Date - expires at specified timestamp
FOK	Fill or Kill - must fill completely immediately or cancel
FAK	Fill and Kill (IOC) - fill what you can, cancel rest

Negative Risk

Some markets support "negative risk" where Yes + No tokens can be merged/split for capital efficiency. Check the negRisk field on markets.

Examples

See the example directory for complete examples:

• Basic Usage - Simple API calls
• WebSocket Streaming - Real-time data
• Trading - Order management

API Documentation

• Polymarket Gamma API
• Polymarket CLOB API
• Polymarket Data API

License

MIT License - see LICENSE for details.