LedgerService.ListTransactions
List transactions matching the provided filters.
Transactions are returned in ascending or descending transaction sequence order according to the query options ordering.
Endpoint
| Network | Host | Authentication |
|---|---|---|
| Mainnet | mainnet-grpc.inodra.com:443 | x-api-key metadata |
| Testnet | testnet-grpc.inodra.com:443 | x-api-key metadata |
Full method name: sui.rpc.v2.LedgerService/ListTransactions. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.
Request: ListTransactionsRequest
Request message for LedgerService.ListTransactions.
| Field | Type | Description |
|---|---|---|
read_mask | google.protobuf.FieldMask | Optional. Mask for specifying which parts of the ExecutedTransaction should be returned. |
start_checkpoint | uint64 | Optional. Start of the checkpoint range to query (inclusive). Defaults to genesis. |
end_checkpoint | uint64 | Optional. End of the checkpoint range to query (exclusive). Defaults to the current indexed ledger tip. |
filter | TransactionFilter | Optional. DNF filter over indexed dimensions. If absent, all transactions in the range are returned. |
options | QueryOptions | Optional cursor-bounded query options. If unspecified, reads in ascending order with the default item limit. The server enforces a maximum item limit and silently coerces larger values down to it. To paginate, pass the last received Watermark.cursor as options.after (ascending) or options.before (descending) on the next request. |
start_transaction_index | uint64 | Optional. Transaction position within start_checkpoint at which the query starts (inclusive): within start_checkpoint, only transactions whose ExecutedTransaction.transaction_index is at least this value are returned. Unset starts at the beginning of start_checkpoint. An index at or past the checkpoint's transaction count starts at the next checkpoint. Requires start_checkpoint. When this position leaves transactions of start_checkpoint out, a descending query does not report that checkpoint as covered in Watermark.checkpoint. Combines with options.after by intersection: the query starts at whichever of the two is later in ledger order. Servers that predate this field ignore it and start at the beginning of start_checkpoint, so clients must still drop transactions before this position themselves. |
end_transaction_index | uint64 | Optional. Transaction position within the last checkpoint of the range, end_checkpoint - 1, at which the query ends (exclusive): within that checkpoint, only transactions whose ExecutedTransaction.transaction_index is below this value are returned, so 0 returns none of it. Unset ends after the whole checkpoint. An index at or past the checkpoint's transaction count ends after the whole checkpoint. Requires end_checkpoint. A query that stops at this position ends with QUERY_END_REASON_CHECKPOINT_BOUND. When this position leaves transactions of that checkpoint out, an ascending query does not report it as covered in Watermark.checkpoint. Combines with options.before by intersection: the query ends at whichever of the two is earlier in ledger order. Servers that predate this field ignore it and return the whole checkpoint, so clients must still drop transactions at or after this position themselves. |
Response: ListTransactionsResponse
Response message for LedgerService.ListTransactions. Every frame carries a watermark with a safe resume cursor. A frame with transaction set delivers one matching item; a frame without it reports scan progress or terminal completion. Watermarks never regress in the requested ordering but may repeat. end is set exactly once, on the final frame of a successful stream. For QUERY_END_REASON_ITEM_LIMIT, that frame also carries the final item. For every other end reason, the final frame has no transaction payload.
| Field | Type | Description |
|---|---|---|
transaction | ExecutedTransaction | One matching transaction. Its position within the containing checkpoint is reported by ExecutedTransaction.transaction_index. |
watermark | Watermark | Progress watermark as of this frame. Present on every frame. A ScanLimit terminal watermark may repeat the previous frame's cursor when its authoritative scan frontier was already emitted. |
end | QueryEnd | Set exactly once, on the final frame of a successful query stream. |
ExecutedTransaction
| Field | Type | Description |
|---|---|---|
digest | string | The digest of this Transaction. |
transaction | Transaction | The transaction itself. |
signatures | repeated UserSignature | List of user signatures that are used to authorize the execution of this transaction. |
effects | TransactionEffects | The TransactionEffects for this transaction. |
events | TransactionEvents | The TransactionEvents for this transaction. This field might be empty, even if it was explicitly requested, if the transaction didn't produce any events. sui.types.TransactionEffects.events_digest is populated if the transaction produced any events. |
checkpoint | uint64 | The sequence number for the checkpoint that includes this transaction. |
timestamp | google.protobuf.Timestamp | The Unix timestamp of the checkpoint that includes this transaction. |
balance_changes | repeated BalanceChange | |
objects | ObjectSet | Set of objects either referenced as inputs or produced as outputs from this Transaction. |
transaction_index | uint64 | Zero-based position of this transaction within the checkpoint that includes it. |
Watermark
Progress of a scan, carried on every response frame, whether or not the frame delivers a matching item. Watermarks never regress in the requested ordering, but consecutive frames may carry the same watermark when additional work does not advance the safe resume frontier. A watermark has two parts:
- The resume point, in two forms:
cursor, opaque, for the server, andcursor_position, in ledger coordinates, for clients to order frames and drop duplicates. - Coverage:checkpoint, the boundary checkpoint the scan has proven fully covered. It trails the resume point. To continue in the same direction, set the request's start (ascending) or end (descending) atcursor_position. To read in the other direction, set the other bound atcursor_positionfrom a frame without an item; from a frame with an item, start a page after the item at its key with the finest index incremented, or end a page before it at its key. In both cases passcursorasoptions.afterwith a start and asoptions.beforewith an end.
| Field | Type | Description |
|---|---|---|
cursor | bytes | Opaque cursor at the resume point. Set on every watermark. Use as options.after (ascending) or options.before (descending) on the next request to resume from here. The most recently received cursor is always the safe resume point. Pass cursors back unchanged; never compare or inspect them. Cursors that differ can name the same point, and their encoding may change. |
checkpoint | uint64 | The inclusive boundary checkpoint that the scan has fully covered within the request's effective interval, in the request's ordering direction: an ascending scan has emitted every matching item in the interval at checkpoints <= checkpoint (strictly greater ones may still hold matches); a descending scan has emitted every matching item in the interval at checkpoints >= checkpoint. This boundary never regresses in the scan direction, but it may repeat while the cursor advances. Unset until the scan's first checkpoint is fully covered. For example, a scan resumed from a cursor that lands mid-checkpoint leaves this unset until the next checkpoint boundary in the scan direction is fully covered. A watermark still has a valid resume cursor while this field is unset. |
cursor_position | LedgerPosition | The resume point in ledger coordinates. Set on every watermark by servers that support it. Ascending, every match from the request's start up to (excluding) cursor_position has been delivered. Descending, every match from cursor_position up to (excluding) the request's end has been delivered. On a frame that carries an item, ascending, it is the boundary just past the item, so it is not the item's own key: it is that key with its finest index incremented (event_index for events, transaction_index for transactions, checkpoint for checkpoints). Descending, it is the boundary just before the item, which is the item's key. It never moves before the request's start (ascending) or past its end (descending), so an ascending request that starts beyond what the server has indexed gets its start echoed back: the resume point says where the client is, not where the ledger is. cursor may then name an earlier point; bounds intersect, so resuming with both starts at cursor_position. |
grpcurl
grpcurl -H "x-api-key: YOUR_API_KEY" \
-d '{
"read_mask": {
"paths": [
"digest"
]
},
"filter": {
"terms": [
{
"literals": [
{
"move_call": {
"function": "0x0000000000000000000000000000000000000000000000000000000000000003::sui_system::request_add_stake"
}
}
]
}
]
},
"options": {
"limit": 5,
"ordering": "ORDERING_DESCENDING"
}
}' \
mainnet-grpc.inodra.com:443 \
sui.rpc.v2.LedgerService/ListTransactionsServer reflection is enabled, so no proto files are needed for grpcurl. Field masks are written as {"paths": [...]}.
TypeScript
import { GrpcWebFetchTransport, SuiGrpcClient } from '@mysten/sui/grpc'
const transport = new GrpcWebFetchTransport({
baseUrl: 'https://mainnet-grpc.inodra.com',
meta: { 'x-api-key': process.env.INODRA_API_KEY! }
})
const client = new SuiGrpcClient({ network: 'mainnet', transport })
const { transactions, endCursor } = await client.listTransactions({
filter: {
function:
'0x0000000000000000000000000000000000000000000000000000000000000003::sui_system::request_add_stake'
},
limit: 5,
order: 'descending'
})
console.log(transactions.length, endCursor)Uses the typed SuiGrpcClient method from @mysten/sui v2 that calls this RPC. Install with npm install @mysten/sui and set INODRA_API_KEY. The gRPC gateway guide covers native gRPC transport for backends.
Credits
1 credit to open the stream, then 2 credits per streamed message, including watermark-only progress messages and the final message. See credits and billing for the full table.
JSON-RPC equivalent
Replaces suix_queryTransactionBlocks. The JSON-RPC to gRPC migration guide has before and after code for the common calls.
Related
- LedgerService overview and the gRPC gateway
- LedgerService.GetServiceInfo
- LedgerService.GetObject
- LedgerService.BatchGetObjects
- LedgerService.GetTransaction
- LedgerService.BatchGetTransactions
- LedgerService.GetCheckpoint
- LedgerService.GetEpoch
- LedgerService.ListCheckpoints
- LedgerService.ListEvents
- Proto definition on GitHub