Agent Overview

Terminal agent architecture and SDK options

Terminal Agent

The WatchTower terminal agent runs on each POS device and connects to the platform via bidirectional gRPC streaming. It reports heartbeats, GPS location, and transactions in real-time, and receives commands (block, unblock, config updates) from the platform.

Architecture

┌─────────────────────┐         gRPC (TLS)         ┌──────────────────┐
│   POS Terminal      │ ◄──────────────────────── ► │  WatchTower      │
│                     │                             │  Platform        │
│  ┌───────────────┐  │   Heartbeats (30s)  ──►    │                  │
│  │ Your POS App  │  │   Transactions      ──►    │  Ingestion GW    │
│  │               │  │   Status Changes    ──►    │       │          │
│  │  ┌─────────┐  │  │                             │       ▼          │
│  │  │WatchTower│  │  │   Block Commands   ◄──    │  NATS JetStream  │
│  │  │  SDK     │  │  │   Config Updates   ◄──    │       │          │
│  │  └─────────┘  │  │   Ping/Keepalive   ◄──    │       ▼          │
│  └───────────────┘  │                             │  Rules Engine    │
│                     │                             │  Dashboard       │
└─────────────────────┘                             └──────────────────┘

SDK vs Standalone Agent

	SDK (Recommended)	Standalone APK
Integration	Embedded in your POS app	Separate app installed on terminal
Transactions	Reports transactions as they happen	Cannot access other apps’ transaction data
Block Commands	App can disable payment flow directly	Cannot control other apps
Setup	Add Gradle dependency	Install APK
Best For	Terminal developers building POS apps	Monitoring terminals you don’t control

Available SDKs

Language	Package	Status
Kotlin (Android)	io.watchtower:agent-sdk	✅ Available
Go	github.com/watchtower-io/agent-go	🚧 Coming soon
Python	pip install watchtower-agent	🚧 Coming soon

Key Features

• Bidirectional gRPC streaming — single persistent connection for all data
• Automatic reconnection — exponential backoff (1s → 60s) with jitter
• Offline queue — transactions stored in local SQLite when disconnected, flushed on reconnect
• GPS tracking — uses Android LocationManager (no Google Play Services required)
• Remote configuration — heartbeat interval adjustable from the platform
• Block/Unblock commands — platform can disable terminal transactions in real-time

Authentication

Each terminal authenticates with an agent API key (wt_agent_*). The key is included in the first gRPC message. Generate keys from the WatchTower dashboard under Settings → API Keys.

Data Flow

Agent → Platform (upstream):

• Heartbeats — GPS coordinates, battery level, signal strength, uptime (every 30s)
• Transactions — amount, type, status, reference, response code (real-time)
• Status changes — terminal state transitions

Platform → Agent (downstream):

• Block command — soft block (agent-enforced) or hard block (processor-level)
• Unblock command — resume transaction processing
• Config update — change heartbeat/GPS intervals remotely
• Ping — keep-alive signal