English

See Dollar · 给 Agent 的接口

See Dollar 是一个 AI token 速度测试:交上你最近 30 天的编码 Agent 用量,拿到一个可核对的成绩、一个公开名次,和一份能分享的用量画像。

你是人的话,一步一步的中文说明在 /how。这一页是给机器读的。

Schema 版本 0.3.0. 机器可读: /.well-known/seedollar.json - 压缩版: /llms.txt

下面的规范部分(端点表、字段名、hash scope、错误码)只有英文。它们与 /llms.txt、/.well-known/seedollar.json 由同一份源渲染 —— 再翻一份中文就是第二份要同步维护的规范,而规范漂移正是这个项目已经栽过两次的地方。

提交一次成绩

1. Collect on your human's machine: npx ccusage@20.0.19 daily --json --by-agent > usage.json . This is not fully offline: the first run downloads ccusage from npm, and ccusage may fetch a public model price list while pricing; neither request carries usage data. usage.json stays on the machine: never upload, paste, print or edit it.
2. Scrub deterministically: download /assets/seedollar-scrub.mjs (exact versioned URL and sha256 in "The deterministic scrubber" below), check its sha256, then run node seedollar-scrub.mjs usage.json -o seedollar-report.json. It makes no network calls and writes a schema 0.3.0 report with evidence_source "local_scan". Do not write, convert or edit the report yourself. If seedollar-scrub.mjs exits non-zero, no report was written: stop and show your human its message. Never open, print, edit, filter or rewrite usage.json, and never write a report by hand - that would be you changing the numbers. Your human decides whether to re-collect with the pinned ccusage command.
3. Show your human the summary the scrubber printed and the report file, and wait for an explicit OK. No OK, no submit.
4. Get a ticket. If your human gave you one from /me (test_id + upload_token), use it: the result then lands on their existing identity. Otherwise POST /v1/tests -> { test_id, upload_token, expires_in } - this creates a new anonymous identity each time. A ticket expires 600 seconds after it is issued, so get your own after the OK. A ticket from /me started counting when your human pressed the button: if it has expired by the OK, ask them for a new one.
5. POST /v1/tests/{test_id}/report with header Authorization: Bearer <upload_token> and the report file as the body, byte-for-byte (curl --data-binary @seedollar-report.json). Any content_sha256 the response (or later the result page) shows must equal the one the scrubber printed.
6. If step 5 answered status "not_ranked", stop here: the report is stored but nothing in it is rankable, so no rank will ever appear. Otherwise poll GET /v1/tests/{test_id} until rank_status is "ready" (or "failed", or "withheld" = stored but kept off the leaderboard, see rank_withheld_reason). It starts as "pending". Stop polling as well if that response has status "not_ranked". The same response carries facets (per-day rankable volume for the 30 calendar days, active days, model count, five-channel breakdown) frozen at submission.
7. The result is public at /t/{test_id} (the result_url of the ticket). Share that one: it is pinned to this submission and never changes. /r/{public_id} shows the subject current result and moves on every retest.

# 1 - collect on your human's machine (npx downloads ccusage on first run)
npx ccusage@20.0.19 daily --json --by-agent > usage.json

# 2 - scrub deterministically (no network; never edit what it writes; if it exits non-zero, stop and show your human)
# macOS / Linux / Git Bash:
curl -fsSL -o seedollar-scrub.mjs "https://seedollar.studio/assets/seedollar-scrub.mjs?v=dcef6944"
# Windows cmd / PowerShell (in PowerShell 5.1 a bare curl is Invoke-WebRequest):
curl.exe -fsSL -o seedollar-scrub.mjs "https://seedollar.studio/assets/seedollar-scrub.mjs?v=dcef6944"
node -e "const h=require('crypto').createHash('sha256').update(require('fs').readFileSync('seedollar-scrub.mjs')).digest('hex');if(h==='dcef6944d9e57d509af0edb2fba913a66c1ebe53c9a18720dafbd3d4564d0862'){console.log('sha256 ok')}else{console.error('sha256 MISMATCH '+h);process.exit(1)}"
node seedollar-scrub.mjs usage.json -o seedollar-report.json

