Skip to content
Polygolem

Go SDK Contracts

Public packages for consumption by go-bot and other Go projects. This page records the current exported contract: packages, methods, and the exact types in their signatures.

Sections marked planned describe the public SDK contract that downstream code should target next, but that is not part of the generated command surface until the matching package lands.

The internal/ packages are implementation detail. They are documented in Internal Packages, but they do not carry the same semver promise as the pkg/ packages below.

Some current pkg/ method signatures still expose implementation types from internal/polytypes and a few relayer/auth aliases. That is an SDK hygiene gap, not an upstream Polymarket requirement. Gamma, Data API, CLOB market/account/order DTOs, and market WebSocket DTOs have been promoted: pkg/gamma, pkg/data, pkg/clob, pkg/stream, and the corresponding methods on pkg/universal return public package types.

pkg/orderbook — Read-Only Order Book

import "github.com/TrebuchetDynamics/polygolem/pkg/orderbook"

Contract: Reader interface

type Reader interface {
    OrderBook(ctx context.Context, tokenID string) (OrderBook, error)
}

Contract: OrderBook struct

type OrderBook struct {
    MarketID       string
    TokenID        string
    Bids           []Level
    Asks           []Level
    LastTradePrice float64
}

Contract: Level struct

type Level struct {
    Price float64
    Size  float64
}

Contract: Constructor

func NewReader(clobBaseURL string) Reader

pkg/bookreader — Deprecated Order Book Alias

import "github.com/TrebuchetDynamics/polygolem/pkg/bookreader"

pkg/bookreader remains for source compatibility and aliases pkg/orderbook types plus NewReader. New consumers should import pkg/orderbook.

pkg/clob — CLOB Market Data & Account Orders

import "github.com/TrebuchetDynamics/polygolem/pkg/clob"

Contract: Constructors

type Client struct { /* unexported fields */ }


type Config struct {
    BaseURL string
    BuilderCode string
}


func NewClient(cfg Config) *Client
func DefaultConfig() Config

Contract: Methods

func (c *Client) Health(ctx context.Context) error
func (c *Client) ServerTime(ctx context.Context) (*types.CLOBServerTime, error)
func (c *Client) Markets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) Market(ctx context.Context, conditionID string) (*types.CLOBMarket, error)
func (c *Client) OrderBook(ctx context.Context, tokenID string) (*types.CLOBOrderBook, error)
func (c *Client) OrderBooks(ctx context.Context, params []types.CLOBBookParams) ([]types.CLOBOrderBook, error)
func (c *Client) Price(ctx context.Context, tokenID, side string) (string, error)
func (c *Client) Prices(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)
func (c *Client) Midpoint(ctx context.Context, tokenID string) (string, error)
func (c *Client) Midpoints(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)
func (c *Client) Spread(ctx context.Context, tokenID string) (string, error)
func (c *Client) TickSize(ctx context.Context, tokenID string) (*types.CLOBTickSize, error)
func (c *Client) NegRisk(ctx context.Context, tokenID string) (*types.CLOBNegRiskInfo, error)
func (c *Client) FeeRateBps(ctx context.Context, tokenID string) (int, error)
func (c *Client) LastTradePrice(ctx context.Context, tokenID string) (string, error)
func (c *Client) LastTradesPrices(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)
func (c *Client) PricesHistory(ctx context.Context, params *types.CLOBPriceHistoryParams) (*types.CLOBPriceHistory, error)
func (c *Client) SimplifiedMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) SamplingMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) SamplingSimplifiedMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)

Contract: Authenticated CLOB Methods

func (c *Client) CreateOrDeriveAPIKey(ctx context.Context, privateKey string) (APIKey, error)
func (c *Client) CreateOrDeriveAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (APIKey, error)
func (c *Client) CreateAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (APIKey, error)
func (c *Client) DeriveAPIKey(ctx context.Context, privateKey string) (APIKey, error)
func (c *Client) DeriveAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (APIKey, error)
func (c *Client) CreateBuilderFeeKey(ctx context.Context, privateKey string) (APIKey, error)
func (c *Client) ListBuilderFeeKeys(ctx context.Context, privateKey string) ([]BuilderFeeKeyRecord, error)
func (c *Client) RevokeBuilderFeeKey(ctx context.Context, privateKey, builderKey string) error
func (c *Client) BalanceAllowance(ctx context.Context, privateKey string, params BalanceAllowanceParams) (*BalanceAllowanceResponse, error)
func (c *Client) UpdateBalanceAllowance(ctx context.Context, privateKey string, params BalanceAllowanceParams) (*BalanceAllowanceResponse, error)
func (c *Client) ListOrders(ctx context.Context, privateKey string) ([]OrderRecord, error)
func (c *Client) Order(ctx context.Context, privateKey, orderID string) (*OrderRecord, error)
func (c *Client) ListTrades(ctx context.Context, privateKey string) ([]TradeRecord, error)
func (c *Client) CancelOrder(ctx context.Context, privateKey, orderID string) (*CancelOrdersResponse, error)
func (c *Client) CancelOrders(ctx context.Context, privateKey string, orderIDs []string) (*CancelOrdersResponse, error)
func (c *Client) CancelAll(ctx context.Context, privateKey string) (*CancelOrdersResponse, error)
func (c *Client) CancelMarket(ctx context.Context, privateKey string, params CancelMarketParams) (*CancelOrdersResponse, error)
func (c *Client) CreateLimitOrder(ctx context.Context, privateKey string, params CreateOrderParams) (*OrderPlacementResponse, error)
func (c *Client) CreateBatchOrders(ctx context.Context, privateKey string, params []CreateOrderParams) (*BatchOrderResponse, error)
func (c *Client) CreateMarketOrder(ctx context.Context, privateKey string, params MarketOrderParams) (*OrderPlacementResponse, error)
func (c *Client) Heartbeat(ctx context.Context, privateKey, heartbeatID string) error
func (c *Client) AutoHeartbeat(ctx context.Context, privateKey string, interval time.Duration) context.CancelFunc

