Bitquery: Crypto & Blockchain Data

Matic Native Balances

matic_native_balances

Read-only

NATIVE COIN BALANCE of up to 50 Polygon (matic, POL, MATIC, PoS) addresses you ALREADY HAVE: each address's current POL balance (the coin that pays gas) - for filtering a known set of wallets down to the funded ones, e.g. an airdrop cohort. To discover holders you do not have yet, use matic_token_holders. NOT one address's transfer history → use matic_address_flow_summary. Pass the addresses separated by "|" (0x..) - up to 50; addresses after the 50th distinct one are ignored (compare Addresses_Requested with Addresses_Used), so split a longer list into several calls. WINDOW: only balances UPDATED within the last since_days days (default 7) are read, so an address that has not moved its native coin in that window returns NO row. Use the same window you searched for activity - e.g. the window of matic_token_senders - because an active wallet's balance is always fresh there; a wider window costs more for no gain on active wallets. Native_Balance is in POL (18 decimals); Native_Balance_Raw is the exact integer amount (wei); Balance_As_Of is when that balance was last updated. To identify the addresses, pass them to labels_for_addresses. Each row: Address, Native_Balance, Native_Balance_Raw, Balance_As_Of, Addresses_Requested, Addresses_Used.

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": {
      "addresses": "<addresses>"
    },
    "name": "matic_native_balances"
  }
}

Input Schema

Name	Required	Description	Default
`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
`addresses`	Yes	Addresses to look up, 0x-hex (case-insensitive), separated by "\|" - up to 50; addresses after the 50th distinct one are ignored (compare Addresses_Requested with Addresses_Used).
`since_days`	No	Only balances updated in the last N days are read (default 7, 1-30); an address not active in that window returns no row. Use the same window you used for matic_token_senders.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 6, 2026

changedInput schema / properties / since_days / default
```
Previous value: -2New value: +7
```

changedInput schema / properties / since_days / description

Previous value: -"Only balances updated in the last N days are read (default 2, 1-30); an address not active in that window returns no row. Use the same window you used for matic_token_senders."New value: +"Only balances updated in the last N days are read (default 7, 1-30); an address not active in that window returns no row. Use the same window you used for matic_token_senders."

AddedOct 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare read-only/non-destructive, but the description discloses the non-obvious behavior that matters here: only balances updated within since_days are read, so stale addresses silently return no row. It also warns that addresses past the 50th distinct one are dropped and points to Addresses_Requested vs Addresses_Used as the check, plus units (POL 18 decimals vs raw wei) and Balance_As_Of semantics.

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?

Front-loaded with purpose, then alternatives, then mechanics, then row shape — a sensible order. It is information-dense but heavy on caps and parentheticals, and the address-separator mechanics are stated twice (once in prose, once implicitly via the schema).

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?

With no output schema, the description compensates by enumerating the returned row columns and explaining the units of Native_Balance vs Native_Balance_Raw. Combined with the window semantics and the pointer to labels_for_addresses for identification, nothing needed to call it correctly is missing.

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 goes further by explaining the cost tradeoff of a wider since_days and recommending matching the window used for matic_token_senders, which the schema does not say. It restates the pipe separator and 50-address cap already in the schema, so it is additive rather than fully incremental.

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?

Opens with a specific verb+resource+scope: native coin balance for up to 50 Polygon addresses you already have, and clarifies POL is the gas coin. It explicitly separates itself from matic_token_holders (discovery) and matic_address_flow_summary (transfer history), so an agent can pick it without opening a sibling 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 the positive case (filter a known set of wallets down to funded ones, e.g. an airdrop cohort), the negative case (discovering new holders), and the wrong-tool case (one address's transfer history). It also tells the caller what to do with an oversized list: split it into several calls.

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

All Bitquery: Crypto & Blockchain Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.