Skip to main content
The Watch Tower includes a built-in HTTP API server that provides version information, configuration details, database dumps, and Prometheus metrics. The API server starts automatically when running the watch-tower in watch mode.

​
Default configuration

The API server starts automatically on port 8080 when running commands that watch the blockchain. 
yarn cli run --config-path ./config.json
# API server running on http://localhost:8080

​
Changing the port

Use the --api-port option to specify a custom port: 
yarn cli run --config-path ./config.json --api-port 3000

​
Available endpoints

​
GET /api/version

Returns version information about the running Watch Tower instance. 
curl http://localhost:8080/api/version
Response: 
{
  "version": "1.2.3",
  "name": "@cowprotocol/watch-tower",
  "description": "Watch-tower for CoW Protocol conditional orders",
  "dockerImageTag": "v1.2.3"
}
The dockerImageTag field is populated from the DOCKER_IMAGE_TAG environment variable when running in Docker.

​
GET /config

Returns the current configuration of all monitored networks. 
curl http://localhost:8080/config
Response: 
[
  {
    "chainId": 1,
    "contract": "0x...",
    "deploymentBlock": 17883049,
    "dryRun": false,
    "filterPolicy": {
      "defaultAction": "ACCEPT",
      "owners": {},
      "handlers": {},
      "transactions": {},
      "conditionalOrderIds": {}
    },
    "pageSize": 5000,
    "processEveryNumBlocks": 1,
    "addresses": ["0x..."]
  }
]

​
GET /api/dump/:chainId

Dumps the entire database for a specific chain ID. 
curl http://localhost:8080/api/dump/1
Replace 1 with the desired chain ID:
  • 1 - Ethereum Mainnet
  • 11155111 - Sepolia
  • 42161 - Arbitrum One
  • 43114 - Avalanche
  • 8453 - Base
  • 100 - Gnosis Chain
  • 137 - Polygon
The database dump includes all conditional orders, owners, and the last processed block for the specified chain.

​
GET /metrics

Exposes Prometheus-compatible metrics for monitoring. 
curl http://localhost:8080/metrics
The metrics endpoint provides:
  • Process metrics (CPU, memory usage)
  • Node.js metrics
  • Custom Watch Tower metrics
Integrate the /metrics endpoint with Prometheus, Grafana, or other monitoring tools to track Watch Tower performance.

​
GET /health

Returns health status of all monitored chains. 
curl http://localhost:8080/health
Response: 
{
  "overallHealth": true,
  "chains": {
    "1": {
      "healthy": true,
      "lastBlock": 12345678
    }
  }
}
  • Returns HTTP 200 when healthy
  • Returns HTTP 503 when unhealthy

​
GET /

Root endpoint returns a simple message: 
curl http://localhost:8080/
Response: 
🐮 Moooo!

​
Disabling the API server

To run the Watch Tower without the API server, use the --disable-api flag: 
yarn cli run --config-path ./config.json --disable-api
Disabling the API server also disables the Prometheus metrics endpoint, which may impact monitoring capabilities.

​
Docker image tag

When running in Docker, set the DOCKER_IMAGE_TAG environment variable to include the Docker image tag in the /api/version response: 
docker run --rm -it \
  -e DOCKER_IMAGE_TAG=v1.2.3 \
  -v "$(pwd)/config.json:/config.json" \
  ghcr.io/cowprotocol/watch-tower:v1.2.3 \
  run --config-path /config.json
This helps identify which Docker image version is running, especially useful in production environments.

​
Port mapping with Docker

When running with Docker, remember to map the container port to your host: 
docker run --rm -it \
  -p 8080:8080 \
  -v "$(pwd)/config.json:/config.json" \
  ghcr.io/cowprotocol/watch-tower:latest \
  run --config-path /config.json

​
Example usage

​
Check version and health

# Start the watch-tower
yarn cli run --config-path ./config.json

# In another terminal, check version
curl http://localhost:8080/api/version

# Check health
curl http://localhost:8080/health

# View configuration
curl http://localhost:8080/config | jq

​
Monitor with Prometheus

Add the Watch Tower to your Prometheus configuration:
prometheus.yml
scrape_configs:
  - job_name: 'watch-tower'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: '/metrics'

​
Debugging database state

# Dump database for Ethereum Mainnet
curl http://localhost:8080/api/dump/1 | jq > mainnet-dump.json

# Dump database for Arbitrum One
curl http://localhost:8080/api/dump/42161 | jq > arbitrum-dump.json

Build docs developers (and LLMs) love

Get started for freeTalk to us