Contract: Authenticated CLOB DTOs

type APIKey struct
type BalanceAllowanceParams struct
type BalanceAllowanceResponse struct
type CreateOrderParams struct
type MarketOrderParams struct
type OrderPlacementResponse struct
type BatchOrderResponse struct
type CancelOrdersResponse struct
type CancelMarketParams struct
type OrderRecord struct
type TradeRecord struct
type BuilderFeeKeyRecord struct

pkg/stream — Public Market WebSocket

import "github.com/TrebuchetDynamics/polygolem/pkg/stream"

Contract: Constructors

type MarketClient struct { /* unexported fields */ }


type Config struct {
    URL               string
    PingInterval      time.Duration
    PongTimeout       time.Duration
    Reconnect         bool
    ReconnectDelay    time.Duration
    ReconnectMaxDelay time.Duration
    ReconnectMax      int
}


func NewMarketClient(cfg Config) *MarketClient
func DefaultConfig(url string) Config
func NewDeduplicator(size int, ttl time.Duration) *Deduplicator

Contract: Methods

func (c *MarketClient) Connect(ctx context.Context) error
func (c *MarketClient) SubscribeAssets(ctx context.Context, assetIDs []string) error
func (c *MarketClient) Close()
func (c *MarketClient) IsConnected() bool


func (d *Deduplicator) Process(data []byte) bool
func (d *Deduplicator) Reset()
func (d *Deduplicator) Stats() (in, dup, out int64)

Contract: Event DTOs

type BookMessage struct
type PriceLevel struct
type PriceChangeMessage struct
type PriceChangeEntry struct
type LastTradeMessage struct

pkg/stream is public market data only. Authenticated user streams are not part of this contract.

pkg/gamma — Read-Only Market Metadata

import "github.com/TrebuchetDynamics/polygolem/pkg/gamma"

Contract: Constructors

type Client struct { /* unexported fields */ }


func NewClient(baseURL string) *Client
func DefaultConfig(baseURL string) transport.Config

Contract: Methods

func (c *Client) HealthCheck(ctx context.Context) (*types.HealthResponse, error)
func (c *Client) ActiveMarkets(ctx context.Context) ([]types.Market, error)
func (c *Client) Markets(ctx context.Context, params *types.GetMarketsParams) ([]types.Market, error)
func (c *Client) MarketByID(ctx context.Context, id string) (*types.Market, error)
func (c *Client) MarketBySlug(ctx context.Context, slug string) (*types.Market, error)
func (c *Client) Events(ctx context.Context, params *types.GetEventsParams) ([]types.Event, error)
func (c *Client) EventByID(ctx context.Context, id string) (*types.Event, error)
func (c *Client) EventBySlug(ctx context.Context, slug string) (*types.Event, error)
func (c *Client) Series(ctx context.Context, params *types.GetSeriesParams) ([]types.Series, error)
func (c *Client) SeriesByID(ctx context.Context, id string) (*types.Series, error)
func (c *Client) Search(ctx context.Context, params *types.SearchParams) (*types.SearchResponse, error)
func (c *Client) Tags(ctx context.Context, params *types.GetTagsParams) ([]types.Tag, error)
func (c *Client) TagByID(ctx context.Context, id string) (*types.Tag, error)
func (c *Client) TagBySlug(ctx context.Context, slug string) (*types.Tag, error)
func (c *Client) RelatedTagsByID(ctx context.Context, tagID string) ([]types.TagRelationship, error)
func (c *Client) RelatedTagsBySlug(ctx context.Context, slug string) ([]types.TagRelationship, error)
func (c *Client) Teams(ctx context.Context, params *types.GetTeamsParams) ([]types.Team, error)
func (c *Client) SportsMetadata(ctx context.Context) ([]types.SportMetadata, error)
func (c *Client) Comments(ctx context.Context, params *types.CommentQuery) ([]types.Comment, error)
func (c *Client) CommentByID(ctx context.Context, id string) (*types.Comment, error)
func (c *Client) CommentsByUser(ctx context.Context, userAddress string, limit int) ([]types.Comment, error)
func (c *Client) PublicProfile(ctx context.Context, walletAddress string) (*types.Profile, error)
func (c *Client) SportsMarketTypes(ctx context.Context) ([]types.SportsMarketType, error)
func (c *Client) MarketByToken(ctx context.Context, tokenID string) (*types.MarketByTokenResponse, error)
func (c *Client) EventsKeyset(ctx context.Context, params *types.KeysetParams) ([]types.Event, string, error)
func (c *Client) MarketsKeyset(ctx context.Context, params *types.KeysetParams) ([]types.Market, string, error)

