Get a leaderboard

View Markdown Ask in ChatGPT Ask in Claude

The top members for one period, category and metric, best first. value is a dollar string for money metrics, an integer for counts and a 0..1 number for ratios. Rows carry a public handle, avatar path and top sport, never an account id. An unknown category is not an error; the board is simply empty. A board STX hides is empty with shown: false.

GET

/api/v1/leaderboard

Try it

Jurisdiction (demo)Base URL

Key ID stx_access_keyPrivate key (PEM or base64 seed) stx_private_key

Request

Every endpoint, in one place: the full Try it.

Signing happens in your browser with WebCrypto. Your private key is never sent anywhere; Send request sends your key ID and the signature to the demo host above. Only demo hosts are offered. The key ID and private key are saved in this browser's local storage, per jurisdiction, until you click Clear saved key. Use a demo key here, never a production one.

Parameters

Name	In	Type	Required	Description
`period`	`query`	`daily` \| `weekly` \| `monthly` \| `yearly` \| `all`	no	The ranking window, on America/New_York calendar days: `daily` is today, `weekly` from Monday, `monthly` from the 1st, `yearly` from 1 January, `all` lifetime. Default `weekly`.
`category`	`query`	string	no	`all` (default) or a sport key, as in a row’s `top_sport`, e.g. `basketball`. An unknown key has no rankings: an empty board, or an unranked standing on `/me`.
`metric`	`query`	`volume` \| `profit` \| `predictions` \| `markets` \| `win_rate` \| `biggest_win` \| `return` \| `streak`	no	The board: notional traded (`filled × max_price`), net profit, contracts settled, markets settled, win rate, biggest single win, return (profit ÷ volume) or longest winning streak. Default: the board STX opens on.
`limit`	`query`	integer	no	Rows to return. Defaults to 100 and is silently clamped to the number of members STX shows per board (at most 100). There is no cursor.

Responses

Status	Description	Schema
`200`	Success	Leaderboard
`400`	A parameter was missing or invalid.	Error
`401`	No credential, a bad signature, or a bearer token that is expired, invalid or not a member’s. With any signing header present the API-key rules apply and the body is {“error”:“Missing or invalid API key credentials”}; otherwise {“error”:“Unauthorized”}.	Error
`403`	The account behind this key is not active, for example it is pending approval or suspended. Body: {“error”:“Your account is suspended. Contact support.”}, the message naming the account’s status.	Error
`404`	The leaderboard is not enabled in this environment. Body: {“error”:“Leaderboard is not enabled”}	Error

Example

Request:

curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/leaderboard' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'

Response 200:

{
  "category": "string",
  "leaderboard": [
    {
      "avatar_url": null,
      "handle": null,
      "rank": null,
      "top_sport": null,
      "top_sport_icon_url": null,
      "value": null
    }
  ],
  "metric": "volume",
  "next_reset_at": null,
  "period": "daily",
  "refreshed_at": null,
  "shown": false
}

Response fields

Field	Type	Description
`category`	string	`all` or a sport key.
`metric`	string	The metric the rows are ranked on.
`next_reset_at`	date-time	When this period’s board resets: local midnight in America/New_York on the next boundary, as UTC. `null` for `all`, which never resets, and before the first snapshot.
`period`	string	The period the board covers.
`refreshed_at`	date-time	When this snapshot was built. `null` before the first snapshot is published.
`shown`	boolean	Whether STX shows this board to members. `false` means the board is hidden and `leaderboard` is empty, not that nobody has ranked yet.
`avatar_url`	string	Path of the member’s avatar, `/avatars/{handle}.svg`, relative to the API host. `null` when `handle` is `null`.
`handle`	string	The member’s public handle. `null` for a member who has not set one.
`rank`	integer	Dense rank, 1-based. Tied values share a rank.
`top_sport`	string	The sport the member traded most in the period, as a category key. On a sport board it is that sport. `null` when unknown.
`top_sport_icon_url`	string	Path of the sport’s icon, the same category icon the apps use, relative to the API host. `null` when `top_sport` is `null`.
`value`		The ranked value. A dollar string on money boards, an integer on count boards and a number from 0 to 1 on ratio boards.

v1.5.9Changelog llms.txt llms-full.txt