Skip to content
Polygolem

Architecture

Polygolem is a Go protocol and automation stack for Polymarket CLOB V2 with a thin Cobra-based CLI on top.

Three Layers

LayerPackagesRole
cmd/polygolem1Binary entry point. Wires Cobra and exits.
pkg/16Public Go SDK contracts. Gamma, Data API, and read-only CLOB DTOs use public pkg/types; authenticated CLOB account/order DTOs live in pkg/clob; contract registry/readiness lives in pkg/contracts; market WebSocket events use public pkg/stream DTOs; pkg/bookreader is deprecated in favor of pkg/orderbook; enrichment and rewards type paths still need cleanup.
internal/21Implementation. Not part of public API.

The CLI and public SDK both depend on the internal protocol implementation. The internal/ packages do not depend on cmd/.

Public SDK (pkg/)

PackagePurpose
pkg/universalSingle client for Gamma + CLOB + Data API + Discovery + Stream
pkg/gammaFull Gamma API surface — 26 methods (markets, events, tags, comments, profiles)
pkg/dataRead-only Data API analytics client returning pkg/types DTOs
pkg/typesPublic DTOs shared by SDK packages
pkg/clobCLOB market-data plus authenticated account/order DTOs
pkg/contractsPolygon contract registry and deposit-wallet bytecode checks
pkg/orderbookRead-only CLOB order-book reader
pkg/bookreaderDeprecated compatibility wrapper for pkg/orderbook
pkg/marketresolverMarket + token ID resolution
pkg/bridgeBridge API — supported assets, deposit addresses, quotes
pkg/relayerBuilder relayer primitives — wallet create, wallet batch, nonce, polling
pkg/streamPublic CLOB WebSocket market stream client
pkg/paginationCursor and offset pagination with concurrent batching

Internal Packages (internal/)

Protocol Clients

PackagePurpose
internal/gammaGamma HTTP client — 26 methods
internal/clobCLOB V2 client — 37 methods, EIP-712, POLY_1271, ERC-7739
internal/dataapiData API — positions, volume, leaderboards
internal/relayerBuilder relayer — WALLET-CREATE, WALLET batch, nonce, polling
internal/streamWebSocket market stream implementation behind pkg/stream
internal/rpcLow-level Polygon RPC helpers: bytecode checks, direct transfers, swaps, deploy estimates

Cross-Cutting

PackagePurpose
internal/authL0/L1/L2 auth, EIP-712, CREATE2 derivation, builder attribution, signers
internal/polytypesV2 protocol types and aliases — Gamma DTO aliases, CLOB data, enrichment, order payloads
internal/transportHTTP retry, rate limiter, circuit breaker, redaction
internal/configConfig loading, defaults, env binding, validation, redaction

Application

PackagePurpose
internal/cliCobra command construction
internal/walletDeposit wallet — derive, deploy, status, batch signing
internal/ordersOrderIntent, fluent builder, validation
internal/executionPaper executor + live executor surface
internal/marketdiscoveryGamma + CLOB enrichment service
internal/modesRead-only / paper / live mode gates
internal/riskPer-trade caps, daily loss limits, circuit breaker
internal/paperLocal paper positions and persisted state
internal/preflightReadiness checks
internal/outputTable + JSON rendering
internal/errorsStructured error types

Dependency Direction

cmd/polygolem
        |
internal/cli
        |
internal/{config, modes, preflight, output, errors}
        |
internal/{gamma, clob, dataapi, stream, relayer, rpc}   ← protocol clients
        |
internal/{auth, transport, polytypes}                   ← cross-cutting
        |
internal/{wallet, orders, execution, risk, paper, marketdiscovery}
        ^
        |
pkg/{universal, gamma, data, types, clob, contracts, stream, orderbook, bookreader, marketresolver, bridge, relayer, pagination}

Mode System

  • Read-only (default): public market data. No credentials needed.
  • Paper: local simulation. Never reaches authenticated endpoints.
  • Live: gated. Requires preflight + all four safety gates.

See Also