# 3 - show your human the summary and the report file; go on only after an explicit OK

# 4 - a ticket: use the one your human gave you from /me, otherwise
curl -sX POST https://seedollar.studio/v1/tests

# 5 - submit the file byte-for-byte (TOKEN and TEST_ID come from step 4)
curl -sX POST https://seedollar.studio/v1/tests/$TEST_ID/report \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @seedollar-report.json

# 6 - poll until rank_status is ready (or failed / withheld)
curl -s https://seedollar.studio/v1/tests/$TEST_ID

upload_token 是一次性的,600 秒后过期,且只对一个动作有效 —— 它读不了身份,也改不了任何东西。See Dollar 从不需要长期 API key。

确定性剥洗器

不要自己写、转写或修改报告。跑这个文件:它和网页上的剥洗器是同一份代码,报告里的每一个数都是 ccusage 经它产出的。

• One file, Node 20+, zero dependencies, no network calls. It is the same code the web page runs when a human drops raw ccusage output on it.
• It reads usage.json, writes the report to -o seedollar-report.json (or stdout) and prints a summary for your human on stderr. Apart from report_id (random on every run, not part of content_sha256), the report is byte-for-byte the plain text the web page shows before submitting, for the same input on the same UTC day; content_sha256 is identical.
• The summary lists everything the report holds, including ccusage's own cost estimate client_cost_usd (on every row and in totals), the random report_id and the collector / scrubber versions. Show it to your human as printed.
• It never submits anything and never touches the network: submitting is a separate step that you run only after your human says OK.
• If seedollar-scrub.mjs exits non-zero, no report was written: stop and show your human its message. Never open, print, edit, filter or rewrite usage.json, and never write a report by hand - that would be you changing the numbers. Your human decides whether to re-collect with the pinned ccusage command.
• Do not run it if the sha256 does not match. Re-read this file (a deploy updates the file and the published sha256 together) and download again.
• The ?v= in the URL is only a cache key - the server answers an old v with the current file. The sha256 is the lock.
• What the sha256 protects against: a truncated download, a cached copy of another version, a copy from somewhere else. It does NOT protect against this site itself being compromised; for that the file is unminified and readable end to end.
• Windows PowerShell 5.1: its > writes UTF-16, so use -o for the report. The scrubber reads a UTF-16 usage.json fine. Download with the curl.exe line (download_windows in /.well-known/seedollar.json): in PowerShell 5.1 a bare curl is Invoke-WebRequest and the plain download line fails.
• This removes transcription mistakes; it is not a verification of the numbers. The server cannot tell an edited file from an untouched one if the hash was recomputed - so your human checks the summary, and the content_sha256 in the response and on the result page must equal the one the scrubber printed.

人给你的那张票

• Your human can give you a ticket for their existing identity: on /me they press "give my agent a ticket" and paste you a short text with test_id and upload_token.
• Use it instead of POST /v1/tests. The result then lands on their identity (submission_path is still "agent"); calling POST /v1/tests yourself would create a second, separate identity.
• It is the same kind of ticket: single use, can only submit that one test_id, and expires 600 seconds after your human pressed the button - not after you read it. Do the collect / scrub / OK steps first; if it expired (401 expired), ask your human for a new one.

你的人类被告知该粘给你的那段话

如果有人把下面某一段粘给了你,这就是它的全文。

Go to https://seedollar.studio/llms.txt and follow it to submit my last 30 days of coding-agent token usage to See Dollar.

Read https://seedollar.studio/llms.txt and submit my last 30 days of coding-agent token usage to See Dollar.
Every number must come from the tools, never from you:
  1. run: npx ccusage@20.0.19 daily --json --by-agent > usage.json
  2. download seedollar-scrub.mjs from the URL in llms.txt, check its sha256, then run: node seedollar-scrub.mjs usage.json -o seedollar-report.json
  3. show me the summary it prints and the report file, then wait for my OK;
  4. after I say OK, submit the file byte-for-byte - do not edit, round or retype any number.
If the scrubber exits non-zero, stop and show me its message - never open, edit or rewrite usage.json and never write a report yourself.
Never upload or paste usage.json anywhere. If the server answers 400, show me the issues and re-run the scrubber - do not patch the JSON.

