polymarket_dart

A Dart SDK for the Polymarket CLOB API — REST, WebSocket, EIP-712 signing, HMAC auth, on-chain approvals, and order management.

Features

53 CLOB API methods — markets, CLOB market info, orderbook, pricing, order management, rewards, auth
GammaClient — 22 methods for market/event discovery, tags, tag relationships, series, comments, sports, teams, profiles, and unified search (no auth required)
DataClient — 12 methods for positions, trades, activity, holders, leaderboard, builder analytics, and portfolio analytics
ComboClient — combo markets, user combo positions & activity, and the Level 2 maker quote flow (submit/cancel quote, Last Look confirm/decline)
QuoterGatewayClient — Quoter Gateway WebSocket for market makers (RFQ requests, signed quotes, Last Look)
RelayerClient — gasless relayer v2: transaction submit/lookup, recent transactions, nonce, API keys, and Deposit Wallet deployment
User + sports WebSocket channels — authenticated per-user order/trade updates, plus an unauthenticated live sports score feed
pUSD settlement calldata — split / merge / redeem / convert encoders for standard and neg-risk markets
EIP-712 signing — order signing for both EOA and GnosisSafe wallets
HMAC Level 2 auth — API key management and authenticated requests
On-chain approvals — EOA (direct Polygon RPC) and GnosisSafe (gasless relayer)
WebSocket — live orderbook, trades, RTDS price feeds
Pure Dart — no Flutter dependency, works in any Dart environment

Installation

Add to your pubspec.yaml:

dependencies:
  polymarket_dart: ^0.6.0

Then run:

dart pub get

Quick Start

import 'package:polymarket_dart/polymarket_dart.dart';

void main() async {
  // CLOB public API — no auth needed
  final client = ClobClient();
  final markets = await client.getMarkets();
  print(markets.data.first.question);
  client.close();

  // Market discovery via Gamma API — no auth needed
  final gamma = GammaClient();
  final topMarkets = await gamma.getMarkets(
    active: true,
    order: 'volume24hr',
    ascending: false,
    limit: 5,
  );
  print(topMarkets.first.question);
  gamma.close();
}

Usage

See docs/plan/GUIDES.md for detailed examples covering public market data, GammaClient discovery, DataClient analytics, EIP-712 API key creation, placing orders (EOA and GnosisSafe), on-chain approvals, and WebSocket subscriptions.

Prerequisites

EOA Trading

A Polygon wallet private key with MATIC for gas
pUSD on Polygon for trading collateral

Run on-chain approvals once before trading:

final wallet = PrivateKeyWalletAdapter('0x...');
await ensureEoaApprovals(wallet, onStatus: print);

GnosisSafe Trading

A GnosisSafe address funded with pUSD
Builder Program API credentials from polymarket.com/settings?tab=builder

Run gasless approvals once:

final relayer = RelayerClient(
  wallet: wallet,
  creds: BuilderCredentials(
    apiKey: '...',
    secret: '...',
    passphrase: '...',
  ),
);
await relayer.runApprovals(safeAddress);

Contract Addresses (Polygon)

Contract	Address
USDC (USDC.e)	`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
pUSD	`0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB`
Collateral Onramp	`0x93070a847efEf7F70739046A929D47a521F5B8ee`
Collateral Offramp	`0x2957922Eb93258b93368531d39fAcCA3B4dC5854`
CTF	`0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`
CTF Exchange V2	`0xE111180000d2663C0091e4f400237545B87B996B`
Neg Risk Exchange V2	`0xe2222d279d744050d28e00520010520000310F59`
Neg Risk Adapter	`0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296`

Testing

# Unit tests (no network)
dart test test/hmac_auth_test.dart test/eip712_test.dart

# CLOB public API
dart test test/clob_client_test.dart --tags integration

# Gamma API (market discovery)
dart test test/gamma_client_test.dart --tags gamma

# Combos / RFQ (live combo markets, positions, activity, maker endpoint)
dart test test/combo_client_integration_test.dart --tags combo

# Relayer v2 public endpoints (relay-payload / nonce, transaction lookup)
dart test test/relayer_integration_test.dart --tags relayer

# Settlement calldata reaches the real CTF / neg-risk contracts (read-only eth_call)
dart test test/settlement_integration_test.dart --tags integration

# Sports WebSocket (live scores)
dart test test/sports_websocket_integration_test.dart --tags sports

# Data API (user analytics)
dart test test/data_client_test.dart --tags data

# L2 auth (requires PRIVATE_KEY in .env)
dart test test/auth_test.dart --tags auth

# Approvals (requires PRIVATE_KEY in .env)
dart test test/approvals_test.dart --tags approvals

# pUSD live wrap/unwrap (requires PRIVATE_KEY, POL gas, and USDC.e)
dart test test/pusd_live_test.dart --tags pusd-live

# GnosisSafe relayer (requires BUILDER_* creds in .env)
dart test test/relayer_test.dart --tags relayer

# Full suite
dart test --tags integration

Create a .env file in the project root:

PRIVATE_KEY=0x...
PUSD_LIVE_TEST_AMOUNT=10000  # optional; base units, 10000 = 0.01 USDC.e/pUSD
FUNDER_ADDRESS=0x...          # GnosisSafe address
BUILDER_API_KEY=...
BUILDER_API_SECRET=...
BUILDER_API_PASSPHRASE=...

Dependencies

http — HTTP client
web_socket_channel — WebSocket
pointycastle — secp256k1 ECDSA, Keccak-256
crypto — HMAC-SHA256
convert — hex encoding

License

MIT