pkg/types — Public DTOs

import "github.com/TrebuchetDynamics/polygolem/pkg/types"

Contract: Data API DTOs

type Position struct
type ClosedPosition struct
type Trade struct
type Activity struct
type Holder struct
type PortfolioValue struct
type TotalMarketsTraded struct
type OpenInterest struct
type LeaderboardRow struct
type LiveVolumeRow struct
type LiveVolumeResponse struct

These types are intentionally public so SDK consumers do not need to import or name internal/dataapi.

Contract: Gamma DTOs

type HealthResponse struct
type Market struct
type Event struct
type Category struct
type Tag struct
type Series struct
type Collection struct
type EventCreator struct
type Team struct
type SportMetadata struct
type TagRelationship struct
type SearchTag struct
type Profile struct
type SearchResponse struct
type GetMarketsParams struct
type GetEventsParams struct
type GetSeriesParams struct
type GetTagsParams struct
type SearchParams struct
type GetTeamsParams struct
type Comment struct
type CommentQuery struct
type KeysetParams struct
type MarketByTokenResponse struct

These types are intentionally public so SDK consumers do not need to import or name internal/polytypes for Gamma market discovery.

Contract: CLOB Read DTOs

type CLOBServerTime struct
type CLOBOrderBook struct
type CLOBOrderBookLevel struct
type CLOBTickSize struct
type CLOBNegRiskInfo struct
type CLOBFeeDetails struct
type CLOBMarket struct
type CLOBToken struct
type CLOBPaginatedMarkets struct
type CLOBBookParams struct
type CLOBPricePoint struct
type CLOBPriceHistory struct
type CLOBPriceHistoryParams struct

These types are intentionally public so SDK consumers do not need to import or name internal/polytypes for read-only CLOB market data. The SDK normalizes compact V2 fields from /clob-markets/{condition_id} and numeric/string price payloads into stable Go DTO fields.

pkg/data — Read-Only Data API Analytics

import "github.com/TrebuchetDynamics/polygolem/pkg/data"

Contract: Constructors

type Client struct { /* unexported fields */ }


type Config struct {
    BaseURL string
}


func NewClient(cfg Config) *Client
func DefaultConfig() Config

Contract: Methods

func (c *Client) Health(ctx context.Context) error
func (c *Client) CurrentPositions(ctx context.Context, user string) ([]types.Position, error)
func (c *Client) CurrentPositionsWithLimit(ctx context.Context, user string, limit int) ([]types.Position, error)
func (c *Client) ClosedPositions(ctx context.Context, user string) ([]types.ClosedPosition, error)
func (c *Client) ClosedPositionsWithLimit(ctx context.Context, user string, limit int) ([]types.ClosedPosition, error)
func (c *Client) Trades(ctx context.Context, user string, limit int) ([]types.Trade, error)
func (c *Client) Activity(ctx context.Context, user string, limit int) ([]types.Activity, error)
func (c *Client) TopHolders(ctx context.Context, tokenID string, limit int) ([]types.Holder, error)
func (c *Client) TotalValue(ctx context.Context, user string) (*types.PortfolioValue, error)
func (c *Client) MarketsTraded(ctx context.Context, user string) (*types.TotalMarketsTraded, error)
func (c *Client) OpenInterest(ctx context.Context, tokenID string) (*types.OpenInterest, error)
func (c *Client) TraderLeaderboard(ctx context.Context, limit int) ([]types.LeaderboardRow, error)
func (c *Client) LiveVolume(ctx context.Context, limit int) (*types.LiveVolumeResponse, error)

pkg/settlement — V2 Winner Redemption

import "github.com/TrebuchetDynamics/polygolem/pkg/settlement"

go-bot must consume settlement through this SDK package, not by shelling out to the CLI. The package turns Data API redeemable=true positions into deposit-wallet WALLET calls that target the V2 collateral adapters. It does not expose raw CTF, direct EOA, SAFE, or PROXY redeem routes for deposit-wallet positions.

Contract: Types

type RedeemablePosition struct {
    TokenID      string
    ConditionID  string
    Size         float64
    Outcome      string
    NegativeRisk bool
    EndDate      string
    Title        string
    Slug         string
}


type RedeemResult struct {
    TransactionID string
    State         string
    Wallet        string
    Nonce         string
    Deadline      string
    CallCount     int
    Redeemed      []RedeemablePosition
}


const DefaultBatchLimit = 10

Contract: Functions

