bug: --filter silently ignored on perp screener, perp leaderboard, and smart-money perp-trades

[Nicolai1205]

Summary

--filter is accepted without error across perp commands but silently ignored — the API receives it, discards it, and returns unfiltered results. Users get no indication the filter had no effect.

Reproduction

# Filter for BTC only — expect 1 result, get full unfiltered list starting with HYPE
nansen research perp screener --filter 'token_symbol=BTC' --limit 3

# Filter for a specific trader — expect their trades only, get unrelated traders
nansen research smart-money perp-trades --filter 'trader_address=0x577ae91c7b74f04ddb3a5b399ded8318e9895fd2' --limit 3

Actual output (screener):

token_symbol │ ...
─────────────┼─────
HYPE         │ ...   ← filter ignored, returned top by default sort
xyz:SNDK     │ ...
WLD          │ ...

Expected: Either BTC row only, or an explicit error: --filter is not supported for this endpoint.

Root cause

perpScreener and smartMoneyPerpTrades in src/api.js receive a filters object from the CLI and pass it to the API, but the underlying endpoints do not support server-side filtering. The API silently drops the parameter. The CLI has no guard to reject or warn before the request is made.

The src/schema.json schema for perp screener and perp leaderboard intentionally omits filters from their options — so agents reading the schema correctly won't offer --filter. However, the CLI still accepts the flag globally and passes it through, which misleads interactive users.

Proposed fix

Add a noFilters (or similar) guard in the perp and smart-money perp-trades handlers — identical to the pattern used for historical-token-flow-summary and historical-smart-money-balances (which already error early when unsupported flags are passed):

// src/cli.js — perp screener handler
'screener': () => {
  if (Object.keys(filters).length > 0) {
    throw new NansenError(
      'perp screener does not support --filter. Use --sort to order results.',
      ErrorCode.INVALID_PARAM
    );
  }
  return apiInstance.perpScreener({ orderBy, pagination, days });
},

Same guard for perp leaderboard and smart-money perp-trades.

Why this fix works

It follows the existing early-rejection pattern already in the codebase (e.g. historical-token-flow-summary errors on --page/--limit). Users get an immediate, actionable error instead of silently wrong results. No API change required.

Discovered via

Dogfooding nansen-cli perp commands v1.31.1.