nous-token 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nousworld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,176 @@
+# nous-token Protocol v2
+
+## Overview
+
+nous-token is an open-source AI usage tracking protocol. A transparent gateway proxies LLM API calls, extracts real token consumption from provider responses, and signs a **receipt** for every call. Users own their receipts and decide what to store on-chain.
+
+The gateway guarantees data authenticity. It does not dictate storage format.
+
+## How It Works
+
+```
+User → Plugin/CLI/SDK → Gateway → LLM Provider (any)
+                           ↓            ↓
+                    hash(API key)    extract .usage
+                    X-Nous-User      auto-detect format
+                           ↓
+                     sign receipt (ECDSA) + store in D1 + update Merkle tree
+                           ↓
+                   User fetches receipts → decides what to store on-chain
+```
+
+### Provider Routing
+
+Two ways to route through the gateway:
+
+1. **Shortcut prefix**: `/{provider}/v1/...` for known providers (openai, anthropic, deepseek, gemini, groq, together, mistral, openrouter, fireworks, perplexity, cohere)
+2. **Custom upstream**: Set `X-Nous-Upstream: https://api.example.com` header to proxy any OpenAI-compatible API
+
+Usage extraction auto-detects response format (OpenAI, Anthropic, or Gemini style). No provider registration needed.
+
+## The Receipt
+
+Every API call through the gateway produces a signed receipt:
+
+```json
+{
+  "p": "nous",
+  "v": 1,
+  "type": "receipt",
+  "id": 42,
+  "ts": "2026-04-02T12:00:00.000Z",
+  "user": "a1b2c3d4...",
+  "provider": "anthropic",
+  "model": "claude-opus-4-6",
+  "input": 5000,
+  "output": 2000,
+  "cache_read": 0,
+  "cache_write": 0,
+  "total": 7000,
+  "leaf": "sha256...",
+  "sig": "ecdsa_signature..."
+}
+```
+
+**Verification**: `leaf` = SHA-256(`ts|user|provider|model|input|output|cache_read|cache_write|total`). `sig` = ECDSA-P256-SHA256 signature over `leaf`. Verify with the gateway's public key at `/api/pubkey`.
+
+The gateway signs the leaf hash, not the JSON. This means:
+- Anyone can independently recompute `leaf` from the fields and verify it matches
+- The signature proves the gateway attested to this exact data
+- No ambiguity from JSON serialization differences
+
+## What the Gateway Guarantees
+
+1. **Token counts are real** — extracted from the actual provider response, not estimated
+2. **Receipts are signed** — ECDSA P-256 signature on each record's leaf hash
+3. **History is append-only** — Merkle Mountain Range makes deletion/modification detectable
+4. **Data is public** — anyone can pull all records and verify independently
+
+## What the Gateway Does NOT Dictate
+
+- What the user stores on-chain (individual receipts, summaries, or nothing)
+- How the user calculates cost (different plans have different rates)
+- What fields the user displays publicly
+- When the user stores proof
+
+## Wallet Identity
+
+Users identify themselves with an Ethereum wallet address. The wallet is the permanent identity — API keys rotate, wallets don't.
+
+### How it works
+
+1. User runs `npx nous-token setup`, enters wallet address + API key
+2. CLI computes `user_hash = SHA-256(api_key)[0:16]` locally, sends `{api_key, wallet}` to `/api/link`
+3. Gateway computes the same hash, verifies it exists in records, links all records to the wallet
+4. Future API calls include `?wallet=0x...` in the base URL (set by CLI) or `X-Nous-Wallet` header (set by plugin)
+5. Gateway stores wallet with each new record and backfills old records for the same hash
+
+### Binding rules
+
+- **First bind wins**: Once a hash is linked to a wallet, it cannot be relinked to a different wallet. This prevents rebinding with expired or leaked API keys.
+- **Multiple hashes per wallet**: A user can link multiple API keys (hashes) to the same wallet. The leaderboard aggregates all hashes under one wallet.
+- **Wallet validation**: Must be a valid Ethereum address (`0x` + 40 hex chars). Invalid addresses are silently ignored.
+
+### Leaderboard aggregation
+
+The leaderboard uses `CASE WHEN wallet != '' THEN wallet ELSE user_hash END` as the identity key. Users with wallets are aggregated by wallet; users without wallets fall back to hash-based identity.
+
+## Privacy by Structure
+
+Not by promise — by code. Audit the source:
+
+- **API Key**: Plugin computes SHA-256 hash locally, sends only the hash via `X-Nous-User` header. If no `X-Nous-User` is present (e.g., Claude Code via base URL), the gateway reads the API key from `Authorization` header **solely** to compute the same hash. The key is never stored, logged, or retained — it exists in Worker memory only for the duration of one SHA-256 call, then is discarded by GC. The `X-Nous-Upstream` header (if used) is stripped before forwarding.
+- **Prompts**: `request.body` is piped directly to the provider. No `.text()`, `.json()`, or `.getReader()` is called on it.
+- **Responses (streaming)**: Tee'd. One branch to user unchanged, other buffers last 4KB to extract `.usage` only.
+- **Responses (non-streaming)**: Full body in Worker memory (V8 isolate, GC'd after request) to extract `.usage`. Never reads `.choices`, `.content`.
+- **Storage**: D1 stores: timestamp, user_hash, provider, model, token counts, leaf_hash, receipt_sig. No prompts, no responses, no keys.
+
+## Tamper Detection: Merkle Mountain Range
+
+Each receipt's `leaf` hash is appended to a Merkle Mountain Range (MMR). The MMR root changes if any single record is modified.
+
+### Verification Levels
+
+| Level | How | Cost |
+|---|---|---|
+| **Single receipt** | Recompute `leaf` from fields, verify `sig` with pubkey | O(1) |
+| **Full tree** | Pull all records, rebuild MMR, compare root | O(n) |
+| **External anchor** | Compare root with published root (GitHub, on-chain) | O(1) |
+
+### Sentinel
+
+Anyone can run an independent verifier:
+
+```
+npx tsx sentinel.ts --watch
+```
+
+The sentinel verifies leaf hashes, receipt signatures, and Merkle root integrity. No API key needed.
+
+## On-Chain Storage
+
+Users choose how to store proof on BASE (or any EVM chain):
+
+### Option 1: Individual Receipts
+
+Fetch signed receipts via `/api/user/:hash/receipts`, store as calldata. Each receipt is independently verifiable.
+
+### Option 2: Summary
+
+Request a signed summary via `POST /api/sign`, store as calldata. The summary aggregates multiple receipts into a single signed attestation.
+
+Both options use self-to-self transactions with data as calldata. No smart contract needed — the ECDSA signature is the proof.
+
+## Trust Model
+
+1. **Code is open-source** — anyone can audit
+2. **Per-call signatures** — every receipt is signed by the gateway
+3. **Merkle tree** — tampering with any record breaks the tree
+4. **Sentinels** — independent verifiers monitor continuously
+5. **On-chain anchoring** — published roots prevent history rewrites
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/{provider}/v1/...` | * | Proxy to LLM provider (append `?wallet=0x...` for identity) |
+| `/api/leaderboard` | GET | Top users by tokens (`?days=30`, `?days=0` for all time) |
+| `/api/leaderboard/model` | GET | Per-model user ranking (`?model=...&days=30`) |
+| `/api/models` | GET | Usage breakdown by model (aggregated across providers) |
+| `/api/stats` | GET | Global totals |
+| `/api/wallet/{address}` | GET | Usage for a wallet (all linked hashes aggregated) |
+| `/api/user/{hash}` | GET | Single user aggregated stats |
+| `/api/user/{hash}/receipts` | GET | Signed receipts (paginated) |
+| `/api/link` | POST | Link hash to wallet (`{api_key, wallet}`) — first bind wins |
+| `/api/records` | GET | Raw records for sentinel verification |
+| `/api/chain` | GET | Merkle root and MMR state |
+| `/api/sign` | POST | Signed summary (optional aggregation) |
+| `/api/pubkey` | GET | Gateway's ECDSA public key |
+
+## Auditing the Gateway
+
+Search the source to verify privacy claims:
+- `authorization`, `x-api-key` → read only to compute user hash when `X-Nous-User` is absent; value is not stored or logged
+- `request.body` → only as argument to `fetch()` (piped, not consumed)
+- `.content`, `.choices`, `.message` → absent from data-reading code
+- `headers.get()` → only for `x-nous-user`, `x-nous-upstream`, `x-nous-wallet`, and `content-type`

package/README.md

@@ -0,0 +1,137 @@
+# nous-token
+
+Open-source AI usage tracker. Every token, verified.
+
+One command to track all your AI spending across every provider. Your data is signed, verifiable, and yours.
+
+**Live leaderboard**: [token.nousai.cc](https://token.nousai.cc)
+
+## Quick Start
+
+```bash
+npx nous-token setup
+```
+
+The CLI asks two things:
+1. **Wallet address** (0x...) — your permanent identity across API keys
+2. **API key** — used locally to compute your hash, never sent anywhere
+
+Then it auto-detects your AI tools (Claude Code, Cursor, Python SDKs, etc.) and routes them through the gateway.
+
+## How It Works
+
+```
+You → AI Tool → Gateway → LLM Provider
+                  ↓
+            extract .usage from response
+            sign receipt (ECDSA)
+            record in Merkle tree
+                  ↓
+            token.nousai.cc
+```
+
+The gateway is a transparent proxy. It forwards your request untouched, reads only the `.usage` field from the response, signs a receipt, and records it. Your prompts and completions are never read or stored.
+
+## Supported Providers
+
+Works with any OpenAI-compatible API out of the box:
+
+| Provider | Route |
+|----------|-------|
+| OpenAI | `/openai/v1/...` |
+| Anthropic | `/anthropic/...` |
+| DeepSeek | `/deepseek/v1/...` |
+| Google Gemini | `/gemini/...` |
+| Groq | `/groq/v1/...` |
+| Together | `/together/v1/...` |
+| Mistral | `/mistral/v1/...` |
+| OpenRouter | `/openrouter/api/v1/...` |
+| Fireworks | `/fireworks/v1/...` |
+| Perplexity | `/perplexity/v1/...` |
+| Cohere | `/cohere/v1/...` |
+| **Any custom** | Set `X-Nous-Upstream` header |
+
+## Wallet Identity
+
+Your wallet address is your permanent identity. API keys expire and rotate — your wallet doesn't.
+
+- Run `npx nous-token setup` with your wallet address
+- All usage across any API key links to your wallet
+- Switch keys, switch machines — your history follows you
+- First bind is permanent (prevents rebind with leaked keys)
+
+## Privacy by Structure
+
+Not by promise — by code. [Audit the source](gateway/src/index.ts).
+
+| Data | What happens |
+|------|-------------|
+| API Key | Hashed (SHA-256) for identity. Never stored. |
+| Prompts | `request.body` piped directly to provider. Never read. |
+| Responses (streaming) | Tee'd. Only last 4KB buffered to extract `.usage`. |
+| Responses (non-streaming) | In V8 isolate memory. Only `.usage` accessed. GC'd after request. |
+| Storage | D1 stores: timestamp, user_hash, wallet, provider, model, token counts. Nothing else. |
+
+## Verification
+
+Every API call produces a signed receipt. Anyone can verify independently.
+
+### Run a sentinel
+
+```bash
+npx tsx sentinel.ts          # one-shot verify
+npx tsx sentinel.ts --watch  # continuous monitoring
+```
+
+The sentinel pulls all records, recomputes leaf hashes, rebuilds the Merkle tree, and verifies receipt signatures. No API key needed.
+
+### Trust model
+
+1. **Code is open-source** — audit everything
+2. **Per-call ECDSA signatures** — every receipt is signed
+3. **Merkle Mountain Range** — tampering breaks the tree
+4. **Sentinels** — independent verifiers anyone can run
+5. **On-chain anchoring** — store receipts on BASE or any EVM chain
+
+## API
+
+Gateway: `https://gateway.nousai.cc`
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/{provider}/v1/...` | * | Proxy to LLM provider |
+| `/api/leaderboard` | GET | Top users by tokens (`?days=30`, `?days=0` for all time) |
+| `/api/leaderboard/model` | GET | Per-model user ranking (`?model=...`) |
+| `/api/models` | GET | Usage breakdown by model |
+| `/api/stats` | GET | Global totals |
+| `/api/wallet/{address}` | GET | Usage for a wallet (all linked hashes) |
+| `/api/user/{hash}` | GET | Single user stats |
+| `/api/user/{hash}/receipts` | GET | Signed receipts (paginated) |
+| `/api/link` | POST | Link hash to wallet (`{api_key, wallet}`) |
+| `/api/records` | GET | Raw records for sentinel verification |
+| `/api/chain` | GET | Merkle root and MMR state |
+| `/api/sign` | POST | Signed summary for on-chain storage |
+| `/api/pubkey` | GET | Gateway's ECDSA public key |
+
+## Architecture
+
+```
+nous-token/
+├── gateway/          Cloudflare Worker — proxy + usage extraction + signing
+│   └── src/
+│       ├── index.ts      API routes + proxy logic
+│       ├── db.ts         D1 storage + Merkle Mountain Range
+│       ├── providers.ts  Usage format auto-detection (OpenAI/Anthropic/Gemini)
+│       └── stream.ts     Streaming response usage extraction
+├── web/              Cloudflare Pages — leaderboard frontend
+│   └── index.html
+├── cli/              CLI setup tool
+│   └── setup.ts
+├── index.ts          OpenClaw plugin
+├── sentinel.ts       Independent Merkle tree verifier
+└── PROTOCOL.md       Full protocol specification
+```
+
+## License
+
+MIT

package/cli/setup.ts

@@ -0,0 +1,306 @@
+#!/usr/bin/env npx tsx
+//
+// nous-token setup — one command to configure all AI tools
+//
+// Usage: npx nous-token setup
+//
+// Scans for installed AI tools, configures them to route through
+// the nous-token gateway for usage tracking.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { execSync } from "child_process";
+import { createHash } from "crypto";
+
+const GATEWAY = "https://gateway.nousai.cc";
+const HOME = homedir();
+const NOUS_CONFIG = join(HOME, ".nous-token");
+
+function loadWallet(): string {
+  try { return readFileSync(NOUS_CONFIG, "utf-8").trim(); } catch { return ""; }
+}
+
+function saveWallet(wallet: string): void {
+  writeFileSync(NOUS_CONFIG, wallet);
+}
+
+function gatewayUrl(path: string, wallet: string): string {
+  return wallet ? `${GATEWAY}${path}?wallet=${wallet}` : `${GATEWAY}${path}`;
+}
+
+interface Tool {
+  name: string;
+  detect: () => boolean;
+  configure: (wallet: string) => ConfigResult;
+}
+
+interface ConfigResult {
+  success: boolean;
+  message: string;
+}
+
+// ── Tool detectors and configurators ──
+
+const tools: Tool[] = [
+  // OpenClaw
+  {
+    name: "OpenClaw",
+    detect: () => {
+      try { execSync("which openclaw", { stdio: "ignore" }); return true; } catch { return false; }
+    },
+    configure: (_wallet: string) => {
+      try {
+        execSync("openclaw plugins install nous-token", { stdio: "inherit" });
+        return { success: true, message: "installed nous-token plugin" };
+      } catch {
+        return { success: false, message: "plugin install failed" };
+      }
+    },
+  },
+
+  // Claude Code
+  {
+    name: "Claude Code",
+    detect: () => {
+      const claudeDir = join(HOME, ".claude");
+      if (existsSync(claudeDir)) return true;
+      try { execSync("which claude", { stdio: "ignore" }); return true; } catch { return false; }
+    },
+    configure: (wallet: string) => {
+      return setShellEnv("ANTHROPIC_BASE_URL", gatewayUrl("/anthropic", wallet), "Claude Code");
+    },
+  },
+
+  // Cursor
+  {
+    name: "Cursor",
+    detect: () => {
+      const paths = [
+        join(HOME, ".cursor"),
+        join(HOME, "Library", "Application Support", "Cursor"),
+        join(HOME, ".config", "Cursor"),
+      ];
+      return paths.some(p => existsSync(p));
+    },
+    configure: (wallet: string) => {
+      const settingsPaths = [
+        join(HOME, "Library", "Application Support", "Cursor", "User", "settings.json"),
+        join(HOME, ".config", "Cursor", "User", "settings.json"),
+      ];
+      for (const sp of settingsPaths) {
+        if (existsSync(sp)) {
+          try {
+            const content = JSON.parse(readFileSync(sp, "utf-8"));
+            if (content["openai.baseUrl"]?.includes("nousai")) {
+              return { success: true, message: "already configured" };
+            }
+            content["openai.baseUrl"] = gatewayUrl("/openai/v1", wallet);
+            writeFileSync(sp, JSON.stringify(content, null, 2));
+            return { success: true, message: `set baseUrl in Cursor settings` };
+          } catch {
+            return { success: false, message: "failed to update Cursor settings" };
+          }
+        }
+      }
+      return { success: false, message: "Cursor settings file not found" };
+    },
+  },
+
+  // Codex CLI
+  {
+    name: "Codex",
+    detect: () => {
+      return existsSync(join(HOME, ".codex")) ||
+        (() => { try { execSync("which codex", { stdio: "ignore" }); return true; } catch { return false; } })();
+    },
+    configure: (wallet: string) => {
+      return setShellEnv("OPENAI_BASE_URL", gatewayUrl("/openai/v1", wallet), "Codex");
+    },
+  },
+
+  // Gemini CLI
+  {
+    name: "Gemini CLI",
+    detect: () => {
+      return existsSync(join(HOME, ".gemini")) ||
+        (() => { try { execSync("which gemini", { stdio: "ignore" }); return true; } catch { return false; } })();
+    },
+    configure: (wallet: string) => {
+      return setShellEnv("GOOGLE_GEMINI_BASE_URL", gatewayUrl("/gemini", wallet), "Gemini CLI");
+    },
+  },
+
+  // Python openai SDK
+  {
+    name: "Python (openai)",
+    detect: () => {
+      try { execSync("python3 -c 'import openai'", { stdio: "ignore" }); return true; } catch { return false; }
+    },
+    configure: (wallet: string) => {
+      return setShellEnv("OPENAI_BASE_URL", gatewayUrl("/openai/v1", wallet), "Python openai SDK");
+    },
+  },
+
+  // Python anthropic SDK
+  {
+    name: "Python (anthropic)",
+    detect: () => {
+      try { execSync("python3 -c 'import anthropic'", { stdio: "ignore" }); return true; } catch { return false; }
+    },
+    configure: (wallet: string) => {
+      return setShellEnv("ANTHROPIC_BASE_URL", gatewayUrl("/anthropic", wallet), "Python anthropic SDK");
+    },
+  },
+];
+
+// ── Shell env helper ──
+
+function setShellEnv(key: string, value: string, toolName: string): ConfigResult {
+  const shell = process.env.SHELL || "/bin/bash";
+  const rcFile = shell.includes("zsh") ? join(HOME, ".zshrc") : join(HOME, ".bashrc");
+
+  if (existsSync(rcFile)) {
+    const content = readFileSync(rcFile, "utf-8");
+    // Check if already configured with the exact same value
+    if (content.includes(`${key}="${value}"`)) {
+      return { success: true, message: "already configured" };
+    }
+    // Remove old nous-token setting if exists, then write new one
+    const lines = content.split("\n").filter(l => !(l.includes(`${key}=`) && l.includes("nousai")));
+    lines.push(`export ${key}="${value}"  # nous-token gateway`);
+    writeFileSync(rcFile, lines.join("\n"));
+  } else {
+    writeFileSync(rcFile, `export ${key}="${value}"  # nous-token gateway\n`);
+  }
+
+  // Also set in current process
+  process.env[key] = value;
+
+  const rcName = rcFile.includes("zsh") ? "~/.zshrc" : "~/.bashrc";
+  return { success: true, message: `set ${key} in ${rcName}` };
+}
+
+// ── Find first available API key ──
+
+function findFirstApiKey(): string | null {
+  const keys = [
+    process.env.OPENAI_API_KEY,
+    process.env.ANTHROPIC_API_KEY,
+    process.env.DEEPSEEK_API_KEY,
+    process.env.GEMINI_API_KEY,
+    process.env.GROQ_API_KEY,
+  ];
+  for (const key of keys) {
+    if (key) return key.replace(/^Bearer\s+/i, "");
+  }
+  return null;
+}
+
+function computeUserHash(): string | null {
+  const key = findFirstApiKey();
+  if (!key) return null;
+  return createHash("sha256").update(key).digest("hex").slice(0, 32);
+}
+
+// ── Prompt helper ──
+
+async function ask(prompt: string): Promise<string> {
+  process.stdout.write(prompt);
+  return new Promise<string>((resolve) => {
+    process.stdin.setEncoding("utf-8");
+    process.stdin.once("data", (chunk) => resolve(chunk.toString().trim()));
+    process.stdin.resume();
+  });
+}
+
+// ── Main ──
+
+console.log("");
+console.log("  \x1b[1mnous-token setup\x1b[0m\n");
+
+// Step 1: Wallet address
+let wallet = loadWallet();
+const walletArg = process.argv.find(a => /^0x[a-fA-F0-9]{40}$/.test(a));
+if (walletArg) {
+  wallet = walletArg.toLowerCase();
+} else if (!wallet) {
+  const input = await ask("  Wallet address (0x...): ");
+  if (/^0x[a-fA-F0-9]{40}$/.test(input)) {
+    wallet = input.toLowerCase();
+  } else if (input) {
+    console.log("  \x1b[33mInvalid address format.\x1b[0m\n");
+    process.exit(1);
+  }
+}
+
+if (wallet) {
+  saveWallet(wallet);
+  console.log(`  \x1b[36mWallet: ${wallet}\x1b[0m\n`);
+} else {
+  console.log("  \x1b[90mNo wallet. Run again with: npx nous-token setup 0x...\x1b[0m\n");
+  process.exit(0);
+}
+
+// Step 2: API key — read from env or ask
+let apiKey = findFirstApiKey();
+if (!apiKey) {
+  const input = await ask("  API key (sk-...): ");
+  if (input) {
+    apiKey = input.replace(/^Bearer\s+/i, "");
+  }
+}
+
+// Step 3: Link hash → wallet via gateway
+if (apiKey) {
+  const hash = createHash("sha256").update(apiKey).digest("hex").slice(0, 32);
+  console.log(`  \x1b[90mUser hash: ${hash}\x1b[0m`);
+  try {
+    const res = await fetch(`${GATEWAY}/api/link`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_key: apiKey, wallet }),
+    });
+    const data = await res.json() as { ok?: boolean; error?: string };
+    if (data.ok) {
+      console.log(`  \x1b[32m✓ Linked to wallet\x1b[0m\n`);
+    } else {
+      console.log(`  \x1b[90m${data.error || "No existing records to link — they'll link automatically on first use."}\x1b[0m\n`);
+    }
+  } catch {
+    console.log("  \x1b[90mCouldn't reach gateway — linking will happen on first use.\x1b[0m\n");
+  }
+} else {
+  console.log("  \x1b[90mNo API key found. Wallet will link on first use through the gateway.\x1b[0m\n");
+}
+
+// Step 4: Configure tools
+console.log("  Scanning for AI tools...\n");
+
+let configured = 0;
+
+for (const tool of tools) {
+  if (tool.detect()) {
+    const result = tool.configure(wallet);
+    if (result.success) {
+      console.log(`  \x1b[32m✓\x1b[0m ${tool.name.padEnd(20)} → ${result.message}`);
+      configured++;
+    } else {
+      console.log(`  \x1b[31m✗\x1b[0m ${tool.name.padEnd(20)} → ${result.message}`);
+    }
+  } else {
+    console.log(`  \x1b[90m-\x1b[0m \x1b[90m${tool.name.padEnd(20)} → not found\x1b[0m`);
+  }
+}
+
+console.log("");
+
+if (configured > 0) {
+  console.log(`  \x1b[32m${configured} tool(s) configured.\x1b[0m`);
+  console.log(`  See your usage at \x1b[4mhttps://token.nousai.cc\x1b[0m`);
+  console.log(`  Run \x1b[1msource ~/.zshrc\x1b[0m to apply changes in this terminal.`);
+} else {
+  console.log("  No AI tools found. Install Claude Code, Cursor, or any OpenAI-compatible tool.");
+}
+
+console.log("");

