Skip to content

Architecture

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

Three Layers

Layer	Packages	Role
`cmd/polygolem`	1	Binary entry point. Wires Cobra and exits.
`pkg/`	21	Public 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`; V2 market WebSocket events use public `pkg/stream` DTOs; normalized live snapshots live in `pkg/marketdata`; `pkg/plugins` defines extensibility interfaces; `pkg/experimental/` hosts APIs staged for SDK promotion.
`internal/`	21	Implementation. 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/`)

Package	Purpose
`pkg/bridge`	Bridge API client — supported assets, deposit addresses, quotes
`pkg/builder`	Builder attribution and fee configuration for order placement
`pkg/clob`	CLOB market-data plus authenticated account/order DTOs
`pkg/contracts`	Polygon contract registry and deposit-wallet bytecode checks
`pkg/ctf`	Conditional Tokens Framework (CTF) helpers for position management
`pkg/data`	Read-only Data API analytics client returning `pkg/types` DTOs
`pkg/enabletrading`	Headless enable-trading flow: ClobAuth API keys and token approvals
`pkg/funding`	Deposit-wallet funding helpers (ERC-20 transfers and balance checks)
`pkg/gamma`	Full Gamma API surface — 26 methods (markets, events, tags, comments, profiles)
`pkg/marketdata`	Normalized live best bid, best ask, spread, midpoint, tick-size, last-trade, and book snapshots
`pkg/marketresolver`	Market + token ID resolution
`pkg/orderbook`	Read-only CLOB order-book reader
`pkg/orderresults`	Order result types and response parsing for placement outcomes
`pkg/pagination`	Cursor and offset pagination with concurrent batching
`pkg/plugins`	Plugin interfaces for market data and risk extensibility
`pkg/relayer`	Builder relayer primitives — wallet create, wallet batch, nonce, polling
`pkg/settlement`	V2 winner redemption planning, adapter calls, and readiness gates
`pkg/stream`	Public CLOB WebSocket market stream client, including V2 custom feature events
`pkg/types`	Public DTOs shared by SDK packages
`pkg/universal`	Single client for Gamma + CLOB + Data API + Discovery + Stream
`pkg/wallet`	Public deposit-wallet primitives — derive, deploy, status, batch signing

Experimental Packages

Package	Purpose
`pkg/experimental/orders`	Fluent `OrderIntent` builder and validation (staged for SDK promotion)
`pkg/experimental/auth`	EIP-712 domain helpers, signature type constants, and hex utilities (staged for SDK promotion)

Internal Packages (`internal/`)

Protocol Clients

Package	Purpose
`internal/gamma`	Gamma HTTP client — 26 methods
`internal/clob`	CLOB V2 client — 37 methods, EIP-712, POLY_1271, ERC-7739
`internal/dataapi`	Data API — positions, volume, leaderboards
`internal/relayer`	Builder relayer — WALLET-CREATE, WALLET batch, nonce, polling
`internal/stream`	WebSocket market stream implementation behind `pkg/stream`
`internal/rpc`	Low-level Polygon RPC helpers: bytecode checks, direct transfers, swaps, deploy estimates

Cross-Cutting

Package	Purpose
`internal/auth`	L0/L1/L2 auth, EIP-712, CREATE2 derivation, builder attribution, signers
`internal/polytypes`	V2 protocol types and aliases — Gamma DTO aliases, CLOB data, enrichment, order payloads
`internal/transport`	HTTP retry, rate limiter, circuit breaker, redaction
`internal/config`	Config loading, defaults, env binding, validation, redaction

Application

Package	Purpose
`internal/cli`	Cobra command construction
`internal/wallet`	Deposit wallet — derive, deploy, status, batch signing
`internal/orders`	OrderIntent, fluent builder, validation
`internal/execution`	Paper executor + live executor surface
`internal/marketdiscovery`	Gamma + CLOB enrichment service
`internal/modes`	Read-only / paper / live mode gates
`internal/risk`	Per-trade caps, daily loss limits, circuit breaker
`internal/paper`	Local paper positions and persisted state
`internal/preflight`	Readiness checks
`internal/output`	Table + JSON rendering
`internal/errors`	Structured 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/{bridge, builder, clob, contracts, ctf, data, enabletrading, funding, gamma, marketdata, marketresolver, orderbook, orderresults, pagination, plugins, relayer, settlement, stream, types, universal, wallet}

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

Go SDK Contracts — every public type and method signature
Internal Packages — full internal API surface
Safety Model — mode boundary enforcement
docs/ARCHITECTURE.md — canonical document