polymarket-client

polymarket-client

Go SDK for Polymarket — the decentralized prediction market platform on Polygon.

Features

• Complete CLOB v2 coverage — market data, order management, positions, RFQ (request-for-quote), rewards, builder APIs
• WebSocket support — live order book, price streams, and user order/trade events with auto-reconnect
• Three-tier auth — public (no auth), L1 (EIP-712 signatures), L2 (API key + passphrase + wallet signature)
• All Polymarket APIs — CLOB, Relayer, Data, Gamma, Bridge
• Zero live dependencies — all tests use httptest.NewServer, run entirely offline
• One external dependency — github.com/ethereum/go-ethereum only

Installation

go get github.com/bububa/polymarket-client

Requires Go 1.23+ (CI uses >=1.23.0; go.mod declares 1.22).

Quick Start

Read-Only (No Auth Required)

package main

import (
    "context"
    "fmt"

    "github.com/bububa/polymarket-client/clob"
)

func main() {
    client := clob.NewClient("") // defaults to CLOB v2 host

    // Fetch market data
    marketInfo := clob.ClobMarketInfo{ConditionID: "0xabc123"}
    if err := client.GetClobMarketInfo(context.Background(), &marketInfo); err != nil {
        panic(err)
    }
    fmt.Printf("Market: %s (negRisk=%v)\n", marketInfo.ConditionID, marketInfo.NegRisk)

    // Get order book (out must have AssetID set)
    book := clob.OrderBookSummary{AssetID: clob.String("token-id-here")}
    if err := client.GetOrderBook(context.Background(), &book); err != nil {
        panic(err)
    }
    fmt.Printf("Best bid: %v, Best ask: %v\n", book.Bids[0].Price, book.Asks[0].Price)
}

Trading (L2 Authentication Required)

The easiest way to trade is using the OrderBuilder, which handles price conversion, tick-size validation, and market option lookups automatically:

package main

import (
    "context"
    "fmt"

    "github.com/ethereum/go-ethereum/crypto"

    "github.com/bububa/polymarket-client/clob"
    "github.com/bububa/polymarket-client/internal/polyauth"
)

func main() {
    privateKey, _ := crypto.HexToECDSA("your-private-key-hex")

    client := clob.NewClient("",
        clob.WithCredentials(clob.Credentials{
            Key:        "your-api-key",
            Secret:     "your-api-secret",
            Passphrase: "your-api-passphrase",
        }),
        clob.WithSigner(polyauth.NewSigner(privateKey)),
        clob.WithChainID(clob.PolygonChainID), // 137
    )

    b := clob.NewOrderBuilder(client)

    // Place a limit order (auto-fetches tickSize and negRisk)
    resp, err := b.CreateAndPostOrderForToken(context.Background(), clob.OrderArgsV2{
        TokenID: "your-token-id",
        Price:   "0.50",   // price per share
        Size:    "10.0",   // number of shares
        Side:    clob.Buy,
    }, clob.GTC, nil)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Order placed: %s (success=%v)\n", resp.OrderID, resp.Success)
}

For advanced use cases (pre-fetched market options, custom tick-size handling):

b := clob.NewOrderBuilder(client)

// Advanced: manually supply tickSize and negRisk
args := clob.OrderArgsV2{
    TokenID: "your-token-id",
    Price:   "0.50",
    Size:    "10.0",
    Side:    clob.Buy,
}
opts := clob.CreateOrderOptions{TickSize: "0.01", NegRisk: false}

order, err := b.BuildOrder(args, opts)
if err != nil {
    panic(err)
}

// Then post manually
resp, err := b.CreateAndPostOrder(ctx, args, opts, clob.GTC, nil)

Note: OrderBuilder only constructs, validates, signs, and optionally submits orders. It does not check balance, allowance, or reserved open-order capacity. The caller is responsible for ensuring sufficient funds before posting.

Using Other APIs

// Data API — positions, trades, activity (no auth)
import "github.com/bububa/polymarket-client/data"

dataClient := data.New(data.Config{})
positions, _ := dataClient.GetPositions(ctx, data.PositionParams{User: "0x..."})

// Gamma API — events, markets search, tags (no auth)
import "github.com/bububa/polymarket-client/gamma"

gammaClient := gamma.New(gamma.Config{})
markets, _ := gammaClient.GetMarkets(ctx, gamma.MarketFilterParams{/* ... */})

// Relayer API — submit signed transactions (L1 auth via API key)
import "github.com/bububa/polymarket-client/relayer"

relayerClient := relayer.New(relayer.Config{
    Credentials: &relayer.Credentials{
        APIKey:  "...",
        Address: "0x...",
    },
})

// Bridge API — deposit, withdraw, bridge status (no auth)
import "github.com/bububa/polymarket-client/bridge"

bridgeClient := bridge.New(bridge.Config{})
assets, _ := bridgeClient.GetSupportedAssets(ctx, &bridge.SupportedAssetsResponse{})