package/index.ts

@@ -0,0 +1,130 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+// nous-token plugin: routes LLM calls through the nous-token gateway
+// for real usage tracking on the global leaderboard.
+//
+// Supports 11 built-in providers + unlimited custom providers via config.
+// Any OpenAI-compatible API can be routed through the gateway.
+//
+// PRIVACY: API Key never leaves the machine in readable form.
+// Plugin computes SHA-256(apiKey) locally and sends only the hash
+// to the gateway via X-Nous-User header.
+
+const GATEWAY = "https://gateway.nousai.cc";
+
+// Built-in providers: prefix maps to gateway shortcut route
+const BUILTIN_PROVIDERS: Record<string, { prefix: string; api: string; envVars: string[] }> = {
+  openai:     { prefix: "openai",     api: "openai-completions",  envVars: ["OPENAI_API_KEY"] },
+  anthropic:  { prefix: "anthropic",  api: "anthropic-messages",  envVars: ["ANTHROPIC_API_KEY"] },
+  deepseek:   { prefix: "deepseek",   api: "openai-completions",  envVars: ["DEEPSEEK_API_KEY"] },
+  google:     { prefix: "gemini",     api: "openai-completions",  envVars: ["GEMINI_API_KEY", "GOOGLE_AI_API_KEY"] },
+  groq:       { prefix: "groq",       api: "openai-completions",  envVars: ["GROQ_API_KEY"] },
+  together:   { prefix: "together",   api: "openai-completions",  envVars: ["TOGETHER_API_KEY"] },
+  mistral:    { prefix: "mistral",    api: "openai-completions",  envVars: ["MISTRAL_API_KEY"] },
+  openrouter: { prefix: "openrouter", api: "openai-completions",  envVars: ["OPENROUTER_API_KEY"] },
+  fireworks:  { prefix: "fireworks",  api: "openai-completions",  envVars: ["FIREWORKS_API_KEY"] },
+  perplexity: { prefix: "perplexity", api: "openai-completions",  envVars: ["PERPLEXITY_API_KEY"] },
+  cohere:     { prefix: "cohere",     api: "openai-completions",  envVars: ["COHERE_API_KEY"] },
+};
+
+interface PluginConfig {
+  // Custom providers: { "myapi": { "upstream": "https://api.myapi.com", "envVar": "MYAPI_KEY" } }
+  customProviders?: Record<string, { upstream: string; envVar: string; api?: string }>;
+}
+
+export default function plugin(api: OpenClawPluginApi): void {
+  const cfg = (api.pluginConfig ?? {}) as PluginConfig;
+
+  // ── Register built-in providers ──
+  for (const [providerKey, { prefix, api: apiType, envVars }] of Object.entries(BUILTIN_PROVIDERS)) {
+    registerProvider(api, providerKey, {
+      baseUrl: `${GATEWAY}/${prefix}/v1`,
+      apiType,
+      envVars,
+    });
+  }
+
+  // ── Register custom providers from config ──
+  if (cfg.customProviders) {
+    for (const [name, { upstream, envVar, api: apiType }] of Object.entries(cfg.customProviders)) {
+      registerProvider(api, name, {
+        // Custom providers use X-Nous-Upstream header instead of shortcut prefix
+        baseUrl: `${GATEWAY}/v1`,
+        apiType: apiType || "openai-completions",
+        envVars: [envVar],
+        upstreamHeader: upstream,
+      });
+    }
+  }
+
+  const total = Object.keys(BUILTIN_PROVIDERS).length + Object.keys(cfg.customProviders || {}).length;
+  api.logger.info(`[nous-token] ready — ${total} providers, usage tracked via gateway`);
+}
+
+// ── Provider registration ──
+
+function registerProvider(
+  api: OpenClawPluginApi,
+  providerKey: string,
+  opts: { baseUrl: string; apiType: string; envVars: string[]; upstreamHeader?: string }
+): void {
+  const nousId = `nous-${providerKey}`;
+
+  api.registerProvider({
+    id: nousId,
+    label: `${providerKey} (nous-token)`,
+
+    auth: {
+      envVars: opts.envVars,
+      choices: [{
+        method: "api-key" as const,
+        choiceId: `${nousId}-key`,
+        choiceLabel: `${providerKey} API key`,
+        groupId: nousId,
+        groupLabel: `${providerKey} via nous-token`,
+      }],
+    },
+
+    catalog: { run: async () => null },
+
+    resolveDynamicModel: (ctx) => ({
+      id: ctx.modelId,
+      name: ctx.modelId,
+      provider: nousId,
+      api: opts.apiType,
+      baseUrl: opts.baseUrl,
+      reasoning: false,
+      input: ["text"] as const,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 32768,
+    }),
+
+    wrapStreamFn: (ctx) => {
+      if (!ctx.streamFn) return undefined;
+      const inner = ctx.streamFn;
+      return async (params) => {
+        let rawKey = params.headers?.["authorization"] || params.headers?.["x-api-key"] || "";
+        rawKey = rawKey.replace(/^Bearer\s+/i, "");
+        if (!rawKey) {
+          return inner(params);
+        }
+        const keyHash = await sha256(rawKey);
+        params.headers = {
+          ...params.headers,
+          "x-nous-user": keyHash,
+          ...(opts.upstreamHeader ? { "x-nous-upstream": opts.upstreamHeader } : {}),
+        };
+        return inner(params);
+      };
+    },
+  });
+}
+
+async function sha256(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash).slice(0, 16))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

