gRPC Protocol Reference

Terminal agent gRPC message and service definitions

gRPC Protocol Reference

The WatchTower agent communicates via a single bidirectional gRPC streaming RPC.

If you’re using the Kotlin SDK, you don’t need to implement the protocol directly.

Service

service TerminalAgent {
  rpc Connect(stream AgentMessage) returns (stream PlatformCommand);
}

Agent → Platform

Message	Fields	Description
Heartbeat	lat, lng, battery_pct, signal_strength, uptime_secs	Terminal health check (every 30s)
TransactionEvent	id, type, amount, currency, status, reference, response_code, metadata	Payment transaction report
StatusChange	old_status, new_status, reason	Terminal state transition

Platform → Agent

Message	Fields	Description
BlockCommand	reason, block_type (“soft”/“hard”)	Disable transaction processing
UnblockCommand	reason	Resume processing
ConfigUpdate	heartbeat_interval_secs, gps_interval_secs	Remote config change
Ping	(empty)	Keep-alive

Authentication

The first AgentMessage must include terminal_id (serial number) and api_key. The server validates the key and resolves the serial number to a terminal UUID. Stream terminates if auth fails.

Full Protocol Definition

See the complete .proto file: backend/proto/agent/v1/agent.proto