Read contract events naming an address
Returns the custom contract events (kind contract_event) whose topic 1, 2 or 3 is this address, newest first, from the contract-event topic index. It complements GET /accounts/{id}/activity, which returns the address’s token movements and fees but not these events.
- Full covered history: no ledger range is needed, and a page holds up to 1000 records at credit weight 1 (account class).
- A muxed address in a topic also matches its base G account. Narrow with
contract,positionandname. - A page can also stop early when its payload reads run out of time on cold history or its records reach 16 MiB. Follow
_links.next.hrefuntilrange_completeis true (pagination). - Unknown or repeated query parameters return 400, so a typo or an unsupported filter never returns unfiltered data.
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 the GET data routes only, from an allowed browser origin. Webhook keys (whk_…) are not accepted here.
Headers
Optional; reads do not need it. When sent it must be 8 to 128 printable ASCII characters (0x21-0x7E: no spaces or control characters) in one header, otherwise 400. Prepaid accounts use it to recover a read without paying again; for every other account a valid key is accepted and has no effect.
8 - 128^[\x21-\x7E]{8,128}$Path Parameters
Stellar address: a G account, M muxed account, C contract, B claimable balance or L liquidity pool StrKey. It must be checksum-valid.
56 - 69"GAIH3ULLFQ4DGSECF2AR555KZ4KNDGEKN4AFI4SU2M7B43MGK3QJZNSR"
Query Parameters
Exact event name: the payload type (the first topic symbol).
1 - 64Only events emitted by this C contract address.
^C[A-Z2-7]{55}$"CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC"
Only events with the address at this topic position (1, 2 or 3).
1 <= x <= 32
Sort by ledger: desc (newest first) or asc. The route description gives the default.
asc, desc "desc"
Records per page. Larger values are clamped to max_page_size from GET /v1/plans (200), or account_max_page_size (1000) on account activity and both topic routes; the page reports the effective value as limit.
x >= 110
Resume after this paging_token. Prefer following _links.next.href, which carries the cursor and the snapshot for you.
First ledger of the range, inclusive. Without until_ledger the range runs to the published tip (read_view.snapshot_ledger). A value past the tip returns an empty, complete page whose scanned_through_ledger is the tip.
x >= 05300000
End of the range, exclusive. Requires since_ledger and must be greater than it. There is no maximum range width.
x >= 1Index generation from read_view.generation. Send it together with snapshot_ledger to keep a walk on one snapshot; server links already include both.
Read at this published snapshot (read_view.snapshot_ledger of an earlier page). Requires generation. Below read_view.first_ledger it answers 400; above the published tip, 503 index_not_ready.
1 <= x <= 2147483647Response
A page of contract events read from one published snapshot.
True when no matching record remains after this page in the requested range (until_ledger, else the snapshot). An exactly full final page is already complete. Follow _links.next only while this is false.
Effective page size after clamping to the plan maximum: max_page_size, or account_max_page_size for account activity.
Last ledger of the range whose matching records this walk has delivered. On every complete page, in both orders, it is the last ledger of the effective range: until_ledger - 1, or snapshot_ledger when until_ledger is absent or later; for a descending walk that holds only if the walk started at the top of its range. On an ascending page stopped early by the scan budget it is the last fully scanned ledger. When since_ledger is beyond snapshot_ledger (past the published tip) the page is empty and complete, has no next link, and reports snapshot_ledger, in both orders, so a sync loop can checkpoint it. Absent on other incomplete pages and on an empty range that ends before first_ledger.