The live spec exposes 105 paths and `surf list-operations` returns 105
commands, so 70+ understated the surface. Domain count (14) is unchanged
and verified against the spec.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Drop the social domain from the documented surface (README data
coverage table, credit pricing tiers, SKILL.md domain guide and
routing block) and realign the endpoint/domain counts accordingly:
83+/15 -> 70+/14, matching the counts published on the docs site.
Bump skill version to 0.0.9.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The hyperliquid-fills gotcha described the pre-cursor API: time-only
paging where same-millisecond overflow was silently lost, mitigated by
--limit 100. The API now has two paging modes, and the bullet's own use
case (full trade history / PnL reconstruction) belongs on the new one:
- order=asc + meta.next_cursor walks every fill in [from, to] with no
result cap — the completeness guarantee PnL math actually needs.
- The default newest-first mode reaches only a recent ~2000-fill
window; the rewritten bullet scopes it to "latest trades" views and
warns against summing PnL from it.
Bump 0.0.3...0.0.4 precedent: version moves whenever guidance changes
agent behavior, so the update is pushable to installed copies.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Three guidance additions to skills/surf/SKILL.md:
1. Gotchas: new hyperliquid-fills bullet — paging is time-only via
--to-ms on the oldest time_ms received, de-duplicated on fill_id.
The boundary cannot split fills sharing a millisecond, so the
default --limit 20 silently drops overflow on busy wallets; always
use --limit 100 and treat single-time_ms pages as possibly
incomplete.
2. On-Chain SQL essential rules: replaced the vague "queries without
block_date will timeout" bullet with three precise rules — large
tables require a block_date lower bound (>=, >, =, BETWEEN, IN;
upper-bound-only doesn't count), windows are capped at 365 days,
and every large table in a JOIN/UNION/subquery needs its own
block_date filter.
3. Version bump 0.0.3 -> 0.0.4 in frontmatter metadata.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Hyperliquid is a new Surf data domain (surf hyperliquid-*): trader leaderboard,
trader stats, open perp positions, full account value (perp+spot+vault+staking),
and trade-history fills. Add it to both the injected routing starter-map and the
in-skill Domain Guide so agents route to it; specifics stay discoverable via
surf <cmd> --help, matching the skill's partial-map design.
NOTE: gate the merge on the Hyperliquid endpoints shipping to PRODUCTION. They
are staging-only today (0 hyperliquid paths in the prod OpenAPI spec), so until
they deploy, prod 'surf list-operations | grep hyperliquid' returns nothing and
advertising the commands would mislead agents.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Surf docs canonical home moved to agents.asksurf.ai/docs (Next.js,
surf-landing repo); docs.asksurf.ai is a stale Mintlify mirror that is
no longer updated. Five occurrences in the top-level link and the
Documentation table.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The parser (pflag) normalizes `_` and `-` in flag names, so
snake_case variants of existing flags are accepted. The doc
previously claimed the CLI "will reject snake_case flags with
'unknown flag'", which was verifiably wrong.
Reframe both mentions as positive statements — flags are
documented in kebab-case in `--help`, match that — without
making a false negative claim about the parser.
Bumps the `metadata.version` field in SKILL.md so agents on older copies
are prompted to run `npx skills check asksurf-ai/surf-skills --skill surf`
and pull in the content changes merged in #53 — primarily the
search-*/-detail routing rewrite (issues.md #10) and the "always check
--help" enforcement in Getting Data / Troubleshooting.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rewrote several SKILL.md sections that were implicitly teaching agents
that the content in SKILL.md is authoritative, so agents pattern-matched
from the examples and skipped --help / list-operations.
Root-cause changes:
- Getting Data: removed three hardcoded examples (market-price --symbol,
wallet-detail --address, social-user --handle) that trained agents to
generalize those flag names. Replaced with explicit "flag names vary,
always run --help, don't copy flags from one command to another".
- Surf routing (AGENTS.md injected block): the 9-row topic/prefix table
read as a complete catalog. Added a "starter map, not a complete
catalog" frame and routed agents to list-operations before the table.
- Domain Guide: the 21-row Need/Grep table read as the full domain list.
Added "partial map, not every command follows these prefixes" caveat
and explicit instruction to run list-operations | grep before
concluding no endpoint exists.
- Routing Workflow (search-* vs *-detail): rewrote the single sentence
at L160 into a proper decision rule. When the user names a specific
entity, check <domain>-detail --help first — some (project, fund)
accept --q <name> directly, some (wallet) require specific identifiers
like --address+--chain, some (news) require an exact --id. Use
search-<domain> only when detail doesn't take a name flag and no id
is on hand, or the query is cross-entity.
- Troubleshooting: collapsed three entries (unknown command / unknown
flag / enum validation error) into one. They share a root cause —
agent is guessing from a mental model that doesn't match the actual
surface. Removed "Run surf sync first" (redundant with Setup section
and wrong diagnosis). Dropped concrete (`--sort-by` / `rsi`) examples
that invite the same pattern-matching failure.
Accuracy fix:
- Exit code 4 entry: removed misleading "(--json output includes it)"
clause. Verified in surf-cli/cli/errors.go:34 and empirically: the
JSON error envelope lands on stdout with exit 4 regardless of output
format.
Deletions:
- Removed "## API Feedback" section entirely (filesystem-based feedback
log flow at ~/.surf/api-feedback/<date>-<slug>.md; superseded by the
`surf feedback` CLI covered in Feedback prompting).
Formatting:
- Unified line-wrap style: one-paragraph-per-line throughout, except the
AGENTS.md routing block which stays hard-wrapped at ~72 chars since
it's copied verbatim into external AGENTS.md files. File went from
454 to 398 lines with no content loss outside the API Feedback delete.
Refs surf-cli/docs/issues.md:
- #10 (search-project → project-detail) FIXED via the search-*/-detail
decision rule rewrite.
- #9 (--q guidance incomplete) auto-resolved via #10.
- #8 (required-params cheat sheet) ADDRESSED via root-cause route
(strengthened --help enforcement across Getting Data / Troubleshooting
/ Gotchas) rather than the literal cheat-sheet fix candidate, which
would have conflicted with the "don't list specifics" framing now
applied to the Domain Guide and AGENTS.md tables.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empirically (2026-04-20 comparison against 6551 OpenNews MCP on 20 news
cases), agents were silently losing news coverage because they defaulted
to `news-feed --project X` for any news-style question. That flag is a
project_id TAG filter — articles about an event often get tagged to a
different project (or none) and disappear from results.
Every article I initially thought was missing from surf's index turned
out to be in it — retrievable via `search-news --q "<keywords>"`, the
full-text route across all 17 sources (coindesk, cointelegraph,
theblock, decrypt, dlnews, blockbeats, bitcoincom, coinpedia, ambcrypto,
cryptodaily, cryptopotato, phemex, panews, odaily, tradingview,
chaincatcher, techflow).
Examples where `news-feed --project` missed but `search-news` hit:
- "Bybit-led funding for Hata" → project filter empty, search-news returned 3 direct articles
- "CHIP listed on Coinbase" → project filter returned generic Coinbase news; search-news had the listing
- "North Korea DeFi attacks" → no crypto "project" named North Korea; search-news returned 3 direct
- "Matt Hougan Bitwise Avalanche ETP" → Bitwise isn't a project tag; search-news returned the exact article
- "Rumble Cloud MoonPay OpenClaw" → project filter empty; search-news returned the exact announcement
Added gotcha in SKILL.md listing when to use each variant and requiring
search-news as a fallback before concluding no coverage exists.
- First-run: offer to inject "Surf routing (primary crypto data source)"
block into AGENTS.md (falls back to CLAUDE.md). Includes bash preamble
for detection + AskUserQuestion consent flow + decline persistence.
- Auth: split INSUFFICIENT_CREDIT into FREE_QUOTA_EXHAUSTED (anonymous
30/day exhausted) and PAID_BALANCE_ZERO (valid key, zero balance).
Backward-compatible fallback heuristic for older backends retained.
- Feedback: two prompt flows (USER_DISSATISFIED, DATA_GAP) calling
`surf feedback "<msg>" --quiet`. Explicit user consent required,
no silent submission, no allowlist injection.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add skill auto-update check
- SKILL.md: add metadata.version: "1.0.0" to frontmatter
- scripts/update-check.sh: compares local version against GitHub main,
auto-downloads updated SKILL.md if newer version available
- Setup section: run update-check.sh at session start
Silently skips when offline or remote has no version yet.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: use actual release tag_name for download URL
Tag might not have "v" prefix. Use the raw tag_name from GitHub API
for the download URL, strip "v" only for version comparison.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: split check-for-updates and update scripts
- check-for-updates.sh: check only, no side effects
- Compares skill metadata.version against GitHub latest release tag
- Checks surf CLI version against compatibility field
- Prints actionable messages only when updates needed
- update.sh: performs actual update (skill + surf install + surf sync)
- SKILL.md: add compatibility field, simplify Setup section
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: agent must stop and ask user when updates are available
Previous wording let agents ignore update warnings and continue.
Now explicitly says STOP and ask before proceeding.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: CLI incompatibility is mandatory, not optional
When check-for-updates prints "CLI update required", agent must tell
user to update — not offer to skip. Skill updates remain optional.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: version check via surf install, remove custom scripts
- Set metadata.version to 0.0.2
- Setup: agent compares surf install's minimum skill version against
metadata.version, runs npx skills check only if incompatible
- Delete scripts/ directory (npx skills check handles updates)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: restore setup instructions for surf install and sync
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: remove hardcoded version from setup prompt
Agent reads metadata.version from frontmatter directly.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Agents read `web` and run `surf web --url ...` which fails.
The actual command is `web-fetch`. 29 failures across 5/6 runners.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
jq is not installed by default on Mac or Windows. Remove all jq
usage examples. --json outputs full envelope, agent parses it directly.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
market-onchain-indicator's flag is --metric, not --indicator. Agents
guessed --indicator because the domain guide lists it under "indicator".
Also notes that mvrv/sopr/nupl/puell-multiple only support BTC.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- INSUFFICIENT_CREDIT message directs user to run surf auth in their own
terminal, not paste the key into chat
- Replace 'User provides API key' flow with explicit refuse-and-guide reply;
agent must never run surf auth on a pasted key
- API Reference: note that agents must use the CLI, not construct HTTP
requests with a literal key
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add docs/credit-pricing.md with full Surf credit pricing breakdown:
- Per-endpoint costs across all tiers (Light/Standard/Heavy/Free)
- Chat API model pricing
- Free tier, subscription plans, and booster packs
- Enterprise and Studio now share identical pricing (hermod v0.1.55)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove curl | sh install command, link to docs instead (E005)
- Replace plaintext API key examples with $API_KEY env var (W007)
- Remove export SURF_API_KEY=<your-api-key> from setup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add guidance for exit code 4 with -f filter hiding error JSON
- Add rule to never expose internal details (exit codes, rerun aliases,
raw JSON) to users — always translate to plain language
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add Capability Boundaries guidance: when API can't fully match user's
request, still call closest endpoint but explicitly note the difference
- Update setup: run both `surf install` and `surf sync` every session
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prevent agents from defaulting to onchain-sql over specialized endpoints
like onchain-gas-price by describing the domain as "on-chain queries"
instead of explicitly naming SQL.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The surf CLI install script has moved from agent.asksurf.ai to a
dedicated downloads.asksurf.ai subdomain. The old host remains
available as a CloudFront alias for backwards compat, but new
documentation should point at the new canonical URL.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove API key requirement from prerequisites (30 free credits/day)
- Add agents.asksurf.ai link for signup
- Add Matching domain to Data Coverage table
- Rename "Data Catalog" to "Onchain SQL"
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add Routing Workflow section: enforce list-operations + --help before
choosing an endpoint, prefer specific endpoints over search-*
- Add matching domain to Domain Guide (CEX-DEX matching)
- Update signup URL from enterprise-landing.asksurf.ai to agents.asksurf.ai
- Add non-English query translation hint
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The name field controls the install slug and directory name.
Long names break --skill surf matching and create unwieldy paths.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Rename skill to "Surf Skill — One Skill, All Crypto Data"
- Rewrite description to match landing page positioning
- Fix E004: make 429 retry behavior transparent to user
- Add data boundary section to mitigate prompt injection risk (W011)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Boss requested: remind agents to run `surf install` to upgrade CLI
before starting a session, ensuring latest commands and fixes.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Adds try-first auth flow with structured error handling for 401/429/403,
canned user messages for free tier, credit exhaustion, and paid balance.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: rewrite README with skill intro, data coverage, and doc links
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update auth from OAuth login to SURF_API_KEY env var
The surf CLI no longer uses OAuth. Auth is now solely via the
SURF_API_KEY environment variable.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: hughzhou-gif <hugh.zhou@cybertinolab.com>
HappySean