getEvents
Read contract and system events, filtered by contract and topic.
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 ofresult (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_limiteduntil 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 inerror.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
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
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).
8 - 128"retry-0001-2026-10-22"
Body
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.
Always 2.0.
2.0 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.
1
getEvents - From startLedger
- From a cursor
Response
The getEvents result. Check error before reading result.
- Result
- Error
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.
2.0 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.
The getEvents result, as returned by stellar-rpc 29.