package/openclaw.plugin.json

@@ -0,0 +1,44 @@
+{
+  "id": "nous-token",
+  "name": "nous-token",
+  "description": "Track your AI usage on the global leaderboard. Routes LLM calls through the nous-token gateway to record real token consumption. Supports 11 providers out of the box + unlimited custom providers. No prompt or response content is stored.",
+  "version": "0.2.0",
+  "kind": "provider",
+  "providers": [
+    "nous-openai", "nous-anthropic", "nous-deepseek", "nous-google",
+    "nous-groq", "nous-together", "nous-mistral", "nous-openrouter",
+    "nous-fireworks", "nous-perplexity", "nous-cohere"
+  ],
+  "providerAuthEnvVars": {
+    "nous-openai": ["OPENAI_API_KEY"],
+    "nous-anthropic": ["ANTHROPIC_API_KEY"],
+    "nous-deepseek": ["DEEPSEEK_API_KEY"],
+    "nous-google": ["GEMINI_API_KEY", "GOOGLE_AI_API_KEY"],
+    "nous-groq": ["GROQ_API_KEY"],
+    "nous-together": ["TOGETHER_API_KEY"],
+    "nous-mistral": ["MISTRAL_API_KEY"],
+    "nous-openrouter": ["OPENROUTER_API_KEY"],
+    "nous-fireworks": ["FIREWORKS_API_KEY"],
+    "nous-perplexity": ["PERPLEXITY_API_KEY"],
+    "nous-cohere": ["COHERE_API_KEY"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "customProviders": {
+        "type": "object",
+        "description": "Add custom providers. Key is provider name, value has upstream URL and env var for API key.",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "upstream": { "type": "string", "description": "Provider API base URL (e.g. https://api.myapi.com)" },
+            "envVar": { "type": "string", "description": "Environment variable name for the API key" },
+            "api": { "type": "string", "description": "API type (default: openai-completions)", "enum": ["openai-completions", "anthropic-messages"] }
+          },
+          "required": ["upstream", "envVar"]
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "nous-token",
+  "version": "0.1.0",
+  "description": "Open-source AI usage tracker. One command to track all your AI spending.",
+  "type": "module",
+  "main": "index.ts",
+  "bin": {
+    "nous-token": "./cli/setup.ts"
+  },
+  "files": [
+    "cli/",
+    "index.ts",
+    "sentinel.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "PROTOCOL.md"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "tsx": "^4"
+  },
+  "keywords": ["ai", "llm", "usage", "tracker", "openclaw", "openai", "anthropic", "leaderboard", "wallet", "crypto"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nousworld/nous-token"
+  }
+}

package/sentinel.ts

@@ -0,0 +1,256 @@
+#!/usr/bin/env npx tsx
+//
+// nous-token sentinel — independent Merkle tree verifier
+//
+// Pulls records from the gateway, recomputes leaf hashes, rebuilds the
+// Merkle Mountain Range locally, and compares the root with the gateway's.
+//
+// Usage:
+//   npx tsx sentinel.ts                          # one-shot verify
+//   npx tsx sentinel.ts --watch                  # verify every 5 minutes
+//   npx tsx sentinel.ts --gateway https://...    # verify a different gateway
+//
+// Anyone can run this. No API key needed. All data is public.
+
+const DEFAULT_GATEWAY = "https://gateway.nousai.cc";
+const POLL_INTERVAL_MS = 5 * 60 * 1000;
+
+interface Record {
+  id: number;
+  timestamp: string;
+  user_hash: string;
+  provider: string;
+  model: string;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens: number;
+  cache_write_tokens: number;
+  total_tokens: number;
+  leaf_hash: string;
+  receipt_sig?: string;
+}
+
+interface ChainState {
+  merkle_root: string;
+  leaf_count: number;
+  peak_count: number;
+}
+
+interface Peak {
+  height: number;
+  hash: string;
+}
+
+// ── Crypto ──
+
+async function sha256(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ── MMR ──
+
+function computeLeafHash(r: Record): Promise<string> {
+  // Model name is normalized at write time (provider/ prefix stripped)
+  // Use the stored model name as-is — it matches what was hashed at write time
+  return sha256([
+    r.timestamp,
+    r.user_hash,
+    r.provider,
+    r.model,
+    r.input_tokens,
+    r.output_tokens,
+    r.cache_read_tokens,
+    r.cache_write_tokens,
+    r.total_tokens,
+  ].join("|"));
+}
+
+async function appendToMMR(peaks: Peak[], leafHash: string): Promise<Peak[]> {
+  let current: Peak = { height: 0, hash: leafHash };
+
+  while (peaks.length > 0 && peaks[peaks.length - 1].height === current.height) {
+    const left = peaks.pop()!;
+    const mergedHash = await sha256(left.hash + "|" + current.hash);
+    current = { height: current.height + 1, hash: mergedHash };
+  }
+
+  peaks.push(current);
+  return peaks;
+}
+
+async function computeRoot(peaks: Peak[]): Promise<string> {
+  if (peaks.length === 0) return "empty";
+  if (peaks.length === 1) return peaks[0].hash;
+  return sha256(peaks.map((p) => p.hash).join("|"));
+}
+
+// ── HTTP ──
+
+async function fetchJSON<T>(url: string): Promise<T> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+  return res.json() as Promise<T>;
+}
+
+// ── Receipt Signature Verification ──
+
+async function getGatewayPubkey(gateway: string): Promise<CryptoKey | null> {
+  try {
+    const res = await fetchJSON<{ ok: boolean; algorithm: string; pubkey: JsonWebKey }>(
+      `${gateway}/api/pubkey`
+    );
+    if (!res.ok || !res.pubkey) return null;
+    return crypto.subtle.importKey(
+      "jwk",
+      res.pubkey,
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"]
+    );
+  } catch {
+    return null;
+  }
+}
+
+async function verifyReceiptSig(pubkey: CryptoKey, leafHash: string, sig: string): Promise<boolean> {
+  const sigBytes = new Uint8Array(sig.match(/.{2}/g)!.map((b) => parseInt(b, 16)));
+  return crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    pubkey,
+    sigBytes,
+    new TextEncoder().encode(leafHash)
+  );
+}
+
+// ── Verification ──
+
+async function verify(gateway: string): Promise<boolean> {
+  // 1. Get Merkle state from gateway
+  const chainRes = await fetchJSON<{ ok: boolean; data: ChainState }>(
+    `${gateway}/api/chain`
+  );
+  const state = chainRes.data;
+
+  if (state.leaf_count === 0) {
+    console.log("[sentinel] Tree is empty (no records yet). OK.");
+    return true;
+  }
+
+  console.log(`[sentinel] Gateway reports: ${state.leaf_count} records, ${state.peak_count} peaks`);
+  console.log(`[sentinel] Merkle root: ${state.merkle_root}`);
+
+  // 2. Fetch gateway public key for receipt signature verification
+  const pubkey = await getGatewayPubkey(gateway);
+  if (pubkey) {
+    console.log(`[sentinel] Gateway public key loaded — will verify receipt signatures`);
+  } else {
+    console.log(`[sentinel] No public key available — skipping receipt signature verification`);
+  }
+
+  // 3. Pull all records and rebuild MMR
+  let afterId = 0;
+  let verified = 0;
+  let sigVerified = 0;
+  let sigMissing = 0;
+  let peaks: Peak[] = [];
+
+  while (true) {
+    const recordsRes = await fetchJSON<{ ok: boolean; data: Record[]; has_more: boolean }>(
+      `${gateway}/api/records?after=${afterId}&limit=10000`
+    );
+
+    if (recordsRes.data.length === 0) break;
+
+    for (const r of recordsRes.data) {
+      // Recompute leaf hash from record fields
+      const computed = await computeLeafHash(r);
+      if (computed !== r.leaf_hash) {
+        console.error(`[sentinel] LEAF HASH MISMATCH at record #${r.id}`);
+        console.error(`  Computed: ${computed}`);
+        console.error(`  Stored:   ${r.leaf_hash}`);
+        return false;
+      }
+
+      // Verify receipt signature if available
+      if (pubkey && r.receipt_sig) {
+        const sigValid = await verifyReceiptSig(pubkey, r.leaf_hash, r.receipt_sig);
+        if (!sigValid) {
+          console.error(`[sentinel] RECEIPT SIGNATURE INVALID at record #${r.id}`);
+          return false;
+        }
+        sigVerified++;
+      } else if (!r.receipt_sig) {
+        sigMissing++;
+      }
+
+      // Append to local MMR
+      peaks = await appendToMMR(peaks, computed);
+
+      afterId = r.id;
+      verified++;
+    }
+
+    console.log(`[sentinel] Verified ${verified} leaf hashes...`);
+
+    if (!recordsRes.has_more) break;
+  }
+
+  // 3. Compare roots
+  if (verified !== state.leaf_count) {
+    console.error(`[sentinel] RECORD COUNT MISMATCH`);
+    console.error(`  Gateway claims: ${state.leaf_count}`);
+    console.error(`  Records found:  ${verified}`);
+    return false;
+  }
+
+  const computedRoot = await computeRoot(peaks);
+  if (computedRoot !== state.merkle_root) {
+    console.error(`[sentinel] MERKLE ROOT MISMATCH`);
+    console.error(`  Computed: ${computedRoot}`);
+    console.error(`  Gateway:  ${state.merkle_root}`);
+    return false;
+  }
+
+  console.log(`[sentinel] ALL ${verified} RECORDS VERIFIED. Merkle tree intact.`);
+  console.log(`[sentinel] Root: ${computedRoot}`);
+  console.log(`[sentinel] Peaks: ${peaks.length} (heights: ${peaks.map((p) => p.height).join(", ")})`);
+  if (sigVerified > 0) {
+    console.log(`[sentinel] Receipt signatures verified: ${sigVerified}/${verified}` +
+      (sigMissing > 0 ? ` (${sigMissing} unsigned — pre-receipt records)` : ""));
+  }
+  return true;
+}
+
+// ── Main ──
+
+const args = process.argv.slice(2);
+const watch = args.includes("--watch");
+const gatewayIdx = args.indexOf("--gateway");
+const gateway = (gatewayIdx >= 0 ? args[gatewayIdx + 1] : DEFAULT_GATEWAY).replace(/\/$/, "");
+
+console.log(`[sentinel] Gateway: ${gateway}`);
+console.log(`[sentinel] Mode: ${watch ? "watch (every 5m)" : "one-shot"}`);
+console.log("");
+
+async function run() {
+  try {
+    const ok = await verify(gateway);
+    if (!ok) {
+      console.error("\n[sentinel] TAMPERING DETECTED. Data integrity compromised.");
+      if (!watch) process.exit(1);
+    }
+  } catch (err) {
+    console.error(`[sentinel] Error: ${err}`);
+    if (!watch) process.exit(1);
+  }
+}
+
+await run();
+
+if (watch) {
+  setInterval(run, POLL_INTERVAL_MS);
+}