func FindRedeemable(ctx context.Context, dataClient *data.Client, owner string) ([]RedeemablePosition, error)
func BuildRedeemCall(p RedeemablePosition) (relayer.DepositWalletCall, error)
func SubmitRedeem(ctx context.Context, rc *relayer.Client, privateKey string, positions []RedeemablePosition, limit int) (*RedeemResult, error)

BuildRedeemCall reuses the legacy redeemPositions(address,bytes32,bytes32,uint256[]) calldata shape but targets CtfCollateralAdapter or NegRiskCtfCollateralAdapter. The adapter uses conditionId and ignores the caller-supplied collateral address, parent collection, and indexSets. The relayer submission remains a deposit-wallet WALLET batch; SAFE/PROXY examples from other wallet types are not interchangeable.

SubmitRedeem dedupes positions by conditionId, caps the batch at limit calls (defaulting to DefaultBatchLimit = 10 when limit <= 0), signs the EIP-712 WALLET batch, and submits via the relayer. When the relayer rejects with an allowlist error (HTTP 400 “not in the allowed list” / “are not permitted” / “call blocked”), the returned error wraps relayer.ErrRelayerAllowlistBlocked. Callers must errors.Is, verify the adapter constants against Polymarket’s current contracts reference, and stop if the constants are current. The V2 deposit-wallet redeem path is non-negotiable; there is no fallback to attempt.

result, err := settlement.SubmitRedeem(ctx, rc, privateKey, positions, settlement.DefaultBatchLimit)
if err != nil {
    if errors.Is(err, relayer.ErrRelayerAllowlistBlocked) {
        // Verify the contract registry, then stop if it is current.
        return err
    }
    return err
}

pkg/universal — All Market Data, One Client

import "github.com/TrebuchetDynamics/polygolem/pkg/universal"

Contract: Client struct

type Client struct { /* unexported fields */ }

Contract: Config struct

type Config struct {
    GammaBaseURL string
    CLOBBaseURL  string
    DataBaseURL  string
    BuilderCode  string
}

Contract: Constructors

func NewClient(cfg Config) *Client
func DefaultConfig() Config

Contract: Methods — Gamma (12 methods)

func (c *Client) ActiveMarkets(ctx context.Context) ([]types.Market, error)
func (c *Client) Markets(ctx context.Context, params *types.GetMarketsParams) ([]types.Market, error)
func (c *Client) MarketByID(ctx context.Context, id string) (*types.Market, error)
func (c *Client) MarketBySlug(ctx context.Context, slug string) (*types.Market, error)
func (c *Client) Events(ctx context.Context, params *types.GetEventsParams) ([]types.Event, error)
func (c *Client) EventByID(ctx context.Context, id string) (*types.Event, error)
func (c *Client) EventBySlug(ctx context.Context, slug string) (*types.Event, error)
func (c *Client) Search(ctx context.Context, params *types.SearchParams) (*types.SearchResponse, error)
func (c *Client) Series(ctx context.Context, params *types.GetSeriesParams) ([]types.Series, error)
func (c *Client) Tags(ctx context.Context, params *types.GetTagsParams) ([]types.Tag, error)
func (c *Client) SportsMetadata(ctx context.Context) ([]types.SportMetadata, error)
func (c *Client) Comments(ctx context.Context, params *types.CommentQuery) ([]types.Comment, error)

Contract: Methods — Extended Gamma (15 methods)

func (c *Client) GammaMarketBySlug(ctx context.Context, slug string) (*types.Market, error)
func (c *Client) GammaEventBySlug(ctx context.Context, slug string) (*types.Event, error)
func (c *Client) SeriesByID(ctx context.Context, id string) (*types.Series, error)
func (c *Client) TagByID(ctx context.Context, id string) (*types.Tag, error)
func (c *Client) TagBySlug(ctx context.Context, slug string) (*types.Tag, error)
func (c *Client) RelatedTagsByID(ctx context.Context, tagID string) ([]types.TagRelationship, error)
func (c *Client) RelatedTagsBySlug(ctx context.Context, slug string) ([]types.TagRelationship, error)
func (c *Client) Teams(ctx context.Context, params *types.GetTeamsParams) ([]types.Team, error)
func (c *Client) CommentByID(ctx context.Context, id string) (*types.Comment, error)
func (c *Client) CommentsByUser(ctx context.Context, userAddress string, limit int) ([]types.Comment, error)
func (c *Client) PublicProfile(ctx context.Context, walletAddress string) (*types.Profile, error)
func (c *Client) SportsMarketTypes(ctx context.Context) ([]types.SportsMarketType, error)
func (c *Client) MarketByToken(ctx context.Context, tokenID string) (*types.MarketByTokenResponse, error)
func (c *Client) EventsKeyset(ctx context.Context, params *types.KeysetParams) ([]types.Event, string, error)
func (c *Client) MarketsKeyset(ctx context.Context, params *types.KeysetParams) ([]types.Market, string, error)

Contract: Methods — CLOB Order Books (12 methods)

