Rank x402 facilitators, sellers or payers over a window of days
/v1/chains/{chain}/x402/leaderboards/{kind}Ranks who settled, who was paid or who paid the most over a window of UTC days. Use it for "top facilitators" and "top sellers" tables, or to compare raw and genuine volume side by side. The board is added up from daily totals, so it is exact and quick whatever the number of payments.
What you can pass. {kind} is facilitators, sellers (the addresses that were paid) or payers. from and to set the window: without them it is the 30 days that end on the day of the newest data, and it spans at most 366 days. tier is A (the default, listed facilitators only) or AB. order is the figure to rank by, highest first: genuine_volume (the default), raw_volume, genuine_payments or raw_payments; ties keep a fixed order by id. limit is 1 to 100 items (default 25). The query keys may come in any order; links.self shows them sorted.
What comes back: data (kind x402_leaderboard) repeats the board, the resolved from and to, tier and order, and items, best first. Each item has the id (a registry id, relayer address or unknown on the facilitator board, an address on the others), its tier, raw_payments, raw_volume, genuine_payments and genuine_volume over the window, active_days (days with at least one payment) and the first_day and last_day of them. A facilitator item also has name (null for tier B) and gas_cost, the gas it spent in wei of the chain's native coin (MON on Monad, USDC on Arc, ETH on Base). With tier=AB one id can appear twice, once per tier. A window with no payment is not an error: items is empty. meta.as_of names the newest block served.
Path parameters
| Name | Type | Description |
|---|---|---|
chainRequired | string | The chain, as a CAIP-2 chain ID. Only Monad, |
kindRequired | string | Which kind of entity. |
Query parameters
| Name | Type | Description |
|---|---|---|
from | string | Optional. The first UTC day to include, |
to | string | Optional. The last UTC day to include, |
tier | stringDefault A | Optional. |
order | stringDefault genuine_volume | Optional. The figure to rank by, highest first: |
limit | integerDefault 25 | Optional. The most items to return, from 1 to 100. The default is 25. |
Response
The ranked entities, wrapped in the {data, meta, links} envelope. data.kind is x402_leaderboard.
| Field | Type | Description |
|---|---|---|
| board | string | facilitatorssellerspayers |
| chain | string | eip155:143eip155:5042eip155:8453 |
| from | string | The first day of the window as resolved. |
| items | array of objects | The ranked entities, best first, at most |
| kind | string | Always |
| order | string | genuine_volumeraw_volumegenuine_paymentsraw_payments |
| tier | string | AAB |
| to | string | The last day of the window as resolved. |
Cost
2 credits.
Errors
| Status | Code |
|---|---|
| 400 | invalid_idinvalid_query |
| 404 | unsupported_chain |
| 429 | rate_limitedcredits_exhausted |
| 500 | internal |
| 503 | upstream_unavailable |
| 504 | deadline_exceeded |
400 invalid_id for a kind that is none of the three. 400 invalid_query for an unknown key, a key sent twice or empty, a day that does not exist, from after to, or a bad tier, order or limit; these cost nothing. A window longer than 366 days is refused by the x402 data source with 400 invalid_query and costs the credits. 404 unsupported_chain, 503 upstream_unavailable (also while the x402 data has not been loaded yet), 504 deadline_exceeded.