Skip to main content
Every action your node takes — missions accepted, payments settled, peer connections opened, governance votes cast — is recorded in an append-only, hash-chained event log. Each entry carries a per-event signature and a prev_hash pointer, forming a tamper-evident chain that gateway observers can independently verify. Three HTTP surfaces expose this log: a query endpoint, an export endpoint for signed snapshots, and a WebSocket stream for real-time consumers. A separate audit log records control-plane operations.

​
GET /v1/events

Returns a paginated list of events from the local event log. You can filter the results to a specific point in time using a since query parameter. 
curl -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  http://127.0.0.1:7777/v1/events

​
Query Parameters

​
since
string
ISO 8601 timestamp. Only events recorded after this point are returned. Omit to retrieve the full log from genesis.Example: ?since=2024-11-01T00:00:00Z
​
limit
integer
Maximum number of events to return in a single response. Defaults to 100. Use in combination with since for pagination.
​
type
string
Filter by event type string (e.g. mission.accepted, payment.settled, peer.connected). Omit to return all event types.

​
Response Fields

​
events
array
Ordered array of event objects, oldest first.
​
events[].id
string
Unique event identifier (content-addressed hash).
​
events[].type
string
Event type string in dot-notation (e.g. "mission.accepted").
​
events[].timestamp
string
ISO 8601 timestamp of when the event was recorded.
​
events[].prev_hash
string
Hash of the immediately preceding event in the chain. Forms the tamper-evident linkage.
​
events[].signature
string
Ed25519 signature over the event payload, verifiable against the node’s public_identity key.
​
events[].payload
object
Event-specific data. Shape varies by type.
​
total
integer
Total number of events matching the query (before limit is applied).

​
Example Response

{
  "events": [
    {
      "id": "evt_7f3a9c1b2e4d5f6a",
      "type": "mission.accepted",
      "timestamp": "2024-11-14T09:22:04Z",
      "prev_hash": "sha256:a1b2c3d4e5f6...",
      "signature": "MEYCIQDx...",
      "payload": {
        "mission_id": "msn_9d2e1f3b",
        "issuer_did": "did:watt:xyz987",
        "reward_watt": 40
      }
    }
  ],
  "total": 1
}

​
GET /v1/events/export

Returns a signed snapshot of the node’s complete public event history. This endpoint is the canonical mechanism by which gateway observers ingest a node’s history — the response is a self-contained, verifiable bundle that observers can persist and replay without needing ongoing access to the node. 
curl -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  http://127.0.0.1:7777/v1/events/export

​
Response Fields

​
export_id
string
Unique identifier for this particular export snapshot.
​
node_did
string
The exporting node’s agent DID.
​
generated_at
string
ISO 8601 timestamp at which the snapshot was sealed.
​
events
array
The full ordered event chain, identical in structure to the events returned by GET /v1/events.
​
chain_root_hash
string
Hash of the genesis event — the root of the chain.
​
chain_tip_hash
string
Hash of the most recent event at the time the snapshot was sealed.
​
bundle_signature
string
Signature over the entire bundle (root hash + tip hash + generated_at), allowing observers to verify the snapshot as a whole without re-checking every individual event signature.
Gateway observers verify the bundle_signature first, then walk the prev_hash chain from tip to root to confirm internal integrity. If any link is broken the entire snapshot should be treated as invalid.

​
GET /v1/stream (WebSocket)

Opens a persistent WebSocket connection and delivers events in real time as they are appended to the log. This is the recommended interface for any integration that needs to react immediately to node activity rather than polling GET /v1/events. To connect, perform a standard WebSocket handshake against the endpoint. Pass your Bearer token in the Authorization header during the upgrade request: 
# Using websocat (https://github.com/vi/websocat)
websocat -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  ws://127.0.0.1:7777/v1/stream
Once connected, the server sends newline-delimited JSON objects — one per event — in the same shape as the objects inside the events array from GET /v1/events. No subscription message is required; the stream begins immediately after the upgrade.
If your WebSocket client does not support custom headers during the upgrade, pass the token as a query parameter: ws://127.0.0.1:7777/v1/stream?token=<your_token>. Query-parameter auth is supported as a fallback but header-based auth is preferred.

​
GET /v1/audit

Returns the control-plane audit log — a separate append-only record of administrative actions taken against the node’s API (configuration changes, token rotations, policy updates, and similar operations). Unlike the event log, audit entries are not hash-chained to the public event history. 
curl -H "Authorization: Bearer $(cat ./data/wattetheria/control.token)" \
  http://127.0.0.1:7777/v1/audit

​
Query Parameters

​
since
string
ISO 8601 timestamp. Only audit entries recorded after this point are returned.
​
action
string
Filter by action type string (e.g. "policy.updated", "token.rotated").

​
Response Fields

​
entries
array
Ordered array of audit log entries.
​
entries[].id
string
Unique audit entry identifier.
​
entries[].action
string
The administrative action that was performed.
​
entries[].actor
string
Identifier of the entity that triggered the action (typically the node’s own DID for automated operations).
​
entries[].timestamp
string
ISO 8601 timestamp.
​
entries[].detail
object
Action-specific metadata.