Module Polymarket_http.BuilderSource

Type-safe request builder with phantom types.

This module provides a builder pattern for HTTP requests with compile-time enforcement of:

Example usage:

  (* GET request - returns parsed JSON list *)
  new_get client "/positions"
  |> query_param "user" user
  |> query_option "limit" string_of_int limit
  |> fetch_json_list position_of_yojson

  (* POST with body *)
  new_post client "/order"
  |> header_list auth_headers
  |> with_body body
  |> fetch_json order_of_yojson

  (* Raw execution for custom handling *)
  new_get client "/health"
  |> fetch
  |> fun (status, body) -> ...
Sourcetype ready

Phantom type indicating request is ready to execute

Sourcetype not_ready

Phantom type indicating request needs a body before execution

Sourcetype 'state t

Request builder type. 'state tracks whether request is ready to execute (either ready or not_ready).

Request Constructors

Sourceval new_get : Client.t -> string -> ready t

Create a GET request. Ready to execute immediately.

Sourceval new_post : Client.t -> string -> not_ready t

Create a POST request. Requires with_body before execution.

Sourceval new_delete : Client.t -> string -> ready t

Create a DELETE request. Ready to execute immediately.

Sourceval new_delete_with_body : Client.t -> string -> not_ready t

Create a DELETE request with body. Requires with_body before execution. Used for APIs that require a JSON body in DELETE requests.

Query Parameter Builders

Sourceval query_param : string -> string -> 'a t -> 'a t

Add a required string parameter.

Sourceval query_add : string -> string option -> 'a t -> 'a t

Add an optional string parameter.

Sourceval query_option : string -> ('b -> string) -> 'b option -> 'a t -> 'a t

Add an optional parameter with a converter function.

Sourceval query_list : string -> ('b -> string) -> 'b list option -> 'a t -> 'a t

Add an optional list parameter, joining values with commas.

Sourceval query_bool : string -> bool option -> 'a t -> 'a t

Add an optional boolean parameter (renders as "true"/"false").

Sourceval query_each : string -> ('b -> string) -> 'b list option -> 'a t -> 'a t

Add each value as a separate query parameter with the same key. query_each "id" string_of_int (Some [1; 2]) produces ?id=1&id=2

Header Builders

Sourceval header_add : string -> string -> 'a t -> 'a t

Add a single header.

Sourceval header_list : (string * string) list -> 'a t -> 'a t

Add multiple headers.

Auth

Sourceval with_l1_auth : private_key:Polymarket_common.Crypto.private_key -> address:string -> nonce:int -> 'a t -> 'a t

Add L1 authentication headers for wallet-based endpoints.

Sourceval with_l2_auth : credentials:Polymarket_common.Auth.credentials -> address:string -> 'a t -> 'a t

Add L2 authentication headers. Computes headers from the request's method, path, and body. Must be called after with_body for POST requests.

Body

Sourceval with_body : string -> not_ready t -> ready t

Add a request body. Changes state from not_ready to ready.

Execution

Sourceval fetch : ready t -> int * string

Execute the request and return raw (status, body). Use this for custom response handling.

Response Parsers

These execute the request and parse the response in one step.

Pass ~expected_fields (from @@deriving yojson_fields) to log warnings when the API returns fields not in our types.

Sourceval fetch_json : ?expected_fields:string list -> ?context:string -> (Yojson.Safe.t -> 'a) -> ready t -> ('a, Client.error) result

Execute and parse response as JSON object.

  • parameter expected_fields

    If provided, logs warning for unknown fields

  • parameter context

    Description for logging (e.g. "Market.t")

Sourceval fetch_json_list : ?expected_fields:string list -> ?context:string -> (Yojson.Safe.t -> 'a) -> ready t -> ('a list, Client.error) result

Execute and parse response as JSON array.

  • parameter expected_fields

    If provided, logs warning for unknown fields in items

  • parameter context

    Description for logging

Sourceval fetch_text : ready t -> (string, Client.error) result

Execute and return response body as string.

Sourceval fetch_unit : ready t -> (unit, Client.error) result

Execute and discard response body. Succeeds on 200/201/204.