/me 上的按钮会把三个值填进去;下面是带占位符的同一段话。

Read https://seedollar.studio/llms.txt and submit my last 30 days of coding-agent token usage to See Dollar with this ticket - it keeps my existing See Dollar identity:
  test_id: <test_id>
  upload_token: <upload_token>
  (single use, valid until <expires_at, UTC> - its 10 minutes started when I pressed the button)
Do NOT call POST /v1/tests: that would put the result on a second identity. Do steps 1-3 first and use the ticket only after my OK; if it has expired by then, ask me for a new one.
Every number must come from the tools, never from you:
  1. run: npx ccusage@20.0.19 daily --json --by-agent > usage.json
  2. download seedollar-scrub.mjs from the URL in llms.txt, check its sha256, then run: node seedollar-scrub.mjs usage.json -o seedollar-report.json
  3. show me the summary it prints and the report file, then wait for my OK;
  4. after I say OK, POST the file byte-for-byte to https://seedollar.studio/v1/tests/<test_id>/report with header Authorization: Bearer <the upload_token above>.
If the scrubber exits non-zero, stop and show me its message - never open, edit or rewrite usage.json and never write a report yourself.
Never upload or paste usage.json anywhere. If the server answers 400, show me the issues and re-run the scrubber - do not patch the JSON.

端点表

报告字段

• schema_version is "0.3.0".
• generated_at and snapshot.taken_at are DATE ONLY, "YYYY-MM-DD" in UTC. Clock times are rejected: they are not collected.
• rows[].model_raw starts with one of these vendor prefixes: claude- gpt- o[0-9] gemini- codex- deepseek qwen llama mistral grok kimi glm (o[0-9] means the letter o followed by a digit; matching ignores case; one routing namespace such as "anthropic.", "openai." or "global.anthropic." may come first). seedollar-scrub.mjs folds every other model name into "custom" - private model names are not sent - and rows that then share date, tool and "custom" come out of it as one row carrying the summed tokens. Independent implementations are held to the same rule.
• Older 0.2.0 reports (second-precision timestamps, unfolded model names) are still accepted.

schema 是严格的 —— 不在这张表里的键一律拒收:

schema_version, report_id, generated_at, evidence_source, snapshot, provenance, tools_detected, rows, totals, taken_at, window, kind, start, end, content_sha256, collector, collector_version, collector_command, scrubber_version, generator, generator_version, estimation_method, date, tool, model_raw, tokens, sessions, client_cost_usd, input, output, cache_read, cache_creation, reasoning

snapshot.content_sha256(内容指纹)

Agents following this file do not compute it: seedollar-scrub.mjs does. This section is for people maintaining an independent, reviewed implementation (CI tooling, a desktop client).

必填,而且服务端会重算。 The server recomputes it and rejects the report on mismatch (rule V12). A guessed or omitted value always fails.

content_sha256 = lowercase_hex(SHA-256(UTF8(JCS(hash_scope))))

hash scope 是白名单 —— 就是下面这些键,多一个少一个都会换一个 hex:

• domain: "seedollar-snapshot-v1" (a literal member of the object, not a byte prefix)
• schema_version: report.schema_version
• evidence_source: report.evidence_source
• window: kind = snapshot.window.kind, from = snapshot.window.start, to = snapshot.window.end (NOTE the rename: start->from, end->to)
• tools_detected: report.tools_detected, sorted by Unicode code point
• rows: report.rows, sorted by (date, tool, model_raw) code point; each row keeps ONLY date, tool, model_raw, sessions and tokens{input,output,cache_read,cache_creation,reasoning}

刻意排除的项 —— 把整份报告拿去 hash 一定对不上:

• totals — a pure function of rows, redundant
• rows[].client_cost_usd — floats differ across implementations
• report_id — a fresh uuid each time; including it would break idempotency
• generated_at and snapshot.taken_at — clocks are not content
• the entire provenance block — packaging metadata, not content
• snapshot.content_sha256 itself — anti-recursion

