Skip to main content
Glama

Bitquery: Crypto & Blockchain Data

Zec Address Flow Summary

zec_address_flow_summary
Read-only

ADDRESS 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

NameRequiredDescriptionDefault
daysNoHow 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_nNoHow many top receivers and top senders to return (each). 1-50.
formatNoShape 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
addressYesZcash 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_amountNoMaximum pro_rata_amount (in ZEC, 0 or more) for a counterparty to appear in the top arrays. 0 (default) = no upper bound.
min_amountNoMinimum 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / format
      Added value: +{
      +  "default": "rows",
      +  "description": "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.",
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare only readOnlyHint/destructiveHint, and the description carries far more: Lifetime_* are cumulative turnover not holdings, Role definitions with thresholds (hub = >1,000 senders AND >1,000 receivers), the arrays cover only the `days` window and are capped at 1,000 tx per side with truncation flags, source data misses a few whole blocks per month, Shielded_Out_ZEC is an Orchard estimate while Shielded_In_ZEC is exact, and shielded value cannot be followed. This is exceptional behavioral disclosure beyond the structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but the length is justified by the tool's genuine complexity and it is front-loaded with the purpose and routing before the field semantics. Some prose (e.g., repeated shielded-pool caveats, the extended Role enumeration) could be tightened, but almost every sentence carries non-obvious operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-faceted analytics tool with no output schema, the description explains the return shape (positional 4-tuples, Top_Fields column order), every derived column, the window-versus-lifetime split, data-gap caveats, and chain limitations (transparent-only, no address labels). An agent has everything needed to interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns more by clarifying that `days` affects only the top arrays and not Lifetime_* columns, that ranking and min_amount/max_amount operate on pro_rata_amount (dropping dust and address-poisoning inside large co-signed transactions), and that empty arrays in a short window mean 'raise days'. That interaction-level meaning goes beyond the per-parameter schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line names a specific verb and resource ('top counterparties of a Zcash address in one call: who it pays and who pays it, plus its lifetime profile and a computed Role') and explicitly distinguishes itself from zec_sent_from_address, zec_address_received, zec_tx_flow, and zec_address_profile. An agent can select this over its siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: 'Call this FIRST when triaging a hop', names the alternatives for raw rows (zec_sent_from_address / zec_address_received) and single transactions (zec_tx_flow), and adds a negative case ('NOT only the lifetime totals, without counterparties → use zec_address_profile'). When-to-use, when-not-to-use, and alternatives are all present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.