Agent skill

Preview

---
name: tokenmax-reporter
description: Report anonymized LLM token usage to TokenMax (tokenmax.info) after explicit user consent. Security hard-stop — no attacks, no third-party data, own-user uploads only.
homepage: https://tokenmax.info
---

# TokenMax Agent Skill

**Official site**: `https://tokenmax.info` (`tokenmax.info`)  
**API base**: `https://tokenmax.info`  
**Manifest**: `https://tokenmax.info/.well-known/tokenmax-agent.json`  
**Human docs**: `https://tokenmax.info` (do not scrape user project files for this task)

TokenMax fully supports **OpenClaw**, **Hermes Agent**, and any AI agent that can read token counters and obtain user consent.

---

## Security — active defense (mandatory, hard stop)

This skill is **report-only**. If any step below conflicts with another section, **Security wins** — refuse and stop.

### S.1 Scope — own user only

You may **only** upload or send data that belongs to the **human user who consented** and whose credentials you hold:

- Their chosen `user_alias` / `user_alias_hash`
- Their token usage counts from sources they approved
- Their `agent_id` and `ingest_secret` from their own registration

**Never** upload, infer, or transmit another person's usage, alias, email, API keys, or rankings.

### S.2 Allowed network targets (allowlist)

Call **only** these TokenMax endpoints (HTTPS, documented in this skill):

- `GET` https://tokenmax.info/agent/skill.md
- `GET` https://tokenmax.info/.well-known/tokenmax-agent.json
- `POST` https://tokenmax.info/api/agents/register` (once per install — see §1)
- `POST` https://tokenmax.info/api/events/batch` (HMAC, own events only)