func (c *Client) OrderBook(ctx context.Context, tokenID string) (*types.CLOBOrderBook, error)
func (c *Client) OrderBooks(ctx context.Context, params []types.CLOBBookParams) ([]types.CLOBOrderBook, error)
func (c *Client) Price(ctx context.Context, tokenID, side string) (string, error)
func (c *Client) Prices(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)
func (c *Client) Midpoint(ctx context.Context, tokenID string) (string, error)
func (c *Client) Midpoints(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)
func (c *Client) Spread(ctx context.Context, tokenID string) (string, error)
func (c *Client) TickSize(ctx context.Context, tokenID string) (*types.CLOBTickSize, error)
func (c *Client) NegRisk(ctx context.Context, tokenID string) (*types.CLOBNegRiskInfo, error)
func (c *Client) FeeRateBps(ctx context.Context, tokenID string) (int, error)
func (c *Client) LastTradePrice(ctx context.Context, tokenID string) (string, error)
func (c *Client) LastTradesPrices(ctx context.Context, params []types.CLOBBookParams) (map[string]string, error)

Contract: Methods — CLOB Markets (7 methods)

func (c *Client) PricesHistory(ctx context.Context, params *types.CLOBPriceHistoryParams) (*types.CLOBPriceHistory, error)
func (c *Client) CLOBMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) CLOBMarket(ctx context.Context, conditionID string) (*types.CLOBMarket, error)
func (c *Client) SimplifiedMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) SamplingMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) SamplingSimplifiedMarkets(ctx context.Context, nextCursor string) (*types.CLOBPaginatedMarkets, error)
func (c *Client) HealthCheck(ctx context.Context) (HealthResponse, error)

Contract: Methods — CLOB Account, Orders, and Trading (20 methods)

func (c *Client) CreateOrDeriveAPIKey(ctx context.Context, privateKey string) (clob.APIKey, error)
func (c *Client) CreateOrDeriveAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (clob.APIKey, error)
func (c *Client) CreateAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (clob.APIKey, error)
func (c *Client) DeriveAPIKey(ctx context.Context, privateKey string) (clob.APIKey, error)
func (c *Client) DeriveAPIKeyForAddress(ctx context.Context, privateKey, ownerAddress string) (clob.APIKey, error)
func (c *Client) CreateBuilderFeeKey(ctx context.Context, privateKey string) (clob.APIKey, error)
func (c *Client) BalanceAllowance(ctx context.Context, privateKey string, params clob.BalanceAllowanceParams) (*clob.BalanceAllowanceResponse, error)
func (c *Client) UpdateBalanceAllowance(ctx context.Context, privateKey string, params clob.BalanceAllowanceParams) (*clob.BalanceAllowanceResponse, error)
func (c *Client) CreateLimitOrder(ctx context.Context, privateKey string, params clob.CreateOrderParams) (*clob.OrderPlacementResponse, error)
func (c *Client) CreateBatchOrders(ctx context.Context, privateKey string, params []clob.CreateOrderParams) (*clob.BatchOrderResponse, error)
func (c *Client) CreateMarketOrder(ctx context.Context, privateKey string, params clob.MarketOrderParams) (*clob.OrderPlacementResponse, error)
func (c *Client) Heartbeat(ctx context.Context, privateKey, heartbeatID string) error
func (c *Client) AutoHeartbeat(ctx context.Context, privateKey string, interval time.Duration) context.CancelFunc
func (c *Client) ListOrders(ctx context.Context, privateKey string) ([]clob.OrderRecord, error)
func (c *Client) Order(ctx context.Context, privateKey, orderID string) (*clob.OrderRecord, error)
func (c *Client) ListTrades(ctx context.Context, privateKey string) ([]clob.TradeRecord, error)
func (c *Client) CancelOrder(ctx context.Context, privateKey, orderID string) (*clob.CancelOrdersResponse, error)
func (c *Client) CancelOrders(ctx context.Context, privateKey string, orderIDs []string) (*clob.CancelOrdersResponse, error)
func (c *Client) CancelMarket(ctx context.Context, privateKey string, params clob.CancelMarketParams) (*clob.CancelOrdersResponse, error)
func (c *Client) CancelAll(ctx context.Context, privateKey string) (*clob.CancelOrdersResponse, error)

CreateMarketOrder currently supports buy-side budgeted market orders. Use CreateLimitOrder for sell-side limit orders until sell-side market order support is promoted into the public contract.

Contract: Methods — CLOB Metadata, Scoring, and Rewards (10 methods)

func (c *Client) CLOBServerTime(ctx context.Context) (*types.CLOBServerTime, error)
func (c *Client) OrderScoring(ctx context.Context, orderID string) (bool, error)
func (c *Client) OrdersScoring(ctx context.Context, orderIDs []string) ([]bool, error)
func (c *Client) RewardsConfig(ctx context.Context) ([]polytypes.RewardsConfig, error)
func (c *Client) RawRewards(ctx context.Context, market string) ([]polytypes.RawRewards, error)
func (c *Client) UserEarnings(ctx context.Context, date string) ([]polytypes.UserEarnings, error)
func (c *Client) TotalEarnings(ctx context.Context, date string) (*polytypes.TotalEarnings, error)
func (c *Client) RewardPercentages(ctx context.Context) ([]polytypes.RewardPercentages, error)
func (c *Client) UserRewardsByMarket(ctx context.Context, params *polytypes.UserRewardsByMarketRequest) ([]polytypes.UserRewardsMarket, error)
func (c *Client) RebatedFees(ctx context.Context) ([]polytypes.RebatedFees, error)

