Project Info

TokenWatcher – AI Cost & Observability Platform

The Problem As AI applications move into production, developers often know how much they're spending only after receiving their monthly invoice. They lack visibility into which models, endpoints, users, or features are driving costs, increasing latency, or generating failures. Existing dashboards expose raw API metrics, but they rarely provide actionable insights that help engineering teams understand, optimize, and control AI infrastructure. Our Solution TokenWatcher is an AI observability platform that helps developers monitor, analyze, and optimize production AI applications. It provides a unified dashboard for AI telemetry across multiple providers, allowing teams to: Monitor token usage and API costs Track latency and request failures Analyze model and endpoint performance Forecast future AI spending Detect anomalies Receive AI-powered optimization recommendations Instead of manually combining logs, spreadsheets, and invoices, developers get real-time visibility into how their AI systems behave. Key Features Real-time AI telemetry dashboard Multi-workspace support Token, cost, latency, and request analytics Model and endpoint performance dashboards Cost forecasting AI-powered insights and recommendations SDK for telemetry instrumentation Secure API key management Telegram integration through OpenClaw Live updates using Server-Sent Events (SSE) Built with GPT-5.6 and Codex For OpenAI Build Week, GPT-5.6 and Codex became an integral part of our development workflow. We used Codex extensively to accelerate implementation by: Debugging backend services Refactoring TypeScript modules Improving project architecture Implementing new dashboard functionality Resolving integration issues Generating and refining documentation Speeding up testing and development iterations GPT-5.6 also helped with architecture decisions, implementation planning, debugging strategies, documentation, and feature refinement throughout development. Rather than simply generating code, Codex acted as a collaborative engineering assistant that significantly accelerated the development of a production-ready platform. Technical Architecture TokenWatcher consists of four major components: TypeScript SDK for telemetry collection Express + PostgreSQL backend React analytics dashboard OpenClaw-powered Telegram interface Telemetry collected by the SDK is securely ingested by the backend, processed into analytics, and streamed to the dashboard in real time. The same analytics layer powers forecasting, reports, recommendations, and conversational Telegram interactions. Challenges Building an observability platform required balancing performance with flexibility. Some of the biggest challenges included: Designing a scalable telemetry ingestion pipeline Handling workspace isolation securely Maintaining real-time dashboard updates Building reliable analytics and forecasting Integrating Telegram workflows without compromising security What We Learned Building TokenWatcher reinforced how quickly AI infrastructure complexity grows in production. Observability is no longer optional—teams need visibility into token usage, costs, latency, and reliability from day one. Combining traditional analytics with AI-powered recommendations creates a much better developer experience than static dashboards alone. What's Next Our roadmap includes: Support for additional LLM providers Advanced anomaly detection Deeper forecasting models More conversational AI workflows Expanded reporting and export capabilities Enterprise deployment improvements

TokenWatch is a production telemetry, analytics, and Telegram delivery platform for AI applications. It instruments your application directly, stores request telemetry in PostgreSQL, and turns raw usage data into dashboards, forecasts, reports, and Telegram replies.

What problem it solves

Many AI products know their model invoices before they know their product behavior. TokenWatch closes that gap by showing:

▪️ what each request costs ▪️ which models and endpoints are driving spend ▪️ how latency and errors change over time ▪️ what should be optimized next ▪️ how to surface the same data in Telegram

Solution

TokenWatch keeps the instrumentation simple:

▪️ the SDK captures telemetry at the source ▪️ the backend authenticates, normalizes, and stores requests ▪️ the analytics engine derives dashboards, forecasts, reports, and recommendations from the same table ▪️ the dashboard and Telegram bot read the same workspace-scoped data ▪️ OpenClaw bridges Telegram traffic back to TokenWatch safely

Key Features