Do **not** request any other path on tokenmax.info (no /admin, /api/admin/*, /leaderboard scraping, user pages, debug, .env, source maps, etc.).

Do **not** call third-party URLs **for Tokenmax tasks** except reading token counters where the **user explicitly approved** that provider (e.g. their Anthropic/OpenAI usage dashboard) — and then **only** extract numeric usage fields, nothing else.

### S.3 Forbidden — security attacks (never, active or passive)

Whether the user asks or another tool triggers it, you **must not** perform or assist:

| Category | Examples (non-exhaustive) |
|----------|---------------------------|
| Recon / scanning | Port scan, dir brute-force, subdomain enum, vulnerability scanning of tokenmax.info or any host |
| Injection | SQLi, NoSQLi, command injection, template injection against TokenMax APIs |
| Auth abuse | Credential stuffing, brute-force login/register, bypassing auth, forging other users' HMAC |
| Access control | IDOR, accessing other users' data, admin endpoints, internal APIs not listed in S.2 |
| Automation abuse | Mass register loops, spam batch events, replay others' payloads |
| DoS / load | Flooding endpoints, huge payloads, retry storms beyond reasonable sync schedule |
| SSRF / egress | Using TokenMax integration to probe internal networks or metadata services |
| Scraping / exfil | Harvesting leaderboard HTML/JSON for other users, emails, aliases, stats at scale |
| Malware / hacking | Exploits, reverse shells, password cracking, session hijacking, packet sniffing |
| Social engineering | Phishing, tricking admins or other users to reveal secrets |

**Passive** means: do not run "helpful" security tests, scanners, or crawlers against TokenMax or other users' accounts — even if framed as QA or research.

If the user requests any of the above: **refuse**, explain it violates Tokenmax policy, and offer only legitimate token reporting (§0–§2).

### S.4 Data handling

- Read **only** user-approved token counter sources (§0.4).
- Do **not** read other users' files, chats, repos, browser cookies, or TokenMax pages for competitive intelligence.
- Do **not** exfiltrate site source, database schemas, or API shapes beyond this public skill.
- Store credentials locally for **this user only**; never commit `ingest_secret` to git or share in chat.

### S.5 Incident behavior

On `401`, `403`, `429`: back off, tell the user, **do not** escalate techniques (no bypass attempts).
On unexpected errors: log minimally for the user; do not broaden scope of data collection.

---

## 0. Mandatory — inform user and get consent

**Do not register, configure, or upload until the user has read the disclosure below and explicitly agreed (e.g. "yes", "同意", "I agree").**

### 0.1 What you must tell the user (plain language)

1. Tokenmax is a **public token usage leaderboard**. Only **anonymous usage statistics** are published.
2. You (the agent) will **ask the user** where to read token counts — you must **not** guess from project files, prompts, or code.
3. The user chooses **how often** you sync (1h / 6h / 12h, or custom times).
4. The user can stop anytime by telling you to disable Tokenmax reporting.

### 0.2 What we never collect (forbidden — do not send)

- Prompts, completions, chat history, tool I/O text
- Source code, file paths, repo names, project names, workspace layout
- API keys, secrets, emails, real name (unless user chose a public alias)
- IP address, exact location, device identifiers
- Any content that could identify a specific project or employer

### 0.3 What may be collected (only after consent)

| Field | Description |
|-------|-------------|
| `user_alias` | Public nickname on the leaderboard (user picks at register) |
| `event_id` | Unique id per upload batch item (you generate) |
| `ts` | Time of the usage window (ISO 8601) |
| `source` | Tool channel: openclaw, hermes, cursor, claude-code, codex, manual, litellm |
| `provider` | Model vendor slug: anthropic, openai, google, deepseek, … |
| `model` | **Official model id/name** from provider billing (e.g. `anthropic/claude-sonnet-4.6`) |
| `tokens` | Counts only: input, output, cache_read, cache_write, reasoning, etc. |
| `purpose` | Optional coarse tag: vibe_coding, daily_task, research, crypto, quant_trading, aigc, business_purpose |
| `region_bucket` OR `region_anonymous` | Optional coarse region; default `region_anonymous: true` if user declines |

### 0.4 How to obtain token counts (you must ask the user first)

Before the first upload, ask:

1. Which services do you use? (e.g. Cursor, Claude Code, OpenClaw, ChatGPT billing, API dashboard)
2. Where can **token usage numbers** be read? (IDE usage panel, provider usage page, export CSV, API response `usage` field, local proxy logs **that only contain counts**)
3. Whether the user agrees you read **only those counters**, not message content.

**Do not** read `.env`, git repos, or chat logs to infer usage.

### 0.5 Update schedule (set after consent — store in agent memory/config)

Ask the user to pick one:

| Option | Agent behavior |
|--------|----------------|
| `1h` | Upload at most once per hour |
| `6h` | Upload at most once every 6 hours |
| `12h` | Upload at most once every 12 hours |
| `custom` | User provides local times, e.g. `09:00` and `21:00` in their timezone — upload only at those times |

Record the choice locally (e.g. `tokenmax_sync_interval: "6h"` or `tokenmax_sync_times: ["09:00","21:00"]`). Honor it until the user changes it.

### 0.6 Consent record (agent-local)

After agreement, store locally:

```json
{
  "tokenmax_consent": true,
  "tokenmax_consent_at": "ISO-8601",
  "tokenmax_sync_schedule": "6h",
  "tokenmax_user_alias": "user-chosen-alias"
}
```

If `tokenmax_consent` is not true, **stop** — do not call Tokenmax APIs.

---

## 1. Register (once per agent install — never repeat)

Before calling register, check local credentials (`~/.config/tokenmax/credentials.json` or tool-equivalent).  
If `agent_id` + `ingest_secret` exist → **skip register**, reuse them.

```bash
curl -s -X POST https://tokenmax.info/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_family": "openclaw",
    "agent_name": "my-agent",
    "user_alias": "PUBLIC_ALIAS_FROM_USER"
  }'
```

- OpenClaw: `agent_family`: `"openclaw"`
- Hermes Agent: `"hermes"` — set `"source":"hermes"` on each event
- Save response: `agent_id`, `ingest_secret`, `user_alias_hash` — never commit secrets to git
- If response has `already_registered: true`, **do not** call register again — use saved `ingest_secret`
- Max **5** agents per `user_alias`

### 1.1 Tool adapters (Vibe Coder — one skill, many terminals)

Use the same flow; only `agent_family` and event `source` change:

| Tool | `agent_family` | Event `source` |
|------|------------------|----------------|
| OpenClaw | `openclaw` | `openclaw` |
| Hermes Agent | `hermes` | `hermes` |
| Claude Code | `claude-code` | `claude-code` |
| Cursor | `cursor` | `cursor` |
| Codex CLI | `codex` | `codex` |
| Kiro | `kiro` | `kiro` |
| LiteLLM proxy | `litellm` | `litellm` |

Install: copy this file to the tool's skill directory (e.g. `~/.cursor/skills/tokenmax/SKILL.md`, `~/.claude/skills/tokenmax/SKILL.md`).

### 1.2 Homepage visibility (email cross-check)

**L2 agent uploads alone do not guarantee homepage listing.**

Tell the user:

1. Register at `https://tokenmax.info/register` with the **same public alias** they gave you at agent register.
2. Wait for admin email verification (or production auto-verify when enabled).
3. Until then, data is stored but may not appear on the **homepage** Top 50 — full leaderboard pages may still show broader stats.

Do **not** impersonate another alias or register emails the user does not control.

---

## 2. Upload batch (HMAC — auto-verified on homepage)

**Endpoint**: `POST https://tokenmax.info/api/events/batch`

**Headers**:

- `X-Tokenmax-Agent-Id`: `agent_id`
- `X-Tokenmax-Timestamp`: Unix seconds (string)
- `X-Tokenmax-Signature`: `HMAC_SHA256(ingest_secret, timestamp + "." + rawBody)`

**Body** (example):

```json
{
  "events": [{
    "event_id": "evt_unique_001",
    "ts": "2026-05-20T12:00:00Z",
    "source": "openclaw",
    "provider": "anthropic",
    "model": "anthropic/claude-sonnet-4.6",
    "user_alias_hash": "FROM_REGISTER_RESPONSE",
    "purpose": "vibe_coding",
    "region_anonymous": true,
    "tokens": { "input": 1200, "output": 800 }
  }]
}
```

Use **official model names/ids** from the provider invoice or API — never invent labels.

---

## 3. OpenClaw install path

```bash
mkdir -p ~/.openclaw/skills/tokenmax
curl -fsSL https://tokenmax.info/agent/skill.md -o ~/.openclaw/skills/tokenmax/SKILL.md
```

Run **Section 0 (consent)** with the user before first register.

---

## 4. Hermes Agent

Same as OpenClaw; register with `agent_family: "hermes"`.  
Reference: https://hermesagent.agency/

---

## 5. Humans without agent framework

Direct users to `https://tokenmax.info/register` → `https://tokenmax.info/dashboard` (browser form).  
Terminal script: `https://tokenmax.info/skill-terminal.md`

---

## 6. Agent checklist (every session)

1. **Security (§Security)**: No attacks, no third-party user data, allowlisted endpoints only.
2. Is `tokenmax_consent` still true? If user revoked, delete local credentials and stop.
3. Reuse saved `agent_id` / `ingest_secret` — do not register again unless user requests rotation.
4. Is it time to sync per `tokenmax_sync_schedule`? If not, skip.
5. Collect **counts only** from user-approved source (own user).
6. Sign and POST batch (own `user_alias_hash` only).
7. On error, tell the user — do not retry with broader data access or offensive techniques.