Skip to main content
POST
Returns contract and system events from startLedger (or from a cursor), filtered by event type, contract and topics. The example reads events of the native XLM contract on Testnet. Pass the returned cursor to read the next page. The examples call Testnet with your key in LUMEUS_API_KEY; the SDK tabs use @stellar/stellar-sdk and the Python stellar-sdk (SDK setup and errors) (the curl example uses jq). On Mainnet, use https://rpc.lumeus.dev and a lum_live_ key.

Result

The fields of result (stellar-rpc 29). Fields marked “Present only when it applies” can be absent.

Parameters

Credits and limits

  • Mainnet: 2 credits plus 1 credit per started 64 KiB of response, so a small answer costs 3 credits. A call that returns a JSON-RPC error costs nothing.
  • Testnet: free. Each call counts toward your organization’s 10,000 Testnet requests a day; above that, calls get 429 rate_limited until 00:00 UTC.
  • Unknown filter fields are rejected with -32602. For full history beyond the 7-day window, use the Activity API (GET /contracts/{id}/activity).
  • The plan RPC rate applies per call; each call in a batch counts as one.

Errors

Gateway errors are JSON-RPC errors with the machine code in error.data and the request ID in error.request_id. Common ones: -32602 (invalid_request, HTTP 400) for invalid params, -32000 with unauthorized (401), rate_limited (429, wait Retry-After seconds) or unavailable (503). See errors.

Authorizations

Authorization
string
header
required

Send Authorization: Bearer <key>. Testnet: lum_test_…; Mainnet: lum_live_…. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable lum_pub_… keys call read-only methods only, from an allowed browser origin. Dashboard sessions and webhook keys are not accepted.

Headers

Idempotency-Key
string

Optional, and not used for deduplication: the response then carries X-Lumeus-Idempotency: ignored. To retry sendTransaction safely, resubmit the same signed envelope (the node answers DUPLICATE).

Required string length: 8 - 128
Example:

"retry-0001-2026-10-22"

Body

application/json

Returns contract and system events in a ledger range, filtered by type, contract and topics. 2 credits plus one per started 64 KiB of response. Named params only (positional arrays are rejected). A params member set to null (as Python stellar-sdk sends for unset options) is treated as omitted at any depth. startLedger 0 next to a cursor, endLedger 0 and pagination.limit 0 mean "not set", as on stellar-rpc.

jsonrpc
enum<string>
required

Always 2.0.

Available options:
2.0
id
integer
required

Request ID, echoed in the response. Send one on every call: a call without an id is a notification, which runs but gets an empty 204 response. A string ID (at most 1024 bytes) also works and is echoed unchanged.

Example:

1

method
enum<string>
required
Available options:
getEvents
params
From startLedger · object
required

Response

The getEvents result. Check error before reading result.

A JSON-RPC 2.0 response: result on success, error otherwise. A JSON-RPC error can arrive with HTTP 200 (for example from the node, or for one child of a batch). Gateway errors carry the code string in error.data and the request ID in error.request_id; they echo your id when the body is a parseable single request and use a null id when it cannot be determined. Preserve integer IDs exactly; avoid unsafe JavaScript numeric IDs. The gateway never answers 502 or 504.

jsonrpc
enum<string>
required
Available options:
2.0
id
integer | null
required

The id of your call, echoed unchanged (a string id comes back as a string). null when the gateway cannot read the id, for example for invalid JSON.

result
getEvents result · object
required

The getEvents result, as returned by stellar-rpc 29.

error
object
Example: