Module Polymarket_data.ClientSource

Data API client for positions, trades, activity, and leaderboards.

include module type of Types

Query Parameter Enums

Sourcemodule Sort_direction : sig ... end
Sourcemodule Position_sort_by : sig ... end
Sourcemodule Filter_type : sig ... end
Sourcemodule Activity_sort_by : sig ... end
Sourcemodule Closed_position_sort_by : sig ... end
Sourcemodule Time_period : sig ... end
Sourcemodule Leaderboard_category : sig ... end
Sourcemodule Leaderboard_order_by : sig ... end

Domain Enums

Sourcemodule Activity_type : sig ... end

Response Types

Sourcetype health_response = {
  1. data : string;
}

Health check response

Sourceval yojson_of_health_response : health_response -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval health_response_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> health_response

Structured error type for all API errors (alias to Polymarket_http.Client.error)

Sourceval error_to_string : error -> string

Convert error to human-readable string

Sourceval pp_error : Format.formatter -> error -> unit

Pretty printer for errors

Domain Models

Sourcetype position = {
  1. proxy_wallet : Polymarket_common.Primitives.Address.t;
  2. asset : string;
  3. condition_id : Polymarket_common.Primitives.Hash64.t;
  4. size : float;
  5. avg_price : float;
  6. initial_value : float;
  7. current_value : float;
  8. cash_pnl : float;
  9. percent_pnl : float;
  10. total_bought : float;
  11. realized_pnl : float;
  12. percent_realized_pnl : float;
  13. cur_price : float;
  14. redeemable : bool;
  15. mergeable : bool;
  16. title : string;
  17. slug : string;
  18. icon : string;
  19. event_slug : string;
  20. outcome : string;
  21. outcome_index : int;
  22. opposite_outcome : string;
  23. opposite_asset : string;
  24. end_date : string;
  25. negative_risk : bool;
  26. event_id : string;
}

Position in a market

Sourcetype closed_position = {
  1. proxy_wallet : Polymarket_common.Primitives.Address.t;
  2. asset : string;
  3. condition_id : Polymarket_common.Primitives.Hash64.t;
  4. avg_price : float;
  5. total_bought : float;
  6. realized_pnl : float;
  7. cur_price : float;
  8. timestamp : int64;
  9. title : string;
  10. slug : string;
  11. icon : string;
  12. event_slug : string;
  13. outcome : string;
  14. outcome_index : int;
  15. opposite_outcome : string;
  16. opposite_asset : string;
  17. end_date : string;
}

Closed position in a market

Sourceval yojson_of_closed_position : closed_position -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval closed_position_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> closed_position
Sourcetype trade = {
  1. proxy_wallet : Polymarket_common.Primitives.Address.t;
  2. side : Side.t;
  3. asset : string;
  4. condition_id : Polymarket_common.Primitives.Hash64.t;
  5. size : float;
  6. price : float;
  7. timestamp : int64;
  8. title : string;
  9. slug : string;
  10. icon : string;
  11. event_slug : string;
  12. outcome : string;
  13. outcome_index : int;
  14. name : string;
  15. pseudonym : string;
  16. bio : string;
  17. profile_image : string;
  18. profile_image_optimized : string;
  19. transaction_hash : string;
}

Trade record

Sourcetype activity = {
  1. proxy_wallet : Polymarket_common.Primitives.Address.t;
  2. timestamp : int64;
  3. condition_id : Polymarket_common.Primitives.Hash64.t;
  4. activity_type : Activity_type.t;
  5. size : float;
  6. usdc_size : float;
  7. transaction_hash : string;
  8. price : float;
  9. asset : string;
  10. side : Side.t;
  11. outcome_index : int;
  12. title : string;
  13. slug : string;
  14. icon : string;
  15. event_slug : string;
  16. outcome : string;
  17. name : string;
  18. pseudonym : string;
  19. bio : string;
  20. profile_image : string;
  21. profile_image_optimized : string;
}

Activity record

Sourcetype holder = {
  1. proxy_wallet : Polymarket_common.Primitives.Address.t;
  2. bio : string;
  3. asset : string;
  4. pseudonym : string;
  5. amount : float;
  6. display_username_public : bool;
  7. outcome_index : int;
  8. name : string;
  9. profile_image : string;
  10. profile_image_optimized : string;
}