Package Overview

Authentication

Polymarket uses three authentication levels:

L2 auth requires BOTH a polyauth.Signer (from your private key) AND Credentials (API key, secret, passphrase).

Creating API Keys

client := clob.NewClient("",
    clob.WithSigner(polyauth.NewSigner(privateKey)),
    clob.WithChainID(clob.PolygonChainID),
)

// Create new API key (L1 — wallet-signed)
var creds clob.Credentials
err := client.CreateAPIKey(ctx, nonce, &creds)
// Use returned credentials for L2 requests

CLOB Package

Market Data (No Auth)

Orders & Trading (AuthL2)

Auth & Account Management

OrderBuilder (Recommended for Trading)

The OrderBuilder provides a high-level API that automatically fetches tickSize and negRisk from the CLOB API, so you don't need to supply them:

b := clob.NewOrderBuilder(client)

// Limit order — auto-fetches tickSize + negRisk
resp, err := b.CreateAndPostOrderForToken(ctx, clob.OrderArgsV2{
    TokenID: "token-id",
    Price:   "0.50",
    Size:    "10.0",
    Side:    clob.Buy,
}, clob.GTC, nil)

// Market order — Amount is USDC for BUY, shares for SELL
resp, err := b.CreateAndPostMarketOrderForToken(ctx, clob.MarketOrderArgsV2{
    TokenID: "token-id",
    Price:   "0.50",   // worst-price limit
    Amount:  "100",    // BUY: USDC to spend / SELL: shares to sell
    Side:    clob.Buy,
}, clob.FOK, nil)

Token-based builders (auto-fetch market options, build + sign only):

// Build only (no submit)
order, err := b.BuildOrderForToken(ctx, clob.OrderArgsV2{...})
marketOrder, err := b.BuildMarketOrderForToken(ctx, clob.MarketOrderArgsV2{...})

Advanced builders (manually supply tickSize and negRisk):

args := clob.OrderArgsV2{TokenID: "...", Price: "0.50", Size: "10.0", Side: clob.Buy}
opts := clob.CreateOrderOptions{TickSize: "0.01", NegRisk: false}

order, err := b.BuildOrder(args, opts)
marketOrder, err := b.BuildMarketOrder(clob.MarketOrderArgsV2{...}, opts)
resp, err := b.CreateAndPostOrder(ctx, args, opts, clob.GTC, nil)
resp, err := b.CreateAndPostMarketOrder(ctx, mktArgs, opts, clob.FOK, nil)

Order types: GTC, GTD for limit orders; FOK, FAK for market orders.

deferExec (post-only) is only valid with GTC/GTD. Pairing it with FOK/FAK returns an error.

RFQ (Request for Quote) (AuthL2)

Rewards (AuthL2 + Public)

Builder APIs (AuthL2 + Public)

CTF On-Chain Helpers

WebSocket (clob/ws)

import "github.com/bububa/polymarket-client/clob/ws"

wsClient := ws.New(
    ws.WithHost(""), // defaults to production
    ws.WithAutoReconnect(true),
    // Optional: auth for user-channel subscriptions
    ws.WithCredentials(&clob.Credentials{
        Key:        "your-api-key",
        Secret:     "your-api-secret",
        Passphrase: "your-api-passphrase",
    }),
)
defer wsClient.Close()

// Connect to market channel (for order book, prices, etc.)
if err := wsClient.ConnectMarket(ctx); err != nil {
    panic(err)
}

// Subscribe to order book
err = wsClient.SubscribeOrderBook(ctx, []string{"token-id"})
// Subscribe to price changes
err = wsClient.SubscribePrices(ctx, []string{"token-id"})
// Subscribe to order updates (requires auth + ConnectUser)
err = wsClient.ConnectUser(ctx)
err = wsClient.SubscribeOrders(ctx, []string{"market-condition-id"})

// Read events
for event := range wsClient.Events() {
    fmt.Printf("Event: %+v\n", event)
}
// Read errors
for err := range wsClient.Errors() {
    fmt.Printf("Error: %v\n", err)
}

Market subscriptions (no auth): SubscribeOrderBook, SubscribePrices, SubscribeMidpoints, SubscribeLastTradePrice, SubscribeTickSizeChange, SubscribeBestBidAsk, SubscribeNewMarkets, SubscribeMarketResolutions.

User subscriptions (auth required, via ConnectUser): SubscribeUserEvents, SubscribeOrders, SubscribeTrades.

Each subscribe method accepts ctx context.Context and a slice of asset IDs (market) or market condition IDs (user).

WebSocket Real-Time Data (clob/ws/rtds)

The rtds subpackage provides WebSocket real-time data stream subscriptions for market data without needing the full CLOB client.

Development

# Build
go build -v ./...

# Run tests (all offline — httptest.NewServer)
go test -v ./...

# Tidy dependencies
go mod tidy

Test Files

License

MIT