data

package
v1.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 29, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package data provides a read-only client for the Polymarket Data API.

Overview

The Data API exposes aggregated market analytics — positions, trades, activity, open interest, leaderboard rankings, and accounting snapshots. No authentication required; all endpoints use AuthNone.

Usage 

client := data.New(data.Config{})  // defaults to data-api.polymarket.com

// User positions
positions, _ := client.GetPositions(ctx, data.PositionParams{User: "0x..."})

// Trades
trades, _ := client.GetTrades(ctx, data.TradeParams{User: "0x...", Limit: 100})

// Open interest
oi, _ := client.GetOpenInterest(ctx, []string{"market1", "market2"})

// Download accounting snapshot (ZIP)
zipData, _ := client.DownloadAccountingSnapshot(ctx, "0x...")

Default host: https://data-api.polymarket.com

Index

Constants

View Source 
const DefaultHost = "https://data-api.polymarket.com"

Variables

This section is empty.

Functions

This section is empty.

Types

type Activity 

type Activity struct {
	// ProxyWallet is the user's Polymarket proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// Timestamp is when the activity occurred.
	Timestamp pmtypes.Int64 `json:"timestamp"`
	// ConditionID is the CTF condition identifier.
	ConditionID string `json:"conditionId"`
	// Type is the activity category.
	Type string `json:"type"`
	// Size is the token quantity.
	Size pmtypes.Float64 `json:"size"`
	// USDCSize is the USDC value.
	USDCSize pmtypes.Float64 `json:"usdcSize"`
	// TransactionHash is the on-chain transaction hash.
	TransactionHash string `json:"transactionHash"`
	// Price is the activity price.
	Price pmtypes.Float64 `json:"price"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// Side is the trade direction.
	Side string `json:"side"`
	// Title is the market question text.
	Title string `json:"title"`
	// Slug is the URL-friendly market slug.
	Slug string `json:"slug"`
	// Icon is the market icon URL.
	Icon string `json:"icon"`
	// EventSlug is the parent event slug.
	EventSlug string `json:"eventSlug"`
	// Outcome is the outcome label.
	Outcome string `json:"outcome"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

Activity describes a user activity event.

func (*Activity) UnmarshalJSON 

func (a *Activity) UnmarshalJSON(data []byte) error

type ActivityParams 

type ActivityParams struct {
	// User is the wallet address.
	User string
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
	// Start is the start Unix timestamp.
	Start int64
	// End is the end Unix timestamp.
	End int64
	// SortBy sets the sort field.
	SortBy string
	// SortDirection sets the sort order.
	SortDirection string
	// Side filters by trade direction.
	Side Side
	// ActivityTypes filters by event categories.
	ActivityTypes []string
}

ActivityParams filters GET /activity requests.

type BuilderLeaderboardEntry 

type BuilderLeaderboardEntry struct {
	Builder     string          `json:"builder"`
	Volume      pmtypes.Float64 `json:"volume"`
	Trades      pmtypes.Int     `json:"trades"`
	Rank        pmtypes.String  `json:"rank"`
	DisplayName string          `json:"displayName"`
}

BuilderLeaderboardEntry describes an aggregated builder leaderboard row.

type BuilderLeaderboardParams 

type BuilderLeaderboardParams struct {
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
}

BuilderLeaderboardParams filters GET /v1/builders/leaderboard requests.

type BuilderVolume 

type BuilderVolume struct {
	Date    string          `json:"date"`
	Builder string          `json:"builder"`
	Volume  pmtypes.Float64 `json:"volume"`
	Trades  pmtypes.Int     `json:"trades"`
}

BuilderVolume describes a daily builder volume time-series row.

type BuilderVolumeParams 

type BuilderVolumeParams struct {
	// Builder is the builder code.
	Builder string
	// Start is the start date.
	Start string
	// End is the end date.
	End string
}

BuilderVolumeParams filters GET /v1/builders/volume requests.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func New 

func New(config Config) *Client

New creates a Data API client.

func (*Client) DownloadAccountingSnapshot 

func (c *Client) DownloadAccountingSnapshot(ctx context.Context, user string) ([]byte, error)

DownloadAccountingSnapshot downloads the accounting snapshot ZIP for a user.

func (*Client) GetActivity 

func (c *Client) GetActivity(ctx context.Context, params ActivityParams) ([]Activity, error)

GetActivity returns user activity.

func (*Client) GetBuilderLeaderboard 

func (c *Client) GetBuilderLeaderboard(ctx context.Context, params BuilderLeaderboardParams) ([]BuilderLeaderboardEntry, error)

GetBuilderLeaderboard returns aggregated builder leaderboard rows.

func (*Client) GetBuilderVolume 

func (c *Client) GetBuilderVolume(ctx context.Context, params BuilderVolumeParams) ([]BuilderVolume, error)

GetBuilderVolume returns daily builder volume time-series rows.

func (*Client) GetClosedPositions 

func (c *Client) GetClosedPositions(ctx context.Context, params ClosedPositionParams) ([]ClosedPosition, error)

GetClosedPositions returns closed positions for a user.

func (*Client) GetHealth 

func (c *Client) GetHealth(ctx context.Context, out *Health) error

GetHealth writes the Data API health response into out.

func (*Client) GetHolders 

func (c *Client) GetHolders(ctx context.Context, params HoldersParams) ([]Holder, error)

GetHolders returns top holders for markets.

func (*Client) GetLeaderboard 

func (c *Client) GetLeaderboard(ctx context.Context, params LeaderboardParams) ([]LeaderboardEntry, error)

GetLeaderboard returns trader leaderboard rankings.

func (*Client) GetLiveVolume 

func (c *Client) GetLiveVolume(ctx context.Context, params LiveVolumeParams) ([]LiveVolume, error)

GetLiveVolume returns live volume for an event or markets.

func (*Client) GetMarketPositions 

func (c *Client) GetMarketPositions(ctx context.Context, params MarketPositionsParams) ([]MarketPositions, error)

GetMarketPositions returns positions grouped by outcome token for a market.

func (*Client) GetOpenInterest 

func (c *Client) GetOpenInterest(ctx context.Context, markets []string) ([]OpenInterest, error)

GetOpenInterest returns open interest for markets.

func (*Client) GetPositions 

func (c *Client) GetPositions(ctx context.Context, params PositionParams) ([]Position, error)

GetPositions returns current positions for a user.

func (*Client) GetTraded 

func (c *Client) GetTraded(ctx context.Context, user string, out *Traded) error

GetTraded writes the total markets a user has traded into out.

func (*Client) GetTrades 

func (c *Client) GetTrades(ctx context.Context, params TradeParams) ([]Trade, error)

GetTrades returns user or market trades.

func (*Client) GetValue 

func (c *Client) GetValue(ctx context.Context, user string, markets []string) ([]Value, error)

GetValue returns the total value of a user's positions.

func (*Client) Host 

func (c *Client) Host() string

Host returns the configured Data API host.

type ClosedPosition 

type ClosedPosition struct {
	// ProxyWallet is the user's Polymarket proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// ConditionID is the CTF condition identifier.
	ConditionID string `json:"conditionId"`
	// AvgPrice is the average entry price.
	AvgPrice pmtypes.Float64 `json:"avgPrice"`
	// RealizedPNL is the profit/loss.
	RealizedPNL pmtypes.Float64 `json:"realizedPnl"`
	// PercentRealizedPNL is the profit/loss percentage.
	PercentRealizedPNL pmtypes.Float64 `json:"percentRealizedPnl"`
	// CurPrice is the current market price.
	CurPrice pmtypes.Float64 `json:"curPrice"`
	// Timestamp is when the position was closed.
	Timestamp pmtypes.Int64 `json:"timestamp"`
	// Title is the market question text.
	Title string `json:"title"`
	// Slug is the URL-friendly market slug.
	Slug string `json:"slug"`
	// Icon is the market icon URL.
	Icon string `json:"icon"`
	// EventSlug is the parent event slug.
	EventSlug string `json:"eventSlug"`
	// Outcome is the outcome label.
	Outcome string `json:"outcome"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// OppositeOutcome is the complementary outcome label.
	OppositeOutcome string `json:"oppositeOutcome"`
	// OppositeAsset is the complementary token address.
	OppositeAsset string `json:"oppositeAsset"`
	// EndDate is the market resolution date.
	EndDate string `json:"endDate"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

ClosedPosition describes a closed user position.

func (*ClosedPosition) UnmarshalJSON 

func (p *ClosedPosition) UnmarshalJSON(data []byte) error

type ClosedPositionParams 

type ClosedPositionParams = PositionParams

ClosedPositionParams is an alias for PositionParams.

type Config 

type Config struct {
	Host       string
	HTTPClient *http.Client
	UserAgent  string
}

Config configures a Data API client.

type Health 

type Health struct {
	// Data is the health status string.
	Data string `json:"data"`
}

Health is the Data API health response.

type Holder 

type Holder struct {
	// ProxyWallet is the holder's proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// Amount is the token balance.
	Amount pmtypes.Float64 `json:"amount"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// Name is the display name.
	Name string `json:"name"`
	// ProfileImage is the profile image URL.
	ProfileImage string `json:"profileImage"`
	// Verified is true for verified accounts.
	Verified bool `json:"verified"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

Holder describes a market holder.

func (*Holder) UnmarshalJSON 

func (h *Holder) UnmarshalJSON(data []byte) error

type HoldersParams 

type HoldersParams struct {
	// Markets filters by condition IDs.
	Markets []string
	// Limit sets the maximum results.
	Limit int
	// MinBalance filters by minimum token balance.
	MinBalance int
}

HoldersParams filters GET /holders requests.

type LeaderboardEntry 

type LeaderboardEntry struct {
	// Rank is the leaderboard rank.
	Rank pmtypes.String `json:"rank"`
	// ProxyWallet is the user's proxy wallet address.
	ProxyWallet string `json:"proxyWallet"`
	// UserName is the display username.
	UserName string `json:"userName"`
	// Vol is the leaderboard volume.
	Vol pmtypes.Float64 `json:"vol"`
	// PNL is the leaderboard profit and loss.
	PNL pmtypes.Float64 `json:"pnl"`
	// ProfileImage is the user's profile image URL.
	ProfileImage string `json:"profileImage"`
	// XUsername is the user's X username.
	XUsername string `json:"xUsername"`
	// VerifiedBadge indicates whether the user has a verified badge.
	VerifiedBadge bool `json:"verifiedBadge"`
}

type LeaderboardParams 

type LeaderboardParams struct {
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
	// Category filters by leaderboard category.
	Category string
	// TimePeriod filters by time range.
	TimePeriod string
	// OrderBy sets the sort field.
	OrderBy string
}

LeaderboardParams filters GET /v1/leaderboard requests.

type LiveVolume 

type LiveVolume struct {
	// Market is the condition ID.
	Market string `json:"market"`
	// Volume is the total traded volume in USDC.
	Volume pmtypes.Float64 `json:"volume"`
}

LiveVolume describes live volume for an event or market.

type LiveVolumeParams 

type LiveVolumeParams struct {
	// Markets filters by condition IDs.
	Markets []string
}

LiveVolumeParams filters GET /live-volume requests.

type MarketPosition 

type MarketPosition struct {
	// ProxyWallet is the user's proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// Name is the display name.
	Name string `json:"name"`
	// ProfileImage is the profile image URL.
	ProfileImage string `json:"profileImage"`
	// Verified is true for verified accounts.
	Verified bool `json:"verified"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// ConditionID is the CTF condition identifier.
	ConditionID string `json:"conditionId"`
	// AvgPrice is the average entry price.
	AvgPrice pmtypes.Float64 `json:"avgPrice"`
	// Size is the position size.
	Size pmtypes.Float64 `json:"size"`
	// CurrPrice is the current market price.
	CurrPrice pmtypes.Float64 `json:"currPrice"`
	// CurrentValue is the current market value.
	CurrentValue pmtypes.Float64 `json:"currentValue"`
	// CashPNL is the realized profit/loss in USDC.
	CashPNL pmtypes.Float64 `json:"cashPnl"`
	// TotalBought is the total USDC spent.
	TotalBought pmtypes.Float64 `json:"totalBought"`
	// RealizedPNL is the realized profit/loss.
	RealizedPNL pmtypes.Float64 `json:"realizedPnl"`
	// TotalPNL is the total profit/loss.
	TotalPNL pmtypes.Float64 `json:"totalPnl"`
	// Outcome is the outcome label.
	Outcome string `json:"outcome"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

MarketPosition describes a user's position in a market outcome token.

func (*MarketPosition) UnmarshalJSON 

func (p *MarketPosition) UnmarshalJSON(data []byte) error

type MarketPositions 

type MarketPositions struct {
	// Token is the outcome token identifier.
	Token string `json:"token"`
	// Positions lists the user positions.
	Positions []MarketPosition `json:"positions"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

MarketPositions groups user positions for a single outcome token.

func (*MarketPositions) UnmarshalJSON 

func (p *MarketPositions) UnmarshalJSON(data []byte) error

type MarketPositionsParams 

type MarketPositionsParams struct {
	// Market is the condition ID.
	Market string
	// User is the wallet address.
	User string
	// Status filters by position status.
	Status string
	// SortBy sets the sort field.
	SortBy string
	// SortDirection sets the sort order.
	SortDirection string
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
}

MarketPositionsParams filters GET /v1/market-positions requests.

type OpenInterest 

type OpenInterest struct {
	// Market is the condition ID.
	Market string `json:"market"`
	// Value is the open interest in USDC.
	Value pmtypes.Float64 `json:"value"`
}

OpenInterest describes market open interest.

type Position 

type Position struct {
	// ProxyWallet is the user's Polymarket proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// ConditionID is the CTF condition identifier.
	ConditionID string `json:"conditionId"`
	// Size is the current position size.
	Size pmtypes.Float64 `json:"size"`
	// AvgPrice is the average entry price.
	AvgPrice pmtypes.Float64 `json:"avgPrice"`
	// InitialValue is the position cost in USDC.
	InitialValue pmtypes.Float64 `json:"initialValue"`
	// CurrentValue is the current market value.
	CurrentValue pmtypes.Float64 `json:"currentValue"`
	// CashPNL is the realized profit/loss in USDC.
	CashPNL pmtypes.Float64 `json:"cashPnl"`
	// PercentPNL is the realized profit/loss percentage.
	PercentPNL pmtypes.Float64 `json:"percentPnl"`
	// TotalBought is the total USDC spent.
	TotalBought pmtypes.Float64 `json:"totalBought"`
	// RealizedPNL is the realized profit/loss from sales.
	RealizedPNL pmtypes.Float64 `json:"realizedPnl"`
	// PercentRealizedPNL is the realized profit/loss percentage.
	PercentRealizedPNL pmtypes.Float64 `json:"percentRealizedPnl"`
	// CurPrice is the current market price.
	CurPrice pmtypes.Float64 `json:"curPrice"`
	// Redeemable is true when the position can be redeemed.
	Redeemable bool `json:"redeemable"`
	// Mergeable is true when positions can be merged.
	Mergeable bool `json:"mergeable"`
	// Title is the market question text.
	Title string `json:"title"`
	// Slug is the URL-friendly market slug.
	Slug string `json:"slug"`
	// Icon is the market icon URL.
	Icon string `json:"icon"`
	// EventSlug is the parent event slug.
	EventSlug string `json:"eventSlug"`
	// Outcome is the outcome label.
	Outcome string `json:"outcome"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// OppositeOutcome is the complementary outcome label.
	OppositeOutcome string `json:"oppositeOutcome"`
	// OppositeAsset is the complementary token address.
	OppositeAsset string `json:"oppositeAsset"`
	// EndDate is the market resolution date.
	EndDate string `json:"endDate"`
	// NegativeRisk is true for neg-risk markets.
	NegativeRisk bool `json:"negativeRisk"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

Position describes a current user position.

func (*Position) UnmarshalJSON 

func (p *Position) UnmarshalJSON(data []byte) error

type PositionParams 

type PositionParams struct {
	// User is the wallet address to query.
	User string
	// Markets filters by condition IDs.
	Markets []string
	// EventIDs filters by event IDs.
	EventIDs []int
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
	// SortBy sets the sort field.
	SortBy string
	// SortDirection sets the sort order.
	SortDirection string
	// Title filters by market title.
	Title string
	// Redeemable filters by redeemable status.
	Redeemable *bool
	// Mergeable filters by mergeable status.
	Mergeable *bool
	// SizeThreshold filters by minimum position size.
	SizeThreshold string
}

PositionParams filters GET /positions requests.

type Side 

type Side string

Side is the trade side. 

const (
	SideBuy  Side = "BUY"
	SideSell Side = "SELL"
)

type Trade 

type Trade struct {
	// ProxyWallet is the user's Polymarket proxy wallet.
	ProxyWallet string `json:"proxyWallet"`
	// User is the wallet address.
	User string `json:"user"`
	// Side is the trade direction.
	Side Side `json:"side"`
	// Asset is the ERC-1155 token address.
	Asset string `json:"asset"`
	// ConditionID is the CTF condition identifier.
	ConditionID string `json:"conditionId"`
	// Size is the trade quantity.
	Size pmtypes.Float64 `json:"size"`
	// Price is the execution price.
	Price pmtypes.Float64 `json:"price"`
	// Timestamp is when the trade occurred.
	Timestamp pmtypes.Int64 `json:"timestamp"`
	// Title is the market question text.
	Title string `json:"title"`
	// Slug is the URL-friendly market slug.
	Slug string `json:"slug"`
	// Icon is the market icon URL.
	Icon string `json:"icon"`
	// EventSlug is the parent event slug.
	EventSlug string `json:"eventSlug"`
	// Outcome is the outcome label.
	Outcome string `json:"outcome"`
	// OutcomeIndex is the 0-based index of the outcome.
	OutcomeIndex pmtypes.Int `json:"outcomeIndex"`
	// TransactionHash is the on-chain transaction hash.
	TransactionHash string `json:"transactionHash"`
	// Raw contains the unparsed JSON response.
	Raw json.RawMessage `json:"-"`
}

Trade describes a Data API trade.

func (*Trade) UnmarshalJSON 

func (t *Trade) UnmarshalJSON(data []byte) error

type TradeParams 

type TradeParams struct {
	// User is the wallet address.
	User string
	// Limit sets the maximum results.
	Limit int
	// Offset sets the start index.
	Offset int
	// TakerOnly filters to taker-side trades.
	TakerOnly *bool
	// Side filters by BUY or SELL.
	Side Side
}

TradeParams filters GET /trades requests.

type Traded 

type Traded struct {
	// User is the wallet address.
	User string `json:"user"`
	// Traded is the number of unique markets traded.
	Traded pmtypes.Int `json:"traded"`
}

Traded contains the total markets traded response.

type Value 

type Value struct {
	// User is the wallet address.
	User string `json:"user"`
	// Market is the condition ID.
	Market string `json:"market"`
	// Value is the total portfolio value.
	Value pmtypes.Float64 `json:"value"`
	// Cash is the USDC balance.
	Cash pmtypes.Float64 `json:"cash"`
	// Tokens is the token position value.
	Tokens pmtypes.Float64 `json:"tokens"`
}

Value describes user portfolio value for a market.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.