Holder of a position

Sourcetype meta_holder = {
  1. token : string;
  2. holders : holder list;
}

Meta holder with token and list of holders

Sourcetype traded = {
  1. user : Polymarket_common.Primitives.Address.t;
  2. traded : int;
}

Traded record

Sourcetype revision_entry = {
  1. revision : string;
  2. timestamp : int;
}

Revision entry

Sourceval yojson_of_revision_entry : revision_entry -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval revision_entry_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> revision_entry
Sourceval pp_revision_entry : Ppx_deriving_runtime.Format.formatter -> revision_entry -> Ppx_deriving_runtime.unit
Sourceval show_revision_entry : revision_entry -> Ppx_deriving_runtime.string
Sourceval equal_revision_entry : revision_entry -> revision_entry -> Ppx_deriving_runtime.bool
Sourcetype revision_payload = {
  1. question_id : Polymarket_common.Primitives.Hash64.t;
  2. revisions : revision_entry list;
}

Revision payload

Sourceval yojson_of_revision_payload : revision_payload -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval revision_payload_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> revision_payload
Sourcetype value = {
  1. user : Polymarket_common.Primitives.Address.t;
  2. value : float;
}

Value record

Sourcetype open_interest = {
  1. market : string;
    (*

    Can be "GLOBAL" or a condition ID hash

    *)
  2. value : float;
}

Open interest for a market

Sourcetype market_volume = {
  1. market : Polymarket_common.Primitives.Hash64.t option;
  2. value : float option;
}

Market volume

Sourcetype live_volume = {
  1. total : float option;
  2. markets : market_volume list;
}

Live volume

Leaderboard Types

Sourcetype leaderboard_entry = {
  1. rank : string;
  2. builder : string;
  3. volume : float;
  4. active_users : int;
  5. verified : bool;
}

Leaderboard entry for builders

Sourceval yojson_of_leaderboard_entry : leaderboard_entry -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval leaderboard_entry_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> leaderboard_entry
Sourceval pp_leaderboard_entry : Ppx_deriving_runtime.Format.formatter -> leaderboard_entry -> Ppx_deriving_runtime.unit
Sourceval show_leaderboard_entry : leaderboard_entry -> Ppx_deriving_runtime.string
Sourceval equal_leaderboard_entry : leaderboard_entry -> leaderboard_entry -> Ppx_deriving_runtime.bool
Sourcetype builder_volume_entry = {
  1. dt : Polymarket_common.Primitives.Timestamp.t;
  2. builder : string;
  3. verified : bool;
  4. volume : float;
  5. active_users : int;
  6. rank : string;
}

Builder volume entry

Sourceval yojson_of_builder_volume_entry : builder_volume_entry -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval builder_volume_entry_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> builder_volume_entry
Sourceval pp_builder_volume_entry : Ppx_deriving_runtime.Format.formatter -> builder_volume_entry -> Ppx_deriving_runtime.unit
Sourceval show_builder_volume_entry : builder_volume_entry -> Ppx_deriving_runtime.string
Sourceval equal_builder_volume_entry : builder_volume_entry -> builder_volume_entry -> Ppx_deriving_runtime.bool
Sourcetype trader_leaderboard_entry = {
  1. rank : string;
  2. proxy_wallet : Polymarket_common.Primitives.Address.t;
  3. user_name : string;
  4. vol : float;
  5. pnl : float;
  6. profile_image : string;
  7. x_username : string;
  8. verified_badge : bool;
}

Trader leaderboard entry

Sourceval yojson_of_trader_leaderboard_entry : trader_leaderboard_entry -> Ppx_yojson_conv_lib.Yojson.Safe.t
Sourceval trader_leaderboard_entry_of_yojson : Ppx_yojson_conv_lib.Yojson.Safe.t -> trader_leaderboard_entry
Sourceval pp_trader_leaderboard_entry : Ppx_deriving_runtime.Format.formatter -> trader_leaderboard_entry -> Ppx_deriving_runtime.unit
Sourceval show_trader_leaderboard_entry : trader_leaderboard_entry -> Ppx_deriving_runtime.string
Sourceval equal_trader_leaderboard_entry : trader_leaderboard_entry -> trader_leaderboard_entry -> Ppx_deriving_runtime.bool

Field Lists for Extra Field Detection