Contract: Methods — Data API (12 methods)

func (c *Client) CurrentPositions(ctx context.Context, user string) ([]types.Position, error)
func (c *Client) CurrentPositionsWithLimit(ctx context.Context, user string, limit int) ([]types.Position, error)
func (c *Client) ClosedPositions(ctx context.Context, user string) ([]types.ClosedPosition, error)
func (c *Client) ClosedPositionsWithLimit(ctx context.Context, user string, limit int) ([]types.ClosedPosition, error)
func (c *Client) Trades(ctx context.Context, user string, limit int) ([]types.Trade, error)
func (c *Client) Activity(ctx context.Context, user string, limit int) ([]types.Activity, error)
func (c *Client) TopHolders(ctx context.Context, tokenID string, limit int) ([]types.Holder, error)
func (c *Client) TotalValue(ctx context.Context, user string) (*types.PortfolioValue, error)
func (c *Client) MarketsTraded(ctx context.Context, user string) (*types.TotalMarketsTraded, error)
func (c *Client) OpenInterest(ctx context.Context, tokenID string) (*types.OpenInterest, error)
func (c *Client) TraderLeaderboard(ctx context.Context, limit int) ([]types.LeaderboardRow, error)
func (c *Client) LiveVolume(ctx context.Context, limit int) (*types.LiveVolumeResponse, error)

Contract: Utilities

type HealthResponse struct {
    GammaOK bool `json:"gamma_ok"`
    CLOBOK  bool `json:"clob_ok"`
    DataOK  bool `json:"data_ok"`
}


func DefaultTransportConfig(baseURL string) transport.Config

Contract: Methods — Discovery + Stream (5 methods)

func (c *Client) EnrichedMarkets(ctx context.Context, limit int) ([]polytypes.EnrichedMarket, error)
func (c *Client) SearchAndEnrich(ctx context.Context, query string, limit int) ([]polytypes.EnrichedMarket, error)
func (c *Client) EnrichMarket(ctx context.Context, market types.Market) (*polytypes.EnrichedMarket, error)
func (c *Client) StreamClient() *stream.MarketClient
func (c *Client) StreamClientWithConfig(cfg stream.Config) *stream.MarketClient

pkg/marketresolver — Token ID Resolution

import "github.com/TrebuchetDynamics/polygolem/pkg/marketresolver"

Contract: Types

type Resolver struct { /* unexported */ }
type MarketStatus string  // "available" | "unavailable" | "stale_token" | "unresolved"


type ResolveResult struct {
    Status      MarketStatus `json:"status"`
    UpTokenID   string       `json:"up_token_id"`
    DownTokenID string       `json:"down_token_id"`
    ConditionID string       `json:"condition_id"`
    Asset       string       `json:"asset"`
    Timeframe   string       `json:"timeframe"`
    Source      string       `json:"source"`
}


type CryptoMarket struct {
    ConditionID, Asset, Timeframe string
    UpTokenID, DownTokenID        string
    Accepting, Closed             bool
    Question, Slug                string
}

Contract: Methods

func NewResolver(gammaBaseURL string) *Resolver
func (r *Resolver) ResolveCryptoMarkets(ctx context.Context, asset string) ([]CryptoMarket, error)
func (r *Resolver) ResolveTokenIDs(ctx context.Context, asset, timeframe string) ResolveResult
func (r *Resolver) ValidateToken(ctx context.Context, tokenID string) MarketStatus

Planned Exact-Window Extension

Live trading callers should move to a strict resolver that carries market startDate/endDate through the result and returns window_mismatch when the matched market does not start at the requested decision window:

func (r *Resolver) ResolveTokenIDsForWindow(ctx context.Context, asset, timeframe string, windowStart time.Time) ResolveResult

This is the guard required to prevent a 5m strategy signal from buying a future 5m market with the same asset and timeframe.

pkg/bridge — Cross-Chain Deposits

import "github.com/TrebuchetDynamics/polygolem/pkg/bridge"

Contract: Methods

func NewClient(baseURL string, tc *transport.Client) *Client
func (c *Client) GetSupportedAssets(ctx context.Context) (*SupportedAssetsResponse, error)
func (c *Client) CreateDepositAddress(ctx context.Context, address string) (*CreateDepositAddressResponse, error)
func (c *Client) GetDepositStatus(ctx context.Context, depositAddress string) (*DepositStatusResponse, error)
func (c *Client) GetQuote(ctx context.Context, req QuoteRequest) (*QuoteResponse, error)

pkg/builder — Builder Header Signing

import "github.com/TrebuchetDynamics/polygolem/pkg/builder"

Contract: Types and Functions

