Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.filter.fun/llms.txt

Use this file to discover all available pages before exploring further.

​
HP scoring ▼

filter.fun’s HP score determines who survives the cut and who gets filtered. The numbers aren’t arbitrary — they’re empirically fit against historical token launches and cross-validated against published academic research. This page documents the scale, the components, the methodology, and the citations.

​
The HP composite

HP is a 0–10000 integer. Computed as the weighted sum of five components, each on a 0-1 scale, multiplied by 10000 and rounded. 
HP = round(Σ(weight_i × component_i) × 10000)
A token at the maximum of every component scores 10000. A token at zero on every component scores 0. Real tokens land in the 3000–9000 range based on Track E corpus runs. Why 0–10000:
  • Matches the basis-point convention used throughout filter.fun (fee splits, settlement math, HHI computation)
  • Integer storage eliminates float-precision bugs in rank comparisons at the cut threshold
  • Same effective resolution as 0–100 with two decimal places (10000 discrete values either way) but cleaner display and JSON
  • Aligns with “HP” as a high-score-style integer (cultural convention from games)
Tie-break rule: in the rare event of an exact HP tie at the cut (hour 96) or settlement (hour 168), the token launched earlier wins. The off-chain ranking algorithm sorts primarily by HP descending, then by launchedAt ascending. Deterministic, on-chain-verifiable, and preserves the early-launcher reward built into the season cadence.

​
The five components

ComponentWeightWhat it measuresOutput
velocity30%Decayed net buy inflow — buy pressure with recency weightingpercentile-rank within cohort → 0-1
effectiveBuyers15%Σ sqrt(walletBuyVolume) — sqrt-dampened economic significance (sybil-resistant)percentile-rank within cohort → 0-1
stickyLiquidity30%max(0, lp_depth − α × lp_removed_24h) — LP depth penalized by recent withdrawalspercentile-rank within cohort → 0-1
retention15%early_holders_still_holding / early_holders_count — fraction of early holders still inalready 0-1 by construction
holderConcentration10%HHI (Herfindahl-Hirschman Index) on filtered holder balances, log-mapped — penalizes whale-cluster ownershipalready 0-1 by construction

​
Why these five (and not others)

Three principles shaped the active component list:
  1. No raw market cap. Market cap is gameable by a single whale buy at thin liquidity. HP rewards real demand, not price action.
  2. No raw unique-buyer count. Sybil farms can manufacture wallet count cheaply. The sqrt-dampening on effectiveBuyers plus the HHI penalty on holderConcentration make sybil construction quadratically expensive.
  3. No social-signal data inside HP. Social volume is high-leverage but un-verifiable on-chain and breaks HP’s deterministic, auditable property. Social data lives on spectator surfaces (planned Phase 3) but doesn’t influence eliminations.
A worked example. Suppose a token’s components score: 
velocity            = 0.85
effectiveBuyers     = 0.62
stickyLiquidity     = 0.78
retention           = 0.71
holderConcentration = 0.55
Then: 
HP = round((0.85 × 0.30 + 0.62 × 0.15 + 0.78 × 0.30
          + 0.71 × 0.15 + 0.55 × 0.10) × 10000)
   = round(0.7435 × 10000)
   = 7435
This token scores HP 7435 — well above the median, comfortably surviving most cohorts.

​
How we derived the weights

The weights aren’t theoretical. They’re the output of an empirical research track called Track E that ran across five iterations, each on real on-chain corpora, with statistical analysis and cross-validation against external research.

​
The story arc

RunnHeadline finding
v248First real signal across the 5 baseline components; holderConcentration validated as the candidate 6th component (positive predictive signal, no rank disruption)
v3250Stratification gaps + outcome-label leakage flags surfaced; momentum input bug diagnosed (98% zero)
v4100 stratifiedL2 fit assigned momentum 0% on every outcome label across a balanced corpus; stickyLiquidity confirmed as dominant non-leakage signal; weights LOCKED
v4 validation7Random-sample-then-FDV funnel returned too small a cohort; v5 algorithm fix filed
v543Liquidity-first scan algorithm; LOCKED weights ρ +0.364 (p=0.016, significant — validated)