Sourceval yojson_fields_of_health_response : string list
Sourceval yojson_fields_of_position : string list
Sourceval yojson_fields_of_closed_position : string list
Sourceval yojson_fields_of_trade : string list
Sourceval yojson_fields_of_activity : string list
Sourceval yojson_fields_of_holder : string list
Sourceval yojson_fields_of_meta_holder : string list
Sourceval yojson_fields_of_traded : string list
Sourceval yojson_fields_of_revision_entry : string list
Sourceval yojson_fields_of_revision_payload : string list
Sourceval yojson_fields_of_value : string list
Sourceval yojson_fields_of_open_interest : string list
Sourceval yojson_fields_of_market_volume : string list
Sourceval yojson_fields_of_live_volume : string list
Sourceval yojson_fields_of_leaderboard_entry : string list
Sourceval yojson_fields_of_builder_volume_entry : string list
Sourceval yojson_fields_of_trader_leaderboard_entry : string list

The client type (alias for HTTP client)

Sourceval default_base_url : string

Default base URL: https://data-api.polymarket.com

Sourceval create : ?base_url:string -> sw:Eio.Switch.t -> net:'a Eio.Net.t -> rate_limiter:Polymarket_rate_limiter.Rate_limiter.t -> unit -> t

Create a Data API client.

  • parameter base_url

    Override the default base URL

  • parameter sw

    Eio switch for resource management

  • parameter net

    Eio network capability

  • parameter rate_limiter

    Rate limiter for API requests

Health Endpoint

Check if the API is healthy.

  • returns

    Ok response on success, Error error on failure

Position Endpoints

Sourceval get_positions : t -> user:Polymarket_common.Primitives.Address.t -> ?market:Polymarket_common.Primitives.Hash64.t list -> ?event_id:int list -> ?size_threshold:float -> ?redeemable:bool -> ?mergeable:bool -> ?limit:int -> ?offset:int -> ?sort_by:Position_sort_by.t -> ?sort_direction:Sort_direction.t -> ?title:string -> unit -> (position list, Polymarket_http.Client.error) result

Get current positions for a user.

  • parameter user

    User address (required)

  • parameter market

    Comma-separated condition IDs (mutually exclusive with event_id)

  • parameter event_id

    Event IDs >= 1 (mutually exclusive with market)

  • parameter size_threshold

    Minimum position size >= 0 (default: 1)

  • parameter redeemable

    Filter redeemable positions (default: false)

  • parameter mergeable

    Filter mergeable positions (default: false)

  • parameter limit

    Maximum results 0-500 (default: 100)

  • parameter offset

    Pagination offset 0-10000 (default: 0)

  • parameter sort_by

    Sort field (default: TOKENS)

  • parameter sort_direction

    Sort direction (default: DESC)

  • parameter title

    Filter by title (max 100 chars)

Sourceval get_closed_positions : t -> user:Polymarket_common.Primitives.Address.t -> ?market:Polymarket_common.Primitives.Hash64.t list -> ?event_id:int list -> ?title:string -> ?sort_by:Closed_position_sort_by.t -> ?sort_direction:Sort_direction.t -> ?limit:int -> ?offset:int -> unit -> (closed_position list, Polymarket_http.Client.error) result

Get closed positions for a user.

  • parameter user

    User address (required)

  • parameter market

    Condition IDs (mutually exclusive with event_id)

  • parameter event_id

    Event IDs >= 1 (mutually exclusive with market)

  • parameter title

    Filter by title (max 100 chars)

  • parameter sort_by

    Sort field (default: REALIZEDPNL)

  • parameter sort_direction

    Sort direction (default: DESC)

  • parameter limit

    Maximum results 0-50 (default: 10)

  • parameter offset

    Pagination offset 0-100000 (default: 0)

Trade Endpoints

Sourceval get_trades : t -> ?user:Polymarket_common.Primitives.Address.t -> ?market:Polymarket_common.Primitives.Hash64.t list -> ?event_id:int list -> ?side:Side.t -> ?filter_type:Filter_type.t -> ?filter_amount:float -> ?taker_only:bool -> ?limit:int -> ?offset:int -> unit -> (trade list, Polymarket_http.Client.error) result

