Matic Address Flow Summary
matic_address_flow_summaryADDRESS FLOW SUMMARY / top counterparties: who a Polygon (matic, POL, MATIC, PoS) address sends funds TO and receives funds FROM, in one call — profile (sent/received
transfer counts, distinct receivers/senders) + TOP receivers AND TOP senders.
Collapses address_profile + trace_next_hop(out) + an incoming convergence into a
single call — call this FIRST when triaging a hop. Returns a computed Role:
receive_only (no outgoing transfer in the period) / send_only (no incoming one) /
no_transfers (neither) / consolidator (senders ≫ receivers) / distributor (receivers ≫
senders) / hub (thousands of both — don't trace deeper) / relay. The profile counts
and Role ALWAYS cover all tokens: currency and contract narrow only the top arrays
(matic_address_profile applies them to every count). Pass the returned counterparties to
labels_for_addresses to identify them. For raw rows use matic_transfers_in/out; for
one direction's full ranking use matic_trace_next_hop. READING THE TOP ARRAYS: one
entry per (counterparty, TOKEN) — the same address repeats once per token it moved.
Symbols are not unique; identify a token by contract. On a very high-traffic address
(an exchange or bridge hub) this aggregates a lot of history and can take tens of
seconds — narrow it with contract or currency to one token to make it far faster.
Amounts here are TOKEN UNITS, never USD - no USD value is available in this
data, so there is no usd filter and totals for different tokens must not be
compared or added together. For a ranking you can reason about, pin ONE token
with contract, or bound the range with min_amount / max_amount.
Symbol_NonAscii = 1 flags a symbol that is not plain ASCII: normal for CJK /
emoji names, but also how a scam token impersonates a major one with Cyrillic or
Greek look-alike letters - never treat such a token as the asset it resembles.
In the top arrays it is the symbol_nonascii field of each entry.
after_time / before_time bound BOTH the profile counts and the top arrays to one period
(without them both cover the whole history).
Counts and arrays are the transfers OF THIS ADDRESS itself. A bot account signs its
transactions while a contract it controls holds and moves the tokens - the contract
its transactions go TO, or a separate one - so a very active trader (the trading
tools' Trader_Address is the signer) can show few or no outgoing transfers here.
To find the address that really moves its tokens, open one of its Tx_Hash values
from trader_trades with matic_tx_transfers, then trace that address
(matic_transactions lists where this account's transactions go).
A transaction's own transfer is TOP-LEVEL, not internal, and is always counted.
POL moved by contract code deeper inside a transaction (an internal
transfer) is left out unless you pass include_internal=1.
For the full labelled list in USD, totals by label type, or a set of addresses → counterparties.
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": {
"address": "<address>"
},
"name": "matic_address_flow_summary"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | How many top receivers and top senders to return (each). | |
| 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 |
| address | Yes | Wallet/contract address, 0x-hex (case-insensitive). | |
| contract | No | Restrict the top arrays to ONE exact token by its contract address (0x-hex, case-insensitive) — the reliable way to pin a token, since a currency symbol also matches clone tokens. The profile counts and Role still cover all tokens. Empty = no token filter. | |
| currency | No | Restrict the top receiver/sender arrays to one currency symbol (e.g. "USDT"). Empty = all. A symbol is NOT unique — clone/scam tokens reuse "USDC"/"USDT" and their broken decimals can make a fake token outrank the real one, so check the returned contract before trusting the ranking. No backslashes. | |
| after_time | No | Only activity at/after this UTC time - bounds the profile counts AND the top arrays. Empty = whole history. 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. | |
| max_amount | No | Maximum total amount for a counterparty to appear in the top arrays. 0 (default) = no upper bound. Amounts are in each token's own units and are NOT comparable across tokens, so a token with inflated or wrong decimals can total billions of units and push the real counterparties out of the top arrays - cap it here, or pin one token with contract. | |
| min_amount | No | Minimum total amount for a counterparty to appear in the top arrays, in that token's own units. 0 (default) = no lower bound. Set it above 0 to drop dust and zero-value address-poisoning transfers (look-alike addresses that send 0 of a token so they show up next to the real counterparties). | |
| before_time | No | Only activity strictly before this UTC time - bounds the profile counts AND the top arrays. 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. | |
| include_internal | No | 0 (default) = top-level transfers only - the transfer a transaction makes itself, plus token transfers. 1 = also count POL moved by contract code deeper inside a transaction (an internal transfer, for example through a batch sender or a withdrawal contract). Only 0 or 1. |