▪️ workspace-isolated telemetry and analytics ▪️ bounded SDK queueing, batching, retries, and shutdown flush ▪️ live dashboard updates over SSE ▪️ request log search, filters, and exports ▪️ forecasts, reports, recommendations, anomalies, and Copilot tools ▪️ Telegram bot integration through BotFather and OpenClaw ▪️ production-ready auth, API keys, and secret handling

Architecture Overview

flowchart LR
  App[Developer Application]
  SDK[TokenWatch SDK]
  API[Backend API]
  DB[(PostgreSQL)]
  Engine[Analytics Engine]
  Dash[Dashboard]
  TG[Telegram Integration]
  OC[OpenClaw Agent]
  User[User]

  App --> SDK --> API --> DB --> Engine --> Dash --> TG --> OC --> User

The detailed system guide lives in docs/architecture.md.

Technology Stack

Layer	Stack
Backend	Node.js, Express, TypeScript, PostgreSQL
Frontend	React 18, Vite, React Query, Tailwind, shadcn/ui
SDK	TypeScript, fetch-based transport, bounded queue, retries
Telegram bridge	OpenClaw, Telegram Bot API
Realtime	Server-Sent Events

Folder Structure

Folder	Responsibility
`backend/`	API, auth, ingest, analytics, storage, notifications
`frontend/`	Dashboard, settings, docs pages, charts, and SSE client
`sdk/`	Public telemetry SDK published to npm
`openclaw/`	Stateless Telegram bridge and intent router
`docs/`	Canonical product, platform, and contributor documentation
`backend/src/db/`	Database schema and startup schema application

Installation

Install the workspace packages you need:

cd backend
npm install

cd ../frontend
npm install

cd ../sdk
npm install

cd ../openclaw
npm install

Environment Variables

The full environment matrix is documented in docs/deployment.md. The most important variables are:

Component	Variables
Backend	`DATABASE_URL`, `JWT_SECRET`, `CORS_ORIGIN`, `TOKENWATCHER_SECRET_ENCRYPTION_KEY`, `OPENCLAW_INTERNAL_SECRET`, `OPENCLAW_PUBLIC_URL`, `RESEND_API_KEY`, `RESEND_FROM_EMAIL`, `X402_ENABLED`, `X402_MODE`, `X402_GATEWAY_URL`, `X402_API_KEY`, `X402_API_SECRET`, `X402_MERCHANT_ID`, `X402_NETWORK`, `X402_CHAIN_ID`, `X402_PAYMENT_TOKEN`, `X402_RECEIVING_WALLET`, `X402_ANALYZE_COST_PRICE_USD`, `X402_MOCK_PAYMENT_TOKEN`
Frontend	`VITE_TOKENWATCH_API_URL`
OpenClaw	`TOKENWATCHER_API_URL`, `OPENCLAW_INTERNAL_SECRET`, `OPENCLAW_PORT`, `OPENCLAW_HOST`, `TOKENWATCHER_TIMEOUT_MS`, `TOKENWATCHER_USER_AGENT`

Running Locally

# Backend
cd backend
npm run dev

# Frontend
cd frontend
npm run dev

# OpenClaw
cd openclaw
npm run build
npm start

The backend listens on http://localhost:3001 by default. The frontend runs on Vite's dev server. OpenClaw listens on http://localhost:3300 by default.

Running with Docker

No official Docker workflow is committed yet. Use the local commands above or add Docker assets if your deployment strategy needs them.

SDK Usage

import { TokenWatch } from "@zn_/tokenwatch";

TokenWatch.init({
  apiUrl: "http://localhost:3001",
  apiKey: process.env.TOKENWATCH_API_KEY!,
});

await TokenWatch.track("llm.request.completed", {
  route: "/api/chat",
  provider: "openai",
  model: "gpt-4o",
  input_tokens: 120,
  output_tokens: 80,
  cost_usd: 0.0042,
  latency_ms: 640,
});

await TokenWatch.flush();

The full SDK guide is in docs/sdk.md.

Telemetry Flow