Get trades for a user or markets.

  • parameter user

    User address

  • parameter market

    Condition IDs (mutually exclusive with event_id)

  • parameter event_id

    Event IDs >= 1 (mutually exclusive with market)

  • parameter side

    Filter by BUY or SELL

  • parameter filter_type

    Filter type (must be provided with filter_amount)

  • parameter filter_amount

    Filter amount >= 0 (must be provided with filter_type)

  • parameter taker_only

    Only taker trades (default: true)

  • parameter limit

    Maximum results >= 0 (default: 100, max: 10000)

  • parameter offset

    Pagination offset >= 0 (default: 0, max: 10000)

Activity Endpoint

Sourceval get_activity : t -> user:Polymarket_common.Primitives.Address.t -> ?market:Polymarket_common.Primitives.Hash64.t list -> ?event_id:int list -> ?activity_types:Activity_type.t list -> ?side:Side.t -> ?start_time:int -> ?end_time:int -> ?sort_by:Activity_sort_by.t -> ?sort_direction:Sort_direction.t -> ?limit:int -> ?offset:int -> unit -> (activity list, Polymarket_http.Client.error) result

Get user activity (on-chain).

  • parameter user

    User address (required)

  • parameter market

    Condition IDs (mutually exclusive with event_id)

  • parameter event_id

    Event IDs >= 1 (mutually exclusive with market)

  • parameter activity_types

    Filter by activity types

  • parameter side

    Filter by BUY or SELL

  • parameter start_time

    Start timestamp >= 0

  • parameter end_time

    End timestamp >= 0

  • parameter sort_by

    Sort field (default: TIMESTAMP)

  • parameter sort_direction

    Sort direction (default: DESC)

  • parameter limit

    Maximum results 0-500 (default: 100)

  • parameter offset

    Pagination offset 0-10000 (default: 0)

Holders Endpoint

Sourceval get_holders : t -> market:Polymarket_common.Primitives.Hash64.t list -> ?min_balance:int -> ?limit:int -> unit -> (meta_holder list, Polymarket_http.Client.error) result

Get top holders for markets.

  • parameter market

    Condition IDs (required)

  • parameter min_balance

    Minimum balance 0-999999 (default: 1)

  • parameter limit

    Maximum holders per token 0-20 (default: 20)

User Data Endpoints

Get total markets a user has traded.

  • parameter user

    User address (required)

Get total value of a user's positions.

  • parameter user

    User address (required)

  • parameter market

    Condition IDs to filter by

Market Data Endpoints

Sourceval get_open_interest : t -> ?market:Polymarket_common.Primitives.Hash64.t list -> unit -> (open_interest list, Polymarket_http.Client.error) result

Get open interest for markets.

  • parameter market

    Condition IDs to filter by

Sourceval get_live_volume : t -> id:int -> unit -> (live_volume list, Polymarket_http.Client.error) result

Get live volume for an event.

  • parameter id

    Event ID >= 1 (required)

Leaderboard Endpoints

Sourceval get_builder_leaderboard : t -> ?time_period:Time_period.t -> ?limit:int -> ?offset:int -> unit -> (leaderboard_entry list, Polymarket_http.Client.error) result

Get aggregated builder leaderboard.

  • parameter time_period

    Time period to aggregate (default: DAY)

  • parameter limit

    Maximum results 0-50 (default: 25)

  • parameter offset

    Pagination offset 0-1000 (default: 0)

Sourceval get_builder_volume : t -> ?time_period:Time_period.t -> unit -> (builder_volume_entry list, Polymarket_http.Client.error) result

Get daily builder volume time-series.

  • parameter time_period

    Time period for daily records (default: DAY)

Sourceval get_trader_leaderboard : t -> ?category:Leaderboard_category.t -> ?time_period:Time_period.t -> ?order_by:Leaderboard_order_by.t -> ?user:Polymarket_common.Primitives.Address.t -> ?user_name:string -> ?limit:int -> ?offset:int -> unit -> (trader_leaderboard_entry list, Polymarket_http.Client.error) result

Get trader leaderboard rankings.

  • parameter category

    Market category (default: OVERALL)

  • parameter time_period

    Time period (default: DAY)

  • parameter order_by

    Ordering criteria (default: PNL)

  • parameter user

    Filter to single user by address

  • parameter user_name

    Filter to single username

  • parameter limit

    Maximum results 1-50 (default: 25)

  • parameter offset

    Pagination offset 0-1000 (default: 0)