const POLY_BUILDER_API_KEY = "POLY_BUILDER_API_KEY"
const POLY_BUILDER_PASSPHRASE = "POLY_BUILDER_PASSPHRASE"
const POLY_BUILDER_TIMESTAMP = "POLY_BUILDER_TIMESTAMP"
const POLY_BUILDER_SIGNATURE = "POLY_BUILDER_SIGNATURE"


type Signer interface {
    CreateHeaders(method, path string, body *string, timestamp *int64) (map[string]string, error)
}


type LocalSignerConfig struct { Key, Secret, Passphrase string }
type RemoteSignerConfig struct { URL, Token string }


func NewLocalSigner(config LocalSignerConfig) (*LocalSigner, error)
func NewRemoteSigner(config RemoteSignerConfig) (*RemoteSigner, error)
func GenSignature(secret string, timestamp int64, method, path string, body *string) string

pkg/ctf — Conditional Tokens Helpers

import "github.com/TrebuchetDynamics/polygolem/pkg/ctf"

Contract: Functions

var USDC common.Address


func SplitPositionData(collateral common.Address, parentCollectionID, conditionID common.Hash, partition []*big.Int, amount *big.Int) ([]byte, error)
func MergePositionsData(collateral common.Address, parentCollectionID, conditionID common.Hash, partition []*big.Int, amount *big.Int) ([]byte, error)
func RedeemPositionsData(collateral common.Address, parentCollectionID, conditionID common.Hash, indexSets []*big.Int) ([]byte, error)
func PositionID(collateral common.Address, collectionID common.Hash) common.Hash
func CollectionID(parentCollectionID, conditionID common.Hash, indexSet *big.Int) common.Hash

These helpers only build calldata and deterministic IDs. They do not submit transactions, bypass deposit-wallet gates, or perform split/merge/redeem execution.

pkg/contracts — Polygon Contract Registry and Code Checks

import "github.com/TrebuchetDynamics/polygolem/pkg/contracts"

Contract: Constants and Types

const PolygonChainID = 137
const PolygonRPC = "https://polygon-bor-rpc.publicnode.com"
const DepositWalletFactory = "0x00000000000Fb5C9ADea0298D729A0CB3823Cc07"
const CTFExchangeV2 = "0xE111180000d2663C0091e4f400237545B87B996B"
const NegRiskExchangeV2 = "0xe2222d279d744050d28e00520010520000310F59"
const NegRiskAdapterV2 = "0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296"
// V2 collateral adapters — split/merge/redeem from a deposit wallet
// must route through these.
const CtfCollateralAdapter = "0xAdA100Db00Ca00073811820692005400218FcE1f"
const NegRiskCtfCollateralAdapter = "0xadA2005600Dec949baf300f4C6120000bDB6eAab"
// V2 collateral ramps — convert between USDC/USDC.e and pUSD.
const CollateralOnramp  = "0x93070a847efEf7F70739046A929D47a521F5B8ee"
const CollateralOfframp = "0x2957922Eb93258b93368531d39fAcCA3B4dC5854"
const PermissionedRamp  = "0xebC2459Ec962869ca4c0bd1E06368272732BCb08"
const PUSD = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
const CTF = "0x4D97DCd97eC945f40cF65F87097ACe5EA0476045"


type Registry struct {
    ChainID int
    DepositWalletFactory string
    ProxyFactory string
    GnosisSafeFactory string
    CTFExchangeV2 string
    NegRiskExchangeV2 string
    NegRiskAdapterV2 string
    CtfCollateralAdapter string
    NegRiskCtfCollateralAdapter string
    CollateralOnramp string
    CollateralOfframp string
    PermissionedRamp string
    PUSD string
    CTF string
}


type DeploymentStatus struct {
    Address string
    Deployed bool
    Source string
}

Contract: Functions

func PolygonMainnet() Registry
func ContractDeployed(ctx context.Context, address string, rpcURL string) (DeploymentStatus, error)
func DepositWalletDeployed(ctx context.Context, depositWallet string, rpcURL string) (DeploymentStatus, error)
func RedeemAdapterFor(negRisk bool) string

DepositWalletDeployed uses Polygon eth_getCode and is the source of truth when relayer /deployed returns a false negative. POLY_1271 order validation depends on the wallet’s bytecode existing on-chain.

RedeemAdapterFor(negRisk bool) returns the V2 collateral adapter address that a deposit wallet must call redeemPositions on for the given market kind. The adapter pulls the wallet’s CTF position tokens, redeems through legacy ConditionalTokens with USDC.e, wraps proceeds back into pUSD, and sends pUSD to the wallet. The adapter ignores caller-supplied collateralToken, parentCollectionId, and indexSets; only conditionId is used.

pkg/relayer — Builder Relayer and Deposit Wallet Onboard

import "github.com/TrebuchetDynamics/polygolem/pkg/relayer"

Contract: Re-exported Types

