View Source Hyperliquid.Api.Stats.Leaderboard (hyperliquid v0.2.2)

Leaderboard data from the Hyperliquid stats API.

Returns trading leaderboard with account values, performance metrics, and rankings.

See: https://stats-data.hyperliquid.xyz/Mainnet/leaderboard

Usage

{:ok, leaderboard} = Leaderboard.request()
{:ok, trader} = Leaderboard.get_trader(leaderboard, "0x...")

Summary

Types

leaderboard_row()

t()

window_performance()

Functions

__endpoint_info__()

Returns metadata about this endpoint.

__postgres_tables__()

Returns postgres table configurations (multi-table support).

__storage_config__()

Returns storage configuration for this endpoint.

build_cache_key(data)

Build a cache key from response data using the configured pattern. Returns nil if cache is not enabled or no pattern configured.

cache_enabled?()

Returns true if cache storage is enabled.

cache_ttl()

Returns the cache TTL if configured.

changeset(leaderboard \\ %__MODULE__{}, attrs)

Creates a changeset for leaderboard data.

fetch()

Fetch data and persist to configured storage backends.

fetch!()

Fetch data and persist. Raises on error.

get_trader(arg1, address)

Get a specific trader's row by address.

get_window_performance(row, window)

Get performance for a specific time window from a trader's row.

parse_response(data)

Parse and validate the API response.

postgres_enabled?()

Returns true if postgres storage is enabled.

postgres_table()

Returns the postgres table name if configured (primary table for legacy support).

postgres_upsert_config()

Returns the upsert config for postgres (primary table for legacy support).

rate_limit_cost()

Get the rate limit cost for this endpoint.

request()

Make the API request and parse the response.

request!()

Make the API request, raising on error.

request_raw()

Make the API request and return the raw response map (no key transformation).

request_raw!()

Make the API request returning raw map, raising on error.

storage_enabled?()

Returns true if any storage backend is enabled.

top_traders(arg1, n)

Get top N traders from the leaderboard.

trader_count(arg1)

Get the number of traders on the leaderboard.

Types

leaderboard_row()

@type leaderboard_row() :: %{
  eth_address: String.t(),
  account_value: String.t(),
  window_performances: [{String.t(), window_performance()}],
  prize: non_neg_integer(),
  display_name: String.t() | nil
}

t()

@type t() :: %Hyperliquid.Api.Stats.Leaderboard{leaderboard_rows: [leaderboard_row()]}

window_performance()

@type window_performance() :: %{pnl: String.t(), roi: String.t(), vlm: String.t()}

Functions

__endpoint_info__()

Returns metadata about this endpoint.

Example

iex> Hyperliquid.Api.Stats.Leaderboard.__endpoint_info__()
%{
  endpoint: "leaderboard",
  type: :stats,
  rate_limit_cost: 0,
  params: [],
  optional_params: [],
  doc: "Retrieve trading leaderboard",
  returns: "Leaderboard with trader rankings and performance metrics"
}

__postgres_tables__()

Returns postgres table configurations (multi-table support).

__storage_config__()

Returns storage configuration for this endpoint.

build_cache_key(data)

Build a cache key from response data using the configured pattern. Returns nil if cache is not enabled or no pattern configured.

cache_enabled?()

Returns true if cache storage is enabled.

cache_ttl()

Returns the cache TTL if configured.

changeset(leaderboard \\ %MODULE{}, attrs)

@spec changeset(t(), map()) :: Ecto.Changeset.t()

Creates a changeset for leaderboard data.

fetch()

@spec fetch() :: {:ok, t()} | {:error, term()}

Fetch data and persist to configured storage backends.

This calls request/0 and then stores the result using Storage.Writer.

fetch!()

@spec fetch!() :: t()

Fetch data and persist. Raises on error.

get_trader(arg1, address)

@spec get_trader(t(), String.t()) :: {:ok, leaderboard_row()} | {:error, :not_found}

Get a specific trader's row by address.

Parameters

leaderboard: The leaderboard struct
address: Ethereum address (0x...)

Returns

{:ok, leaderboard_row()} if found
{:error, :not_found} if not found

get_window_performance(row, window)

@spec get_window_performance(leaderboard_row(), String.t()) ::
  {:ok, window_performance()} | {:error, :not_found}

Get performance for a specific time window from a trader's row.

Parameters

row: A leaderboard row
window: Time window ("day", "week", "month", "allTime")

Returns

{:ok, window_performance()} if found
{:error, :not_found} if window not found

parse_response(data)

@spec parse_response(map()) :: {:ok, t()} | {:error, term()}

Parse and validate the API response.

postgres_enabled?()

Returns true if postgres storage is enabled.

postgres_table()

Returns the postgres table name if configured (primary table for legacy support).

postgres_upsert_config()

Returns the upsert config for postgres (primary table for legacy support).

rate_limit_cost()

@spec rate_limit_cost() :: non_neg_integer()

Get the rate limit cost for this endpoint.

request()

@spec request() :: {:ok, t()} | {:error, term()}

Make the API request and parse the response.

request!()

@spec request!() :: t()

Make the API request, raising on error.

request_raw()

@spec request_raw() :: {:ok, map()} | {:error, term()}

Make the API request and return the raw response map (no key transformation).

request_raw!()

@spec request_raw!() :: map()

Make the API request returning raw map, raising on error.

storage_enabled?()

Returns true if any storage backend is enabled.

top_traders(arg1, n)

@spec top_traders(t(), non_neg_integer()) :: [leaderboard_row()]

Get top N traders from the leaderboard.

Parameters

leaderboard: The leaderboard struct
n: Number of top traders to return

Returns

[leaderboard_row()]

trader_count(arg1)

@spec trader_count(t()) :: non_neg_integer()

Get the number of traders on the leaderboard.

Parameters

leaderboard: The leaderboard struct

Returns

non_neg_integer()