stellar-rpc-beta.openrpc.json

{
  "openrpc": "1.2.6",
  "info": {
    "title": "Stellar RPC (beta methods)",
    "description": "Methods that are only served by the archive Stellar RPC node, which is in beta. These methods are in development and can change without notice.",
    "termsOfService": "https://stellar.org/terms-of-service",
    "contact": {
      "name": "Stellar Development Foundation",
      "url": "https://stellar.org/connect",
      "email": "hello@stellar.org"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "0.1.0"
  },
  "servers": [],
  "methods": [
    {
      "name": "queryEvents",
      "summary": "returns events for a ledger range, ascending or descending, with cursors that do not expire (beta)",
      "description": "Returns contract and system events that match the specified filters within a ledger range. Results are paginated; each response contains a page of events and, when the scan is not complete, a cursor for continuing the query.\n\nSet `order` to `asc` to scan forward from `minLedger`, or to `desc` to scan backward from `maxLedger`. If omitted, `maxLedger` defaults to the latest ledger.\n\nTo start a query, specify the applicable ledger bounds, scan order, and optional filters. To retrieve the next page, send the `cursor` returned in the previous response without repeating `minLedger`, `maxLedger`, `order`, or `filters`. The cursor preserves those query parameters. `limit` and `xdrFormat` are not stored in the cursor and may be specified on each request.\n\nUse `scanStatus` to determine whether to request another page, wait for additional ledgers, or stop. An empty `events` array does not necessarily mean the scan is complete.",
      "externalDocs": {
        "url": "https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/queryEvents"
      },
      "paramStructure": "by-name",
      "params": [
        {
          "name": "minLedger",
          "summary": "first ledger of the range, inclusive",
          "description": "The first ledger in the range (inclusive). Required for ascending scans (`order: asc`) and optional for descending scans. Specify this parameter only when starting a query, not when continuing with a cursor.",
          "required": false,
          "schema": {
            "title": "ledgerSequence",
            "description": "Sequence number of the ledger.",
            "type": "number"
          }
        },
        {
          "name": "maxLedger",
          "summary": "last ledger of the range, inclusive",
          "description": "The last ledger in the range (inclusive). Optional. Without `maxLedger`, an ascending scan continues toward newly closed ledgers and reports `WAITING_FOR_LEDGERS` when it catches up to the chain. A descending scan starts at the latest ledger. Specify this parameter only when starting a query.",
          "required": false,
          "schema": {
            "title": "ledgerSequence",
            "description": "Sequence number of the ledger.",
            "type": "number"
          }
        },
        {
          "name": "order",
          "summary": "scan direction: 'asc' or 'desc'",
          "description": "The direction of the scan. `asc` (default) scans forward from `minLedger`; `desc` scans backward from `maxLedger`. Specify this parameter only when starting a query.",
          "required": false,
          "schema": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ]
          }
        },
        {
          "name": "filters",
          "summary": "list of filters; AND inside a filter, OR across filters",
          "description": "An array of 1 to 256 event filters. An event matches if it satisfies at least one filter; within a filter, all specified fields must match. Omit `filters` to match all events. Specify this parameter only when starting a query.\n\nFor example, to match either `transfer` or `mint` events from one contract, send two filters with the same `contractId` and a different `topic0`. The first example below does this.\n\nTopic values are Base64-encoded XDR `ScVal`s, not plain strings. Use the [JSON to XDR](https://lab.stellar.org/xdr/to) page in the Lab to encode a value.\n\nA query may use at most 15 distinct index terms by default; node operators can configure this limit. Each distinct `contractId` is one term, each distinct `type` is one term, and each distinct value at a given topic position is one term. The same value at the same position counts once no matter how many filters repeat it. The same value at two different positions counts twice. For example, `[{ topic0: transfer, topic1: me }, { topic0: transfer, topic2: me }]` uses 3 terms. A query over the budget returns `invalid_params` with `termsUsed` and `termBudget` in `error.data`.",
          "required": false,
          "schema": {
            "type": "array",
            "minItems": 1,
            "maxItems": 256,
            "items": {
              "type": "object",
              "description": "Every field set in the filter must match (AND). At least one field is required. There is no wildcard string; an omitted topic position matches anything.",
              "minProperties": 1,
              "additionalProperties": false,
              "properties": {
                "type": {
                  "title": "type",
                  "description": "The type of emitted event.",
                  "type": "string",
                  "enum": [
                    "contract",
                    "system"
                  ]
                },
                "contractId": {
                  "title": "contractId",
                  "description": "The emitting contract address in StrKey format (`C...`).",
                  "type": "string"
                },
                "topic0": {
                  "type": "string",
                  "description": "The Base64-encoded XDR `ScVal` that the first event topic must match."
                },
                "topic1": {
                  "type": "string",
                  "description": "The Base64-encoded XDR `ScVal` that the second event topic must match."
                },
                "topic2": {
                  "type": "string",
                  "description": "The Base64-encoded XDR `ScVal` that the third event topic must match."
                },
                "topic3": {
                  "type": "string",
                  "description": "The Base64-encoded XDR `ScVal` that the fourth event topic must match."
                }
              }
            }
          }
        },
        {
          "name": "cursor",
          "summary": "cursor from the previous response",
          "description": "The cursor returned by the previous response, used to continue a query. It preserves the ledger bounds, scan order, and filters. Do not combine `cursor` with `minLedger`, `maxLedger`, `order`, or `filters`; doing so returns an error.",
          "required": false,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "limit",
          "summary": "events per page, 1 to 1000",
          "description": "The maximum number of events to return per page, from 1 to 1,000. Defaults to 100. This setting is not stored in the cursor; include it on each request to retain a nondefault value.",
          "required": false,
          "schema": {
            "type": "number",
            "minimum": 1,
            "maximum": 1000
          }
        },
        {
          "name": "xdrFormat",
          "summary": "chooses a response format for XDR fields: 'json' or 'base64'",
          "required": false,
          "description": "Controls how XDR values are represented in the response: decoded JSON or Base64-encoded XDR. Do not depend on a fixed schema for the JSON representation, as it may change with the underlying XDR.",
          "schema": {
            "title": "xdrFormat",
            "type": "string",
            "description": "Specifies whether XDR should be encoded as Base64 (default or 'base64') or JSON ('json')."
          }
        }
      ],
      "result": {
        "name": "queryEventsResult",
        "schema": {
          "type": "object",
          "required": [
            "events",
            "scanStatus",
            "scannedLedger",
            "oldestLedger",
            "latestLedger"
          ],
          "properties": {
            "events": {
              "type": "array",
              "description": "Events returned on this page, up to the configured `limit`. The array may be empty even when more pages remain; check `scanStatus`.",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "title": "type",
                    "description": "The type of emitted event.",
                    "type": "string",
                    "enum": [
                      "contract",
                      "system"
                    ]
                  },
                  "ledger": {
                    "description": "The sequence number of the ledger in which the event was emitted.",
                    "type": "number"
                  },
                  "ledgerClosedAt": {
                    "description": "The ledger close time, formatted as an ISO 8601 timestamp.",
                    "type": "string"
                  },
                  "contractId": {
                    "description": "The address of the contract that emitted the event, in StrKey format.",
                    "type": "string"
                  },
                  "id": {
                    "description": "A unique event identifier consisting of a 19-character TOID and a 10-character, zero-padded event index, separated by a hyphen.",
                    "type": "string"
                  },
                  "transactionIndex": {
                    "description": "The index of the event's transaction within the ledger.",
                    "type": "number"
                  },
                  "operationIndex": {
                    "description": "The index of the operation that emitted the event within its transaction.",
                    "type": "number"
                  },
                  "topic": {
                    "description": "The event topics, each represented as a Base64-encoded XDR `ScVal`.",
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 4,
                    "items": {
                      "type": "string"
                    }
                  },
                  "value": {
                    "description": "The event data, represented as a Base64-encoded XDR `ScVal`.",
                    "type": "string"
                  },
                  "txHash": {
                    "title": "hash",
                    "type": "string",
                    "minLength": 64,
                    "maxLength": 64,
                    "pattern": "^[a-f\\d]{64}$",
                    "description": "The hash of the transaction that triggered the event."
                  }
                }
              }
            },
            "cursor": {
              "type": "string",
              "description": "An opaque cursor for retrieving the next page. It preserves the original ledger bounds, scan order, and filters and does not expire. The cursor is absent only when `scanStatus` is `COMPLETE`."
            },
            "scanStatus": {
              "type": "string",
              "description": "Indicates the state of the scan and the next action.\n\n- `HAS_MORE`: more data can be scanned immediately; request the next page.\n- `WAITING_FOR_LEDGERS`: the scan needs ledgers the node does not yet hold; wait and retry with the same cursor.\n- `OLDEST_REACHED`: a descending scan reached the oldest ledger available on this node before reaching the requested lower bound; stop or use a node with deeper history.\n- `COMPLETE`: the requested range has been fully scanned; no cursor is returned.",
              "enum": [
                "HAS_MORE",
                "WAITING_FOR_LEDGERS",
                "OLDEST_REACHED",
                "COMPLETE"
              ]
            },
            "scannedLedger": {
              "type": "number",
              "description": "A scan checkpoint indicating that all matching events from the scan's starting bound through this ledger have been delivered. If a page ends partway through a ledger, this field identifies the last fully scanned ledger; the cursor resumes within the partially scanned ledger. Before any ledger has been fully scanned, the value is `minLedger - 1` for ascending scans or `maxLedger + 1` for descending scans."
            },
            "oldestLedger": {
              "type": "number",
              "description": "The sequence number of the oldest ledger available to the RPC node when it processed the request."
            },
            "latestLedger": {
              "type": "number",
              "description": "The sequence number of the latest ledger known to the RPC node when it processed the request."
            }
          }
        }
      },
      "examples": [
        {
          "name": "Newest transfer or mint events",
          "description": "Starts a query for the newest `transfer` or `mint` events from one contract, two per page. With `order: desc` and no ledger bounds, the scan starts at the latest ledger and walks back. The two filters share a `contractId` and differ in `topic0`, so an event matches either. Ledger numbers and hashes are illustrative.",
          "params": [
            {
              "name": "order",
              "value": "desc"
            },
            {
              "name": "filters",
              "value": [
                {
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "topic0": "AAAADwAAAAh0cmFuc2Zlcg=="
                },
                {
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "topic0": "AAAADwAAAARtaW50"
                }
              ]
            },
            {
              "name": "limit",
              "value": 2
            }
          ],
          "result": {
            "name": "queryEventsResult",
            "value": {
              "events": [
                {
                  "type": "contract",
                  "ledger": 1189981,
                  "ledgerClosedAt": "2024-04-25T17:52:46Z",
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "id": "0005110929477865472-0000000000",
                  "transactionIndex": 1,
                  "operationIndex": 0,
                  "txHash": "5bd25a1a8fd1fe8ec99ab1fdd57af9a6f0e4c7c8a3c1b7d2e9f0a1b2c3d4e5f6",
                  "topic": [
                    "AAAADwAAAAh0cmFuc2Zlcg==",
                    "AAAAEgAAAAAAAAAAeo0X4ISuIjuArAyYXR0z8qyj0x0MHpv92CTtN4PONek=",
                    "AAAAEgAAAAAAAAAAfn3koV5C+Z6q8U1LfPwlofeZ3jnWI6Iudfg5NOEmOtg="
                  ],
                  "value": "AAAACgAAAAAAAAAAAAAAAAX14QA="
                },
                {
                  "type": "contract",
                  "ledger": 1189977,
                  "ledgerClosedAt": "2024-04-25T17:52:26Z",
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "id": "0005110912298004480-0000000000",
                  "transactionIndex": 3,
                  "operationIndex": 0,
                  "txHash": "e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70",
                  "topic": [
                    "AAAADwAAAAh0cmFuc2Zlcg==",
                    "AAAAEgAAAAAAAAAAfn3koV5C+Z6q8U1LfPwlofeZ3jnWI6Iudfg5NOEmOtg=",
                    "AAAAEgAAAAAAAAAAeo0X4ISuIjuArAyYXR0z8qyj0x0MHpv92CTtN4PONek="
                  ],
                  "value": "AAAACgAAAAAAAAAAAAAAAACYloA="
                }
              ],
              "cursor": "gec1_AQEAAAASJnIAAAASJm0AAAAB...",
              "scanStatus": "HAS_MORE",
              "scannedLedger": 1189978,
              "oldestLedger": 2,
              "latestLedger": 1190004
            }
          }
        },
        {
          "name": "Next page",
          "description": "Continues the query above by sending only the `cursor` from the previous response and `limit`. The order and filters come from the cursor. The scan has no lower bound, so it reports `HAS_MORE` until it reaches the oldest ledger the node holds. Keep sending the cursor until `scanStatus` is `OLDEST_REACHED` or `COMPLETE`.",
          "params": [
            {
              "name": "cursor",
              "value": "gec1_AQEAAAASJnIAAAASJm0AAAAB..."
            },
            {
              "name": "limit",
              "value": 2
            }
          ],
          "result": {
            "name": "queryEventsResult",
            "value": {
              "events": [
                {
                  "type": "contract",
                  "ledger": 1189977,
                  "ledgerClosedAt": "2024-04-25T17:52:26Z",
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "id": "0005110912298004481-0000000000",
                  "transactionIndex": 3,
                  "operationIndex": 1,
                  "txHash": "e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70",
                  "topic": [
                    "AAAADwAAAARtaW50",
                    "AAAAEgAAAAAAAAAAfn3koV5C+Z6q8U1LfPwlofeZ3jnWI6Iudfg5NOEmOtg="
                  ],
                  "value": "AAAACgAAAAAAAAAAAAAAAAX14QA="
                },
                {
                  "type": "contract",
                  "ledger": 1189950,
                  "ledgerClosedAt": "2024-04-25T17:50:11Z",
                  "contractId": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
                  "id": "0005110796333883392-0000000000",
                  "transactionIndex": 2,
                  "operationIndex": 0,
                  "txHash": "0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f9",
                  "topic": [
                    "AAAADwAAAAh0cmFuc2Zlcg==",
                    "AAAAEgAAAAAAAAAAeo0X4ISuIjuArAyYXR0z8qyj0x0MHpv92CTtN4PONek=",
                    "AAAAEgAAAAAAAAAAfn3koV5C+Z6q8U1LfPwlofeZ3jnWI6Iudfg5NOEmOtg="
                  ],
                  "value": "AAAACgAAAAAAAAAAAAAAAAJiWgA="
                }
              ],
              "cursor": "gec1_AQEAAAASJj4AAAASJj0AAAAA...",
              "scanStatus": "HAS_MORE",
              "scannedLedger": 1189951,
              "oldestLedger": 2,
              "latestLedger": 1190004
            }
          }
        }
      ]
    }
  ],
  "components": {}
}