​
What the methodology actually does

For each Track E run:
  1. Build a stratified corpus. Pull a balanced sample of survivor + dead tokens from Clanker V4 launches. v4 used 50/50 dead/survivor (n=100); v5 used a liquidity-first scan against PoolManager Swap logs to recover top-FDV tokens (n=43).
  2. Compute HP components for each token at hour 96 post-launch using the production scoring code.
  3. Compute outcome labels the components don’t read — survived_to_day_7, holder_retention_at_30d, price_floor_at_30d. The decoupling matters: if outcomes derive from data the components also read, fitted weights are inflated by leakage.
  4. Fit weights via L2-regularized logistic regression against each outcome label. Compare to defaults.
  5. RandomForest feature importance as a non-linear sanity check.
  6. Leakage discipline — flag any component-vs-outcome correlation with |ρ| ≥ 0.85; treat the corresponding fitted weights as inflated, don’t act on them.
  7. Lock decision — adopt only fitted weights that survive the leakage check, have non-trivial empirical signal, and don’t disrupt rank stability vs current weights.

​
What the data said about each component

  • stickyLiquidity is the dominant predictor. v4 RF importance 0.38 (highest of any component); v5 Spearman ρ +0.87 against price-floor outcome. Empirical weight in the L2 fit was 42%, but the leakage flag (component and outcome share underlying LP data) means that’s an inflated upper bound. Locked at 30% — a conservative middle ground between the prior default (20%) and the inflated fit (42%).
  • retention is a real but leakage-suspect signal. v4 ρ +0.93 against the same-name outcome label hit the leakage threshold. Held at the prior default 15%.
  • holderConcentration validated as a real component across two runs (v2 ρ +0.46 / AUC 0.80; v3 ρ +0.39 / AUC 0.61). Adding it doesn’t disrupt rankings (rank stability ρ +0.997 to +1.000). Locked at 10%.
  • velocity and effectiveBuyers are weaker than prior defaults suggest. v4 L2 fit assigned 19% and 20% (vs 30% and 15% prior). With n=100 and known leakage in the outcome that drove the fit, deviating on these would be over-fitting. Held at defaults: 30% and 15%.
  • A sixth component, momentum, was tested and removed. The L2 fit assigned momentum 0% on every outcome label across a 100-token stratified corpus. Diagnostic showed 42% of survivor-half tokens had structurally flat HP in the 72h→96h window where momentum is measured. The component was structurally degraded by the current delta-window definition. Removed; its 10% weight slot was redistributed to stickyLiquidity (the strongest non-leakage signal). The component’s code remains in place behind a feature flag (HP_MOMENTUM_ENABLED=false) for v6 reconsideration if a wider delta window surfaces signal.

​
Cross-validation against published research

The most credibility-bearing part of the methodology is that filter.fun’s empirical findings independently match results from external research on adjacent launchpad ecosystems. Marino, Naviglio, Tarantelli, Lillo (2026) — “Predicting the success of new crypto-tokens: the Pump.fun case” (arxiv 2602.14860) — a peer-reviewable analysis of n=567,876 pump.fun tokens. Their three headline findings, mapped to filter.fun’s components:
Marino findingfilter.fun equivalentStatus
”Fast accumulation of liquidity through a small number of trades is the strongest predictor of graduation”stickyLiquidity as dominant componentCross-validated
”Markets dominated by bot-like activity exhibit systematically lower graduation probabilities”holderConcentration HHI penalty + effectiveBuyers sqrt-dampeningCross-validated, design vindicated
”Presence of historically successful traders provides at most a modest and non-monotonic effect”(we considered cross-token wallet history, didn’t model it)Confirms our scope
wangr.com pump.fun analysis dashboard — n=567,876 tokens with mortality + holder + graduation data. Reports approximately 12-day average lifespan and 0.5% graduation rate. Track E v4’s observed survivor rate of 4.5% on Clanker V4 lands within wangr’s reported pump.fun band (3-5%), corroborating that the corpus mortality side of the analysis generalizes across launchpad venues. Why this matters: filter.fun is on Base, not Solana, and uses Uniswap V4 hooks instead of pump.fun’s bonding curve. The fact that two independent analyses on different chains and different launchpad mechanics arrive at the same dominant predictors is strong evidence that the HP design is targeting the right signal — not just an artifact of our specific corpus.

