SubscriptionService.SubscribeTransactions
Subscribe to the stream of transactions.
The stream begins at the latest executed checkpoint as seen by the server and yields transactions matching the filter as they are executed.
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.SubscriptionService/SubscribeTransactions. Server-streaming: the response is a stream of messages. Get a key from the dashboard; the same key works on every protocol.
Request: SubscribeTransactionsRequest
Request message for SubscriptionService.SubscribeTransactions.
| Field | Type | Description |
|---|---|---|
read_mask | google.protobuf.FieldMask | Optional. Mask for specifying which parts of the ExecutedTransaction should be returned. |
filter | TransactionFilter | Optional. DNF filter over indexed dimensions. If absent, every transaction is streamed. |
Response: SubscribeTransactionsResponse
Response message for SubscriptionService.SubscribeTransactions. Mirrors ListTransactionsResponse, except there is no end field: a subscription stream has no successful end.
| 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. |
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"
}
}
]
}
]
}
}' \
mainnet-grpc.inodra.com:443 \
sui.rpc.v2.SubscriptionService/SubscribeTransactionsServer 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 call = client.subscriptionService.subscribeTransactions({
readMask: { paths: ['digest'] },
filter: {
terms: [
{
literals: [
{
negated: false,
predicate: {
oneofKind: 'moveCall',
moveCall: {
function:
'0x0000000000000000000000000000000000000000000000000000000000000003::sui_system::request_add_stake'
}
}
}
]
}
]
}
})
for await (const frame of call.responses) {
if (frame.transaction) console.log(frame.transaction.digest)
}@mysten/sui v2 has no typed method for this RPC, so the sample calls the generated client.subscriptionService service client. Install with npm install @mysten/sui and set INODRA_API_KEY. The gRPC gateway guide covers native gRPC transport for backends.
Credits
Billed by volume: 5 credits to open the stream, then 1 credit per 50 KB of encoded message with a 1-credit minimum per message (20 credits per MB). Messages that carry only a watermark are free. The stream also pays for connection time, like a Warp stream: 4 credits per 5 seconds (about 48 per minute). See credits and billing for the full table.