type Client = internalrelayer.Client
type BuilderConfig = auth.BuilderConfig
type PrivateKeySigner = auth.PrivateKeySigner
type RelayerTransaction = internalrelayer.RelayerTransaction
type RelayerTransactionState = internalrelayer.RelayerTransactionState
type DepositWalletCall = internalrelayer.DepositWalletCall
type NonceResponse = internalrelayer.NonceResponse
type DeployedResponse = internalrelayer.DeployedResponse
type V2APIKey = internalrelayer.V2APIKey


type OnboardOptions struct {
    SkipDeploy bool
    SkipApprove bool
    DeployPollMaxAttempts int
    DeployPollInterval time.Duration
    ApprovalDeadlineSeconds int64
}


type OnboardDeployResult struct {
    TransactionID string
    State string
    Skipped bool
    AlreadyDeployed bool
}


type OnboardApprovalResult struct {
    TransactionID string
    State string
    Nonce string
    Deadline string
    CallCount int
    Skipped bool
}


type OnboardResult struct {
    Owner string
    DepositWallet string
    Deploy *OnboardDeployResult
    Approve *OnboardApprovalResult
    NextSteps []string
}

Contract: Error Sentinels

var ErrRelayerAllowlistBlocked = internalrelayer.ErrRelayerAllowlistBlocked

ErrRelayerAllowlistBlocked is wrapped via errors.Join by every relayer submission method (SubmitWalletCreate, SubmitWalletBatch) when the relayer rejects with one of three known markers: not in the allowed list, are not permitted, or call blocked. Detect with errors.Is and surface as a structured stop: verify local contract constants against Polymarket’s current contracts reference, then stop if they are current. There is no safe fallback for V2 deposit-wallet positions.

Contract: Constructors and Helpers

func New(baseURL string, bc BuilderConfig, chainID int64) (*Client, error)
func NewV2(baseURL string, key V2APIKey, chainID int64) (*Client, error)
func NewSigner(privateKeyHex string, chainID int64) (*PrivateKeySigner, error)
func BuildApprovalCalls() []DepositWalletCall
func BuildAdapterApprovalCalls() []DepositWalletCall
func BuildAdapterApprovalCallsJSON() (string, error)
func BuildDeadline(secondsFromNow int64) string
func SignWalletBatch(signer *PrivateKeySigner, walletAddress, nonce, deadline string, calls []DepositWalletCall) (string, error)
func OnboardDepositWallet(ctx context.Context, client *Client, privateKey string, opts OnboardOptions) (*OnboardResult, error)
func DepositWalletCodeDeployed(ctx context.Context, depositWallet string, rpcURL string) (bool, error) // deprecated: use pkg/contracts

BuildApprovalCalls returns the six trading approvals (pUSD + CTF for CTFExchangeV2, NegRiskExchangeV2, NegRiskAdapterV2). BuildAdapterApprovalCalls returns the four redeem-readiness approvals (pUSD approve + CTF setApprovalForAll for CtfCollateralAdapter and NegRiskCtfCollateralAdapter). Both batches are idempotent.

Contract: Client Methods

func (c *Client) SubmitWalletCreate(ctx context.Context, ownerAddress string) (*RelayerTransaction, error)
func (c *Client) SubmitWalletBatch(ctx context.Context, ownerAddress, walletAddress, nonce, signature, deadline string, calls []DepositWalletCall) (*RelayerTransaction, error)
func (c *Client) GetNonce(ctx context.Context, ownerAddress string) (string, error)
func (c *Client) GetTransaction(ctx context.Context, txID string) (*RelayerTransaction, error)
func (c *Client) PollTransaction(ctx context.Context, txID string, maxAttempts int, interval time.Duration) (*RelayerTransaction, error)
func (c *Client) IsDeployed(ctx context.Context, ownerAddress string) (bool, error)

OnboardDepositWallet derives the deposit-wallet address, deploys it through the relayer when needed, polls the deploy transaction, and submits the standard six-call pUSD + CTF approval batch. It does not transfer pUSD or bypass live execution gates; callers must fund and preflight explicitly before live trading.

pkg/pagination — Cursor & Offset Helpers

import "github.com/TrebuchetDynamics/polygolem/pkg/pagination"

Contract: Functions

func CollectAll[T any](ctx context.Context, fn CursorPageFunc[T]) ([]T, error)
func CollectOffset[T any](ctx context.Context, fn OffsetPageFunc[T], pageSize int) ([]T, error)
func Batch[T, R any](ctx context.Context, items []T, concurrency int, fn BatchFunc[T, R]) ([]R, error)

Known Public SDK Gaps

The following are intentional gaps in the current stable pkg/ contract:

GapCurrent Status
Public type ownershipGamma, Data API, and read-only CLOB DTOs are public in pkg/types; authenticated CLOB account/trading DTOs are public in pkg/clob; market WebSocket DTOs are public in pkg/stream; rewards, enrichment, and user-stream signatures still need promotion work before claiming a fully clean external SDK
Authenticated user WebSocket streamPublic market stream is exposed; user stream waits for L2 WebSocket auth tests
Consolidated V2 CLOB market infoTick size, neg-risk, and fee-rate are separate calls today

See Also