[parity] declare the API routes alerts/account/web/agent already call in schema.json

[gulshngill]

What

src/schema.json is the CLI's machine-readable surface description — shell completions, --help, docs tooling and automated surface checks all read it. It is maintained by hand, and eight routes the code already requests were never declared in it.

This PR declares them. Docs-only: no handler, request, or behaviour changes.

Command	Route the code calls	Declared as
alerts list	GET /api/v1/smart-alert/list	endpoint
alerts create	POST /api/v1/smart-alert	endpoint
alerts update	PATCH /api/v1/smart-alert	endpoint
alerts toggle	PATCH /api/v1/smart-alert/toggle	endpoint
account	GET /api/v1/account	endpoint
web search	POST /api/v1/search/web-search	endpoint
web fetch	POST /api/v1/search/web-fetch	endpoint
agent	POST /api/v1/agent/fast or /api/v1/agent/expert	apiEndpoints

agent resolves its route from --expert at call time (src/commands/agent.js:210), so it declares both under apiEndpoints rather than naming a single billed endpoint — the convention the perp commands already follow, and the one src/__tests__/schema-bridge-perp.test.js encodes.

What this closes

Before this change, nine routes were requested by CLI code without being declared in src/schema.json. This PR declares eight of them, taking the undeclared count from nine to one.

The remaining one, /api/v1/points/leaderboard, is deliberately not declared here: #542 removes that dead route together with its schema leaf, so declaring it now would conflict. None of the declarations added here contradict the documented HTTP method for their path.

Validation

Each declared route was checked for existence against the published API surface. No credentials, wallet addresses, or response payloads were used or reproduced.

Route	Result	Basis
POST /api/v1/search/web-search	confirmed reachable	unauthenticated request resolves to this route, and the response differs from the one an unknown path produces
POST /api/v1/search/web-fetch	confirmed reachable	same check
POST /api/v1/agent/fast	confirmed reachable	same check
POST /api/v1/agent/expert	confirmed reachable	same check
GET /api/v1/account	unconfirmed	authentication is refused before routing, so the check is inconclusive without an API key; documented in the published API reference as GET, not deprecated
GET /api/v1/smart-alert/list	unconfirmed	same inconclusive reason; documented as GET, not deprecated
POST / PATCH /api/v1/smart-alert	not safely checkable	account-mutating (creates/updates an alert); documented as POST + PATCH, not deprecated; call sites src/api.js:1644,1648
PATCH /api/v1/smart-alert/toggle	not safely checkable	account-mutating; documented as PATCH, not deprecated; call site src/api.js:1652

Nothing here is a removal, so no route needed proof of absence. Every declared path is one the CLI code demonstrably requests today — call sites are cited above and in the commit message.

Run from a fresh npm ci, with API and service credentials cleared from the environment:

• npm test — 62 files, 2540 passed, 2 skipped
• npm run lint — clean

Same result on pristine main, so the suite is green either side of this change.

One flake was seen on an earlier npm test run (update-check.test.js → "should show update notification on stderr for help command"). It reads and writes the real per-user update-check state file, so it races with anything else touching that file; it passes in isolation and on clean full-suite runs, on this branch and on main alike. Unrelated to this change — flagging it as a pre-existing test-isolation weakness, not fixing it here.

Notes

Opened by an automated surface-parity check that compares the API's published surface against the MCP server and this CLI.

Scope is limited to the routes that check flagged. alerts delete calls a path-parameterised route (/api/v1/smart-alert/{id}), which the check excludes as a template and which was not flagged — left alone deliberately.

This is a proposal for human review. Auto-merge is not enabled.

🤖 Generated with Claude Code

[nansen-pr-reviewer]

pr-reviewer Summary for #28714c6

📝 1 finding

Review completed. Please address the findings below.

Findings by Severity

Severity	Count
🟡 Medium	1

Review effort: 1/5 (Trivial)

Summary

This is a clean, well-scoped docs-only PR. All eight endpoint/apiEndpoints declarations added match the actual API call sites in src/api.js and src/commands/agent.js. The agent command correctly uses apiEndpoints (plural) rather than endpoint to reflect its dual fast/expert dispatch, matching the convention already established by the perp mutating commands. The cross-check between declared routes and code call sites is solid.

Findings (1 medium)

src/schema.json — alerts create and alerts update share the same endpoint

Severity: medium

Both alerts create (POST) and alerts update (PATCH) are declared with "endpoint": "/api/v1/smart-alert". The actual API calls confirm they hit the same path but with different HTTP methods (src/api.js:1644 POST, src/api.js:1648 PATCH). This is accurate, but because getCostForEndpoint() in src/cli.js keys entirely on the path string, both subcommands will look up and display the same credit cost, which is the correct behaviour — the two operations share a billing route.

However, the schema as written gives no indication to tooling (completions, docs generators, the parity checker) which subcommand is a write vs. a read. Every other write-path command in the schema that shares this ambiguity (e.g. perp mutating commands) resolves it by using submitsTo or by the direct Hyperliquid path. For the Nansen API write routes there is currently no method field convention in the schema. This means the parity checker and help renderer can't distinguish the two, which is fine today but could silently cause a mismatch if the API ever splits them.

Suggested fix: This is consistent with how update was already handled before this PR (the routes were just undeclared), so the immediate fix is simply a forward-looking one: add a "method": "POST" / "method": "PATCH" annotation to each subcommand entry (mirroring the method already used internally in src/api.js). If the project decides to adopt this convention, open a follow-up issue; otherwise this finding is advisory only.

If no method field convention is planned, you can close this finding as a known intentional omission — but it's worth a code comment or a TODO on alerts update explaining the shared path.

---

Token usage: 395 input, 5,263 output, 461,562 cache read, 34,124 cache write | Usage Guide

New pushes are reviewed automatically with a 10-minute cooldown between reviews. To request a review at any time, comment @nansen-pr-reviewer re-review.

[nansen-pr-reviewer]

Auto-approved

This PR was automatically approved because:

• Claude recommends approval
• Claude assessed this as a minimal effort change
• The effort level is within the auto-approval threshold of 2
• No high or critical issues were detected
• Review comment contains non-blocking feedback

If you have any concerns, please request a manual review.