​
Honest caveats

The Track E v5 validation cohort showed pre-v4 defaults (which kept momentum at 10%) edging the LOCKED weights by Δρ≈0.045 on n=43 — both weight sets reach significance individually, but the gap is real and consistent with v4’s directional finding at n=7. The reconciling story: validation cohort is recent-active by construction; momentum signal may be more informative there than in the dead-launch-heavy main corpus. The momentum coefficient is the most fragile call in the locked weight set. We held the lock for mainnet despite this for five reasons:
  1. The empirical case from the main corpus (n=100 stratified, RF importance, L2 fit, leakage-aware analysis) outweighs n=43 with Δρ=0.045
  2. Marino cross-check + wangr base-rate match corroborate the main corpus
  3. Off-chain weights make post-mainnet revision cheap (see “How weights are deployed” below)
  4. Asymmetric risk: a mis-tuned LOCKED is detectable + fixable at runtime; mis-tuned pre-v4-defaults would run silently if the main-corpus signal was correct
  5. The 7-day public-notice procedure for any weight change adds material cost; better spent on a post-mainnet refit with real filter.fun data than on a third pre-mainnet revision
A v6 / post-mainnet refit will revisit momentum once filter.fun has approximately 30+ days of its own corpus data.

​
How weights are deployed

Weights live in scoring-engine config — not in contract bytecode. Contracts only see the oracle-published Merkle root of rankings; they never read weight values directly. This is a deliberate architectural choice: the load-bearing on-chain invariant is the oracle/Merkle path, while weights remain tunable post-deploy without a contract migration. Weight-update flow:
  1. New locked values + rationale published (changelog entry)
  2. HP_WEIGHTS_VERSION constant updated (e.g., 2026-05-05-v4-locked-int10k → 2026-Q3-v6-stratified-int10k)
  3. Public notice posted (X + docs.filter.fun/changelog) with at least 7-day timer before activation
  4. Indexer/scoring service redeployed; from that block forward, all hpSnapshot rows are tagged with the new version
  5. The /scoring/weights endpoint reflects the new active version
Public verifiability:
  • Live weights queryable at /scoring/weights
  • Every hpSnapshot row in the indexer is tagged with weightsVersion for historical reproducibility
  • At least 7 days of public notice before any weight change activates
Why off-chain:
  • Weight revisions are a continuous research process (Track E v2 → v3 → v4 → v5 already shows multiple iterations)
  • Pinning weights to contract bytecode would freeze them or require constant contract migrations
  • Contracts already enforce the load-bearing invariant via the oracle/Merkle-publish path

​
What’s next

Post-mainnet refit: once filter.fun has approximately 30+ days of its own corpus, weights will be refit against both stratified and recent-active cohorts. The momentum coefficient will be revisited at that point — if a wider delta window (96h − 48h vs current 96h − 72h) surfaces signal, momentum may be revived at 5-10% weight. If not, the 5-component composition stays. Other deferred work (non-blocking):
  • WETH-pair filter at FDV-sample step (lifts validation cohort n closer to 50)
  • Liquid coverage gap (134 lifetime / 1 active in 7d as of v5)
  • Marino cross-check on a stratified validation cohort (current cohort structurally can’t populate Marino’s failure cell)
HP scoring is the load-bearing mechanic of filter.fun’s tournament. It’s empirically grounded, cross-validated, and runtime-revisable as the protocol learns from its own data.