The developer application emits telemetry through the SDK.
The SDK batches and sends the payload to the backend ingest API.
The backend authenticates the workspace and stores telemetry in requests.
Analytics, forecasts, reports, and recommendations are derived from the same source table.
The dashboard refreshes through SSE and workspace-scoped queries.
Telegram and OpenClaw read the same workspace data to answer user requests.

See docs/architecture.md for the full lifecycle.

ERC-8004 And x402

TokenWatcher is registered externally as ERC-8004 Agent #80 on GOAT Mainnet. The application exposes that public identity at GET /api/agent and publishes three paid capabilities:

POST /api/agent/analyze-cost
POST /api/agent/optimize-cost
POST /api/agent/health

Each paid capability uses x402 payment protection:

the server returns a 402 Payment Required challenge when no payment proof is present,
the client submits payment using the configured GOAT merchant path,
the backend binds the payment to the requested capability before executing its logic,
the backend verifies the payment server-side, rejects expired or mismatched payments, and reuses the canonical telemetry pipeline for analytics and intelligence results.

Local development can use X402_MODE=mock together with X402_MOCK_PAYMENT_TOKEN. Production must use real x402 verification and must not enable mock mode.

The paid capabilities remain workspace-scoped and still use the existing auth and ownership rules after payment verification.

Dashboard Overview

The dashboard is documented in docs/frontend.md. The main screens are:

▪️ Overview ▪️ Requests ▪️ Models ▪️ Endpoints ▪️ Settings ▪️ Agent & payments

Each screen is backed by the same telemetry source of truth.

Telegram Integration

Telegram setup lives in docs/telegram.md. In short:

▪️ create a bot in BotFather ▪️ paste the token into Settings -> Telegram Integration ▪️ connect the bot ▪️ send the bot one message ▪️ use Test to confirm delivery

OpenClaw Integration

OpenClaw is the stateless Telegram bridge used by TokenWatch. Read the guide in docs/openclaw.md for the webhook flow, intent routing, and tool execution model.

Built with GPT-5.6 & Codex

TokenWatcher was developed and refined with the help of GPT-5.6 and Codex throughout the project lifecycle.

Codex served as an AI pair programmer, accelerating development by helping with:

Debugging backend and frontend issues
Refactoring TypeScript modules for better maintainability
Implementing new features and production-ready workflows
Resolving API integration and SDK issues
Improving project architecture and code organization
Generating and refining technical documentation
Assisting with testing, code reviews, and optimization

During development, Codex was used across numerous engineering tasks, including production readiness audits, telemetry pipeline improvements, SDK stabilization, onboarding enhancements, Telegram integration, adapter verification, bug fixes, and documentation updates.

GPT-5.6 was also used to reason through architecture decisions, implementation strategies, debugging approaches, and feature planning, significantly accelerating the development of TokenWatcher while maintaining full developer oversight of the final implementation.

Deployment

Deployment guidance is in docs/deployment.md. It covers:

▪️ frontend deployment ▪️ backend deployment ▪️ OpenClaw deployment ▪️ database setup ▪️ production checklist

Roadmap

▪️ more Telegram commands and richer conversational shortcuts ▪️ broader report export formats ▪️ deeper forecasting and recommendation surfaces ▪️ multi-instance realtime hardening ▪️ improved deployment automation and container support

Contributing

Please read docs/contributing.md before opening a pull request.

License

MIT. The SDK package declares MIT in sdk/package.json.

Acknowledgements

Built with the work of the TokenWatch maintainers and the open-source ecosystem behind Express, React, Vite, PostgreSQL, and Telegram Bot APIs.

Analysis

Compare with all teams

View

Metric

Zainab Travadi
5

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

CSSIn code
ExpressIn code
HTMLIn code
JavaScriptIn code
PostgreSQLIn code
ReactIn code
Tailwind CSSIn code
TypeScriptIn code
Node.jsClaimed

8 of 9 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

CodexConfig

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

1.2 MB

Source files

259

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.