0watch Quickstart

Monitor your first agent wallet in 5 minutes.

0watch is an on-chain monitoring service for agent wallets. It indexes transactions on Base, detects anomalies, and exposes a REST API for querying activity and alerts.

Prerequisites

Step 1 — Install dependencies

npm install

Step 2 — Start the services

0watch has two processes: the API server and the indexer. Run both.

Terminal 1 — API server:

npm run api

You should see:

[0watch-api] listening on port 3001

Terminal 2 — Indexer:

npm run indexer

You should see:

[0watch-indexer] starting block watcher

The indexer polls Base every 2 seconds for new blocks and writes to SQLite at data/0watch.db. The database and schema are created automatically.

Step 3 — Add your agent wallet

Replace the address below with your agent's wallet address.

curl -X POST http://localhost:3001/api/wallets \
  -H 'Content-Type: application/json' \
  -d '{"address": "0xYourWalletAddress", "label": "my agent"}'

Response:

{
  "address": "0xyourwalletaddress",
  "label": "my agent"
}

The wallet is now in the watch list. The indexer will pick up its transaction history on the next polling cycle.

Step 4 — Check transaction history

curl http://localhost:3001/api/wallets/0xYourWalletAddress/transactions

Response:

{
  "address": "0xyourwalletaddress",
  "count": 3,
  "transactions": [
    {
      "hash": "0xabc...",
      "blockNumber": 27480000,
      "timestamp": 1741500000,
      "fromAddress": "0xyourwalletaddress",
      "toAddress": "0x...",
      "valueWei": "100000000000000000",
      "txType": "eth_transfer",
      "gasUsed": 21000,
      "status": 1,
      "chainId": 8453
    }
  ]
}

valueWei is a string — agent wallets often move amounts that overflow JavaScript's Number.MAX_SAFE_INTEGER. Parse it with BigInt().

Step 5 — Check for alerts

curl http://localhost:3001/api/wallets/0xYourWalletAddress/alerts

Response if the indexer detected anomalies:

{
  "address": "0xyourwalletaddress",
  "count": 1,
  "alerts": [
    {
      "walletAddress": "0xyourwalletaddress",
      "txHash": "0xabc...",
      "anomalyType": "large_transfer",
      "severity": "high",
      "details": {},
      "detectedAt": 1741550000000
    }
  ]
}

Alert severities: low, medium, high, critical.

Common operations

List all watched wallets

curl http://localhost:3001/api/wallets

Stop watching a wallet

curl -X DELETE http://localhost:3001/api/wallets/0xYourWalletAddress

Limit results

# Last 10 transactions
curl 'http://localhost:3001/api/wallets/0xYourWalletAddress/transactions?limit=10'

# Last 5 alerts
curl 'http://localhost:3001/api/wallets/0xYourWalletAddress/alerts?limit=5'

Health check

curl http://localhost:3001/api/health
# {"status":"ok","timestamp":1741550000000}

Configuration

Env var Default Description
API_PORT 3001 Port the API server listens on
DB_PATH data/0watch.db Path to the SQLite database

Next steps