Matic Token Senders
matic_token_sendersTOKEN SENDERS COHORT on Polygon (matic, POL, MATIC, PoS): the addresses that SENT a given token at least min_transfers
times inside a time window, most recently active first - "wallets that actively use this token",
"build a cohort or airdrop list of recent senders of this token".
NOT one wallet's own outgoing transfers → use matic_transfers_out.
This counts SENDERS of the token, one row per sender; it does not value or label them - pass the
returned addresses to labels_for_addresses, and to matic_native_balances to keep only funded
wallets. By default only normal user wallets (EOAs) that sent the token in their OWN transaction count (eoa_only=1); set eoa_only=0 to include contract senders.
Pass the token's CONTRACT address in token (0x-hex (case-insensitive)); a symbol also matches clone tokens, so
pin the exact contract.
WINDOW: the last days days (default 1, at most 30) ending at before_time or now;
after_time sets the start instead. A sender must reach min_transfers sends WITHIN this window, so a
short recent window keeps only clearly-active wallets - the recency the cohort wants. There is no
full-history mode: to go further back, page with before_time.
PAGING: newest-active first, at most limit rows. If the result has limit rows there may be more -
set before_time to the oldest Last_Transfer_Time returned and call again, then combine and
de-duplicate the pages.
COST grows with the token's volume times the window: widen days step by step. A row-limit error
("Limit for rows ... exceeded") means the token is too busy for that window - shorten days.
Each row: Address, Transfers, First_Transfer_Time, Last_Transfer_Time.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"token": "<token>"
},
"name": "matic_token_senders"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window length in days ending at before_time (or now), 1-30. Ignored when after_time is set. | |
| limit | No | Max senders to return, most recently active first. At most 5000. | |
| token | Yes | The token's CONTRACT address (0x-hex (case-insensitive)) whose senders to list. Pin the exact token - a symbol matches clone tokens. | |
| format | No | Shape of the returned data. "rows" (the default) returns one item per row. "columnar" returns a single item, {"columns":[...],"rows":[[value,...],...]}, naming the columns once and listing each row's values in that order; it is more compact for large results and carries the same values. | rows |
| eoa_only | No | 1 (default) = only normal user wallets (EOAs), i.e. the sender signed the transaction itself; 0 = any sender, contracts included. Only 0 or 1. | |
| after_time | No | Only sends at/after this UTC time (e.g. "2026-06-01"). Overrides days. Empty = the last `days` days. | |
| before_time | No | Only sends strictly before this UTC time - set it to the oldest Last_Transfer_Time of a full page to get the next one. Empty = up to now. Format: YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], ISO-8601 like 2026-09-20T00:00:00Z (fraction or +02:00 offset allowed) or 10-digit unix seconds. | |
| min_transfers | No | Minimum number of sends of this token by an address inside the window to include it (default 11). 1-1000. |