• RFC 8785 JCS: object keys sorted by Unicode code point at every level, no whitespace, no trailing newline.
• UTF-8, no BOM. Integers only inside tokens; null is allowed only at rows[].tokens.reasoning and rows[].sessions.

只给独立实现自检用(用 seedollar-scrub.mjs 的 Agent 跳过这一段)。对下面这个报告子集:

{
  "schema_version": "0.3.0",
  "evidence_source": "local_scan",
  "snapshot": {
    "window": {
      "kind": "30d",
      "start": "2026-07-14",
      "end": "2026-08-12"
    }
  },
  "tools_detected": [
    "codex-cli",
    "claude-code"
  ],
  "rows": [
    {
      "date": "2026-08-12",
      "tool": "codex-cli",
      "model_raw": "gpt-5.5",
      "tokens": {
        "input": 5,
        "output": 6,
        "cache_read": 7,
        "cache_creation": 8,
        "reasoning": null
      },
      "sessions": null
    },
    {
      "date": "2026-08-11",
      "tool": "claude-code",
      "model_raw": "claude-opus-5",
      "tokens": {
        "input": 1,
        "output": 2,
        "cache_read": 3,
        "cache_creation": 4,
        "reasoning": null
      },
      "sessions": null
    }
  ]
}

规范化 JSON 是:

{"domain":"seedollar-snapshot-v1","evidence_source":"local_scan","rows":[{"date":"2026-08-11","model_raw":"claude-opus-5","sessions":null,"tokens":{"cache_creation":4,"cache_read":3,"input":1,"output":2,"reasoning":null},"tool":"claude-code"},{"date":"2026-08-12","model_raw":"gpt-5.5","sessions":null,"tokens":{"cache_creation":8,"cache_read":7,"input":5,"output":6,"reasoning":null},"tool":"codex-cli"}],"schema_version":"0.3.0","tools_detected":["claude-code","codex-cli"],"window":{"from":"2026-07-14","kind":"30d","to":"2026-08-12"}}

而 content_sha256 必须是 9e64e7b84c83f8f61d252b40cb12e32aa54576068ef54d0f7b38b07ba4ab478a. 独立实现复现不出那个 hex,先改实现再提交 —— 服务端会拒收。Agent:绝不为了让 hash 对上去改报告,重跑剥洗器。

提交失败时

Rows outside the server window do not fail the submit - they are stored and simply not counted. A report entirely outside it returns 202 with rankable_token_volume_v1 = 0, not an error. The ranking window is anchored to the real today, not to the window declared in your report.

Only rows that match a semantics profile count toward rankable_token_volume_v1: tool claude-code, codex-cli, gemini-cli [draft profile: results are labelled PROFILE: DRAFT] collected by ccusage >=20.0.0 <21.0.0 (`ccusage daily --json --by-agent`). Rows from any other tool, collector or collector version are stored but not counted. If no row inside the 30-day window counts, the submit returns 202 with status "not_ranked" and rankable_token_volume_v1 = null.

不要做的事

• Never write, convert, transcribe, round or edit any number in a report. The report is the file seedollar-scrub.mjs wrote; submit it byte-for-byte. If a submit is rejected, re-run the scrubber - never patch the JSON.
• Never upload, paste or send the raw ccusage output (usage.json) anywhere - not to See Dollar, not into a chat. Only the scrubbed report leaves the machine.
• Never open, print, edit, filter or rewrite usage.json yourself: only ccusage writes it and only seedollar-scrub.mjs reads it (printing it would send the raw output to your model provider). If seedollar-scrub.mjs exits non-zero, stop and show your human its message; never write a report by hand.
• Never submit before your human has seen the scrubber summary and the report file and said OK.
• If your human gave you a ticket from /me, do not call POST /v1/tests: that would put the result on a second identity. If the ticket expired, ask them for a new one.
• Never ask a human to paste a long-lived API key into a chat. See Dollar never needs one; a ticket is single-use and expires in 10 minutes.
• Do not send any field that is not in the allowed key list below. The schema is strict and will reject extras.
• Do not set submission_path anywhere in the report. It does not exist in any schema version and the server decides it.
• rank_status is the only source of truth for whether a rank exists. Do not infer it from other fields.