polymarket_sdk

defmodule Polymarket do
  @moduledoc """
  Higher-level Elixir SDK for Polymarket.

  This package depends on [`polymarket_clob`](https://hexdocs.pm/polymarket_clob)
  and builds on top of it. The split is deliberate:

    * `polymarket_clob` owns the low-level CLOB surface — EIP-712 order
      signing, ClobAuth, HMAC L2 request auth, order placement and
      cancellation, balances, order books, prices, and per-market metadata.
      Use it directly if that is all you need.
    * `polymarket` (this package) owns the higher-level Polymarket SDK —
      Gamma market discovery, the public Data API, normalized activity,
      P&L helpers, on-chain CTF redeem/merge/split, pUSD wrap/unwrap, and
      the RTDS real-time trade feed. It also exposes convenience facades
      that compose lower-level package calls.

  ## Out of scope

  This package is not a paper trading engine and not a runnable trading bot.
  Those live in separate `paper_ex` and `polymarket_bot` projects.

  ## Convenience facade

  The most common read-side calls are re-exported here, so casual
  use is one module away:

      {:ok, markets} = Polymarket.get_markets(params: [limit: 5])
      {:ok, market} = Polymarket.get_market("some-slug")
      {:ok, positions} = Polymarket.get_positions("0xwallet…")
      {:ok, activity} = Polymarket.get_activity("0xwallet…")
      {:ok, book} = Polymarket.get_order_book(token_id)
      {:ok, mid} = Polymarket.get_midpoint(token_id)

  Note the Gamma list endpoints (`get_markets/1`, `get_events/1`) read
  query filters only from the `:params` keyword — `Polymarket.get_markets(limit: 5)`
  would silently drop the `limit`. See `Polymarket.Gamma` for the full
  filter list.

  Each delegate's full documentation (options, response shapes)
  lives on the owning module — `Polymarket.Gamma`,
  `Polymarket.Data`, and `PolymarketClob.API.MarketData`. Anything
  beyond these one-liners (CTF, collateral, RTDS, RPC, activity
  normalization) is deliberately *not* re-exported: those surfaces
  carry state (an `%Polymarket.RPC{}`, a WebSocket) or domain
  decisions that deserve the explicit module name at the call site.

  ## Trading is done through `polymarket_clob`

  Order signing and placement are not exposed here. Build a CLOB client and
  call into `polymarket_clob` directly:

      client =
        PolymarketClob.client(
          private_key: System.fetch_env!("POLY_PRIVATE_KEY"),
          api_key: System.get_env("POLY_API_KEY"),
          api_secret: System.get_env("POLY_API_SECRET"),
          api_passphrase: System.get_env("POLY_API_PASSPHRASE")
        )

      {:ok, balance} = PolymarketClob.API.Account.get_balance_allowance(client)
  """

  ## Gamma — market & event discovery

  defdelegate get_markets(opts \\ []), to: Polymarket.Gamma
  defdelegate get_market(id_or_slug, opts \\ []), to: Polymarket.Gamma
  defdelegate get_events(opts \\ []), to: Polymarket.Gamma
  defdelegate get_event(id_or_slug, opts \\ []), to: Polymarket.Gamma

  ## Data API — wallet positions, activity, trades

  defdelegate get_positions(address, opts \\ []), to: Polymarket.Data
  defdelegate get_activity(address, opts \\ []), to: Polymarket.Data
  defdelegate get_trades(address, opts \\ []), to: Polymarket.Data

  ## CLOB market data (public, no credentials)

  defdelegate get_order_book(token_id, opts \\ []), to: PolymarketClob.API.MarketData
  defdelegate get_midpoint(token_id, opts \\ []), to: PolymarketClob.API.MarketData
  defdelegate get_tick_size(token_id, opts \\ []), to: PolymarketClob.API.MarketData

  @doc """
  Returns the package version.

  Derived from the loaded application spec (`:polymarket_sdk`'s `:vsn`),
  which is set from `mix.exs`'s `@version` at build time — so there is a
  single source of truth and this cannot drift from the published
  version.
  """
  @spec version() :: String.t()
  def version, do: :polymarket_sdk |> Application.spec(:vsn) |> to_string()
end