Universal Client

The pkg/universal package provides a single client that wraps Gamma, CLOB, Data API, discovery enrichment, and the supported authenticated CLOB order surface.

Quick Start

import (
    "github.com/TrebuchetDynamics/polygolem/pkg/clob"
    sdkstream "github.com/TrebuchetDynamics/polygolem/pkg/stream"
    "github.com/TrebuchetDynamics/polygolem/pkg/types"
    "github.com/TrebuchetDynamics/polygolem/pkg/universal"
)

client := universal.NewClient(universal.Config{})

No credentials are needed for read-only operations. Authenticated methods take the EOA private key per call, derive CLOB L2 credentials, and sign locally. All methods are safe for concurrent use.

Market Discovery

// Search by keyword
results, _ := client.Search(ctx, &types.SearchParams{Q: "btc 5m"})

// Get active markets
markets, _ := client.ActiveMarkets(ctx)

// Get by ID or slug
market, _ := client.MarketByID(ctx, "0xbd31dc8a...")
market, _ := client.MarketBySlug(ctx, "will-btc-be-above")

// Keyset pagination
events, cursor, _ := client.EventsKeyset(ctx, &types.KeysetParams{Limit: 50})

Order Books & Pricing

// L2 order book
book, _ := client.OrderBook(ctx, "token-id")

// Best price per side
bid, _ := client.Price(ctx, "token-id", "BUY")
ask, _ := client.Price(ctx, "token-id", "SELL")

// Calculated values
mid, _ := client.Midpoint(ctx, "token-id")
spread, _ := client.Spread(ctx, "token-id")
lastPrice, _ := client.LastTradePrice(ctx, "token-id")

// OHLCV history
hist, _ := client.PricesHistory(ctx, &polytypes.PriceHistoryParams{
    Market:   "0x...",
    Interval: "1h",
})

// Batch operations
books, _ := client.OrderBooks(ctx, []polytypes.BookParams{{TokenID: "t1"}, {TokenID: "t2"}})
prices, _ := client.Prices(ctx, []polytypes.BookParams{{TokenID: "t1", Side: "BUY"}})

Market Enrichment (Gamma + CLOB)

// Active markets with CLOB details appended
enriched, _ := client.EnrichedMarkets(ctx, 50)
// Each includes: Market + TickSize + NegRisk + FeeRateBps + OrderBook + LastPrice + Midpoint + Spread

// Search and enrich in one call
results, _ := client.SearchAndEnrich(ctx, "btc 5m", 20)

// Enrich a single market
em, _ := client.EnrichMarket(ctx, someMarket)

Tags & Categories

tags, _ := client.Tags(ctx, &types.GetTagsParams{})
tag, _ := client.TagByID(ctx, "tag-id")
tag, _ := client.TagBySlug(ctx, "crypto")
related, _ := client.RelatedTagsByID(ctx, "tag-id")

Comments & Profiles

comments, _ := client.Comments(ctx, &types.CommentQuery{})
comment, _ := client.CommentByID(ctx, "comment-id")
userComments, _ := client.CommentsByUser(ctx, "0x...", 10)
profile, _ := client.PublicProfile(ctx, "0x...")

Volume & Leaderboards

vol, _ := client.LiveVolume(ctx, 10)
board, _ := client.TraderLeaderboard(ctx, 100)
positions, _ := client.CurrentPositions(ctx, "0x...")
holdings, _ := client.TopHolders(ctx, "token-id", 20)
interest, _ := client.OpenInterest(ctx, "token-id")

Authenticated CLOB

key, _ := client.CreateOrDeriveAPIKey(ctx, privateKey)
_ = key

balance, _ := client.BalanceAllowance(ctx, privateKey, clob.BalanceAllowanceParams{
    AssetType: "COLLATERAL",
})
_ = balance

order, _ := client.Order(ctx, privateKey, "0xorder-id")
_ = order

cancelled, _ := client.CancelOrders(ctx, privateKey, []string{"0xorder-id"})
_ = cancelled

Order placement is exposed as CreateLimitOrder and CreateMarketOrder. Polygolem’s supported live path is deposit wallet (signatureType = 3). After wallet deployment, create or derive the deposit-wallet-owned CLOB key with CreateOrDeriveAPIKeyForAddress or DeriveAPIKeyForAddress; private CLOB account methods and order placement use the deposit wallet as L2 POLY_ADDRESS.

Streams

marketStream := client.StreamClient()
marketStream.OnBook = func(msg sdkstream.BookMessage) { /* handle orderbook update */ }
marketStream.OnPriceChange = func(msg sdkstream.PriceChangeMessage) { /* handle price change */ }
marketStream.OnLastTrade = func(msg sdkstream.LastTradeMessage) { /* handle trade */ }
marketStream.Connect(ctx)

Configuration

// Production defaults
client := universal.NewClient(universal.Config{})

// Custom endpoints
client := universal.NewClient(universal.Config{
    GammaBaseURL: "https://gamma-api.polymarket.com",
    CLOBBaseURL:  "https://clob.polymarket.com",
    DataBaseURL:  "https://data-api.polymarket.com",
    BuilderCode:  "0x...", // optional V2 order attribution bytes32
})

// Default config for reference
cfg := universal.DefaultConfig()

When to Use

Use pkg/universal when you need to query multiple Polymarket APIs from one client. Use the individual packages (pkg/gamma, pkg/clob, pkg/orderbook, etc.) when you only need one API and want minimal dependencies.

For deposit-wallet deployment, approvals, and other relayer wallet lifecycle operations, use the CLI. Those commands are still internal implementation surfaces, not public SDK contracts.