Zec Address Flow Summary
zec_address_flow_summaryADDRESS FLOW SUMMARY / top counterparties of a Zcash (zec, ZEC, mainnet) address in one call: who
it pays and who pays it, plus its lifetime profile and a computed Role. Call this FIRST when
triaging a hop; for raw rows use zec_sent_from_address / zec_address_received,
for one transaction zec_tx_flow.
NOT only the lifetime totals, without counterparties → use zec_address_profile.
PROFILE columns (Lifetime_*, First_Received, Last_Received, Last_Sent) cover the address's
WHOLE history.
Lifetime_Received_ZEC / Lifetime_Sent_ZEC are cumulative TURNOVER, not holdings: every
output ever paid to the address (including the change it pays back to itself inside its own
spending transactions) and every input it ever spent. The same coins are counted each time
they pass through, so a busy exchange wallet's totals can exceed the coin's total supply many
times over; Lifetime_Received minus Lifetime_Sent is the balance at this address.
Role covers the WHOLE history too, not the days window, and follows from the lifetime counts:
no_transfers (nothing received and nothing spent) / receive_only (it never spent anything — cold
storage or an unused deposit address) / send_only (spends with no recorded receipt) / hub (more
than 1,000 distinct senders AND more than 1,000 distinct receivers — an exchange or service,
don't trace deeper) / consolidator (distinct senders more than 3 times distinct receivers) /
distributor (distinct receivers more than 3 times distinct senders) / relay (none of these).
The TOP ARRAYS cover only the last days (default 90) and, inside that window, at most the
1,000 most recent transactions on each side. Spend_Txs_Scanned / Receipt_Txs_Scanned say how
many were read; Spend_Txs_Truncated / Receipt_Txs_Truncated = 1 means older transactions in
the window were left out. So the arrays do NOT add up to the Lifetime_* totals. Window_Days /
Window_From state the period covered: empty arrays for an address whose Last_Sent is long
ago mean nothing moved in the window, not that it never moved — raise days.
Top_Receivers = the non-change recipients of the transactions this address spent in; Amount =
ZEC paid to that recipient. Top_Senders = the input addresses of the transactions that paid
this address (change excluded); Amount = ZEC this address received in those transactions.
A transaction with several input addresses credits each of them in full (they are usually one
owner — see zec_related_addresses), so Amount can be far more than what moved between the
two addresses. pro_rata_amount is Amount scaled by the input share: how much of those
transactions this address paid (Top_Receivers) or that sender paid (Top_Senders). Both arrays
are RANKED by pro_rata_amount, largest first, and min_amount / max_amount filter on it — dust
and address-poisoning payments hidden inside a large co-signed transaction have a tiny share.
Window_Own_Input_ZEC is what this address itself put into the spending transactions read,
the ceiling the Top_Receivers pro-rata amounts add up to. The arrays are built from a copy of
the transaction data that misses a few whole blocks (a handful a month), so a counterparty can
be absent.
READING THE TOP ARRAYS: positional 4-tuples [counterparty, amount, txs, pro_rata_amount]; the
Top_Fields column lists those names in the same order.
Shielded_Out_ZEC = ZEC the scanned spend transactions moved from the transparent side INTO
the shielded pool; Shielded_In_ZEC = ZEC the scanned receipt transactions brought OUT of it
(whole-transaction values, same window and cap as the arrays; block rewards are not
counted). Shielded_In_ZEC is exact. Shielded_Out_ZEC is exact for the Sapling pool and an
estimate for the Orchard pool, where the shielded amount and the fee are not recorded
separately: a standard fee is subtracted per transaction, so an unusually high fee can add
up to a few hundredths of a ZEC per transaction. Shielded value cannot be
followed: a large Shielded_Out_ZEC with few or no Top_Receivers means the coins went into
the shielded pool (the visible trail ends there), and a receipt funded from the shielded
pool has no visible sender.
Only the TRANSPARENT side of Zcash is visible: transparent addresses start with t1 or
t3. Coins moved into or out of the shielded pool (z-addresses, unified u1… addresses)
cannot be traced here.
Address labels are not available for this chain, so exchange / mixer / service nodes
cannot be recognized from this data.
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": "zec_address_flow_summary"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How far back the top arrays look, in days (default 90, 0-20000). The window ends today; inside it at most the 1,000 most recent transactions per side are ranked. The Lifetime_* profile columns ignore it. | |
| top_n | No | How many top receivers and top senders to return (each). 1-50. | |
| 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 | Zcash TRANSPARENT address — t1… or t3…, 35 characters, case-sensitive, matched verbatim. Shielded z-addresses and unified u1… addresses are not supported and are rejected. An address of another chain does not have this form and is refused. | |
| max_amount | No | Maximum pro_rata_amount (in ZEC, 0 or more) for a counterparty to appear in the top arrays. 0 (default) = no upper bound. | |
| min_amount | No | Minimum pro_rata_amount (in ZEC, 0 or more) for a counterparty to appear in the top arrays. 0 (default) = no lower bound. Set it above 0 (e.g. 0.001) to drop dust and address-poisoning payments - it filters on the pro-rata share, so a dust payment inside a large co-signed transaction is dropped too. |