API Endpoint(s) to get Reserve Events (Burns & Deductions)

[sallymoc]

Returns the burn and/or deduct events, ordered by most recent first.
Whether these are exposed as one endpoint or two separate ones is up to the team.

Input:

Param	Type	Required	Default	Description
contractIndex	int?	no	null	Filter by contract. If omitted, returns events across all contracts
pagination				Parameters use to paginate the results

Burn event (type 8 — increases contract reserve)

{
  "contractIndex": 2,
  "amount": 40000000000,
  "source": "PYIAWBCBIAXFOFYRNRHQEDPMJKDLKGEHIIAHOHCNPAFMHO...",
  "epoch": 150,
  "tick": 40012940,
  "txHash": "abcdef...",
  "logId": 123456,
  "timestamp": "2025-12-25T19:12:44Z"
}

Field	Type	Description
id	long	Event unique identifier within the epoch
contractIndex	int	Contract that received the burn
amount	long	Amount burned in QU
source	string	Address that initiated the burn
epoch	int	Epoch when the burn occurred
tick	long	Network tick number
txHash	string	Transaction hash
logId	long	Log ID from WebSocket stream (unique within an epoch)
timestamp	datetime	UTC timestamp of the event

Deduct event (type 13 — decreases contract reserve)

{
  "contractIndex": 2,
  "deductedAmount": 1000000,
  "remainingAmount": 39999000000,
  "epoch": 150,
  "tick": 40012941,
  "txHash": "fedcba...",
  "logId": 123457,
  "timestamp": "2025-12-25T19:12:45Z"
}

Field	Type	Description
logId	long	Event unique identifier within the epoch
contractIndex	int	Contract that was deducted from
deductedAmount	long	Amount deducted in QU
remainingAmount	long	Reserve balance after this deduction in QU
epoch	int	Epoch when the deduction occurred
tick	long	Network tick number
txHash	string	Transaction hash
timestamp	datetime	UTC timestamp of the event

Reference

[qubicmio]

contract index filter is added in qubic/archive-query-service#130. This might be enough for this user story.

[sallymoc]

We could use the getEventLogs with the appropriated filters to get the data for this.