Skip to main content
Glama
0xfreak0

sui-analytics-mcp

by 0xfreak0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Query transactions

query_transactions
Read-only

Filter Sui transactions by sender, address, object, function, or time/checkpoint range. Returns paginated results with cursors and per-transaction Move call details for attribution.

Instructions

Query raw Sui transactions with specific filters (sender, affected address/object, function, time or checkpoint range). Note: only ONE of affected_address, affected_object, or function can be used per query (Sui GraphQL limitation). Newest first by default; each page reports its order, oldest_shown/newest_shown and the resolved window, and next_cursor goes back as cursor with the same order and filters. For human-readable wallet activity, prefer get_transaction_history instead.

VERSIONS: a function filter matches calls made through that exact package version, and each version of an upgraded package sees its own share of the calls. function_scope names the lineage when the package has other versions; all_versions: true reads every version as one merged list.

ATTRIBUTION WARNING: the function filter matches any transaction containing that call, including PTBs where it is one leg among several protocols. A transaction's balance changes cover the WHOLE PTB, so summing them per protocol over-attributes: a big Cetus swap in the same PTB will be counted as your protocol's volume. Set include_functions to see every Move call in each transaction, and prefer the protocol's own events (query_events) when measuring per-protocol flow.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax results (default 20, max 50)
orderNo'newest' (default) starts at the most recent match and pages back; 'oldest' starts at the earliest and pages forward.
cursorNo`next_cursor` from the previous page. Pass the same `order` and filters.
senderNoFilter by sender address
networkNoNetwork: 'mainnet' (default) | 'testnet' | 'devnet'
functionNoFilter by Move function (e.g. 0x2::coin::transfer or 0x2::pay). Mutually exclusive with affected_address and affected_object.
all_versionsNoWith `function`: read calls made through every version of the package's lineage, merged into one list (default false). Without it only the named version is read.
affected_objectNoFilter by affected object ID. Mutually exclusive with affected_address and function.
affected_addressNoFilter by affected address (sender, sponsor, or recipient). Mutually exclusive with affected_object and function.
after_checkpointNoOnly transactions after this point: a checkpoint number, or an ISO 8601 time (2026-08-07T00:00:00Z), which includes transactions at that time
before_checkpointNoOnly transactions before this point: a checkpoint number, or an ISO 8601 time, which includes transactions at that time
include_functionsNoReturn every Move call in each transaction, so you can see whether the filtered package was the whole transaction or one leg of a multi-protocol PTB.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changedv1.20.0
    • removedInput schema / properties / after
      Removed value: -{
-  "description": "Pagination cursor",
-  "type": "string"
-}
    • changedInput schema / properties / after_checkpoint / description
      Previous value: -"Only transactions after this checkpoint"New value: +"Only transactions after this point: a checkpoint number, or an ISO 8601 time (2026-08-07T00:00:00Z), which includes transactions at that time"
    • changedInput schema / properties / after_checkpoint / type
      Previous value: -"string"New value: +[
+  "string",
+  "number"
+]
    • addedInput schema / properties / all_versions
      Added value: +{
+  "description": "With `function`: read calls made through every version of the package's lineage, merged into one list (default false). Without it only the named version is read.",
+  "type": "boolean"
+}
    • changedInput schema / properties / before_checkpoint / description
      Previous value: -"Only transactions before this checkpoint"New value: +"Only transactions before this point: a checkpoint number, or an ISO 8601 time, which includes transactions at that time"
    • changedInput schema / properties / before_checkpoint / type
      Previous value: -"string"New value: +[
+  "string",
+  "number"
+]
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "`next_cursor` from the previous page. Pass the same `order` and filters.",
+  "type": "string"
+}
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (default 20)"New value: +"Max results (default 20, max 50)"
    • addedInput schema / properties / limit / maximum
      Added value: +50
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / network / description
      Previous value: -"Which Sui network to run this call against: 'mainnet' (default), 'testnet', or 'devnet'. Set this per-call — different tool calls in the same session can target different networks (e.g. to compare a value on testnet against mainnet)."New value: +"Network: 'mainnet' (default) | 'testnet' | 'devnet'"
    • addedInput schema / properties / order
      Added value: +{
+  "description": "'newest' (default) starts at the most recent match and pages back; 'oldest' starts at the earliest and pages forward.",
+  "enum": [
+    "newest",
+    "oldest"
+  ],
+  "type": "string"
+}
  2. First observedv1.5.0

TDQS

A4.5/5.0
Behavior4/5

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

The description is unusually transparent about pagination ('order', 'oldest_shown'/'newest_shown', 'next_cursor'), version-matching behavior, and the PTB over-attribution pitfall. However, it references `function_scope` as if it were a usable parameter even though it is not present in the schema, which introduces confusion.

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?

The description is front-loaded with the core purpose and organized into digestible paragraphs with clear warnings. It is longer than typical, but most sentences earn their place; the `function_scope` sentence is unearned and inaccurate, keeping it from a perfect score.

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

Completeness4/5

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

For a 12-parameter tool with no output schema, the description covers the return-page format, pagination contract, filter constraints, version semantics, and attribution warning, which is strong contextual coverage. The only meaningful gap is the misleading `function_scope` reference; otherwise an agent would have enough information to call the tool 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?

The schema already documents all parameters, so the bar is high, and the description adds real value: mutual exclusivity among affected_address/affected_object/function, exact-version versus all_versions behavior, and why include_functions matters for attribution. The phantom `function_scope` mention slightly weakens an otherwise strong parameter explanation.

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 description opens with a specific verb and resource: 'Query raw Sui transactions with specific filters...' and enumerates the filter dimensions. The word 'raw' plus the explicit pointer to get_transaction_history separates it from the wallet-activity sibling without needing the 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?

It gives direct routing: 'For human-readable wallet activity, prefer get_transaction_history instead' and 'prefer the protocol's own events (query_events) when measuring per-protocol flow.' It also states the hard constraint that only ONE of affected_address, affected_object, or function may be used, and when to enable all_versions and include_functions.

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

Deploy Server

Other Tools