Glidepath 🛬

You have to sell a token you never meant to own. Glidepath turns it into a dated selling calendar sized to the market's organic demand — so you are never the biggest seller on a day the pros are exiting.

It plans. It never trades. 12 credits per plan on EVM chains, 15 on solana/base, 0 on a cache hit — and the 13 recorded plans replay offline byte-for-byte with zero network calls and zero credits (npm run verify).

JUDGE.md · DEMO.md · SCORING.md · DX-REPORT.md · ARCHITECTURE.md

The PEPE plan, live on 2026-09-19 — 12 credits, 9 calls, 2.0 s; a red today (exchange net deposits +$736K) halves the first tranche — and every Nansen call streams into the rail on the right as it lands:

BONK on solana inside a red regime — today is green, but tgm/flow-intelligence 7d shows exchange net deposits of +$3.32M over the week and tgm/flows marks 1 of the last 13 days red; the costs are real trade/quote routes — and the rail shows all 12 calls that just landed, 15 credits, 5.3 s:

provenance drawer beside the rail — the receipt and the live meter, same nine calls	mobile — the TURBO thin plan, 90 tranches, 30 % still unsold; the rail is the bar at the bottom

A nonprofit's finance officer receives a $40K memecoin donation. A freelancer is paid in a project's token. They have never used a DEX, and they must turn the tokens into dollars without crashing the price or competing with the funds on the day the funds are dumping.

Paste token · chain · amount held. Glidepath:

1. Computes organic daily buy volume — DEX buys over the last 7 days by wallets that carry none of Nansen's Smart Money / Fund / Whale / Exchange / sniper-bot labels — via tgm/who-bought-sold label filters and tgm/token-information.
2. Prints the dump-today line: position value, estimated impact, and what share of a full day's organic buying you would be.
3. Sizes daily tranches to k × organic/day, where k slides from 10 % to 3 % as Nansen's peer-percentile risk indicators rise (tgm/indicators), capped at 1 % of liquidity_usd.
4. Flags red days: today from tgm/flow-intelligence (Smart Money net-selling, or net deposits to exchanges), the 13 complete days before it from tgm/flows daily cohort history (a 14-day strip with today). A red today halves the first tranche; the observed red-day rate stretches the expected finish.
5. Shows dump today vs glidepath cost — constant-product from liquidity_usd, or a real routed trade/quote on solana/base, labelled as such.
6. Exports the plan as ICS (one calendar event per tranche, with the go/no-go rule inside) and CSV, plus a share card with an OG image.
7. Streams every Nansen call into the call rail on the right as it happens (endpoint · params · credits · ms · hash), then opens a provenance drawer: every call, the fields used, credits (from Nansen's response headers), cached or live, ms — and a "computed Ns ago" badge.

It plans. It never trades.

One plan is resolve → facts → computePlan → applyQuotes; the plan is a pure function of (facts, input, now), so a recorded fixture replays to the same calendar dates, the same red history and the same decision hash. Full module map and data flow: ARCHITECTURE.md.

flowchart LR
  IN["token · chain · amount"] --> R["resolve.ts<br/>address passes through · ticker → search/general (0 credits)"]
  R --> F["facts.ts<br/>Promise.all over 8 calls, every failure lands in errors[term]"]
  F <--> C["cache.ts<br/>key = sha256(method + endpoint + canonical body)<br/>hit = 0 credits · NANSEN_OFFLINE=1 never touches the network"]
  C <--> N["Nansen API<br/>tgm/token-information · tgm/who-bought-sold ×2<br/>tgm/flow-intelligence ×2 · tgm/flows ×2 · tgm/indicators"]
  F --> P["plan.ts<br/>price → organic/day → risk dial k → tranches<br/>→ red-day rule (today + 13 days) → impact → decision hash"]
  P --> Q["impact.ts<br/>constant-product cost(V) = V²/(L/2+V)<br/>or trade/quote ×3 on solana/base"]
  Q <--> N
  P --> X["export.ts<br/>ICS (one VEVENT per tranche, go/no-go rule inside) · CSV"]
  P --> CLI["packages/cli<br/>npm run glidepath -- &lt;token&gt; --chain --amount"]
  P --> WEB["apps/web (Next.js 15)<br/>/api/plan?stream=1 → the call rail · /api/export · /api/og · /p share page"]
  N -. "CallEvent start · end (the same Call objects)" .-> WEB

The data drives the logic — every on-screen number traces to a named Nansen field.

12 credits per plan on EVM chains, 15 on solana/base, 0 on a cache hit. Formulas with the real PEPE numbers: docs/SCORING.md.

You watch it happen. The right-hand Nansen call rail streams every call as the plan is computed — /api/plan?stream=1 emits an NDJSON line when a call leaves (a pending row) and one when it lands (the recorded Call: endpoint, params, credits from the response header, ms, sha256 of the body) — the same objects the provenance drawer prints afterwards, so the rail's counters and the drawer's totals always agree. On load the rail shows the recorded example's calls labelled replayed · 0 cr; the CLI prints the same rows with --explain.

"Organic demand" is a who, not a how much. An RPC node or an explorer gives you volume; it cannot tell you which buyers are funds, Smart Money, exchanges or sniper-bot users. On Nansen that split exists as a server-side label filter on tgm/who-bought-sold — and the spike showed the filter acts on labels the row's address_label does not even display, so there is no client-side substitute. The red-day rule needs cohort net flows (tgm/flows, tgm/flow-intelligence); the risk dial needs peer-percentile scores (tgm/indicators); the route quote needs an aggregator that returns decimals with the price (trade/quote). Remove Nansen and Glidepath degrades to a TWAP calculator on raw volume — exactly the number a forced seller must not trust.

The constant-product estimate treats liquidity_usd as one pool with the token on one side. It is optimistic for tokens whose depth sits in a single thin pool, and it ignores MEV and gas. On solana and base the routed trade/quote replaces it and the label changes to "route quote". Not financial advice.

• 258 vitest tests (npm test): tranche-sizing table, red-day rule, risk dial vs indicator scores, impact model, decision-hash stability, pagination cap (the 20,000-buyer case), cache and offline mode, client retries/timeouts/header credits, ICS/CSV, resolver, end-to-end on a fake Nansen, one replay test per fixture — and three high-signal categories:
  • 18 regression tests, each named for the defect it pins (qa round …, regression (…)): the one-tranche "expect ~2 days" copy, the ICS \; no-op, the error body cut mid-word, the FLOKI empty symbol, liquidity_usd = 0, the 7-day regime that was fetched but never shown, the echoed-key redaction, the zero-token tranche; and from the 2026-09-23 audit: a non-JSON 200 recorded twice and cached for an hour, a socket error never retried, a pro list ending exactly on page 3 called truncated, a cross-model "savings" figure, an unbounded memory cache.
  • One property-based verification, 60,000 generated cases (packages/core/test/plan.property.test.ts, fast-check, 6 properties × 10,000 runs): Σ tranches + remainder = amount held; every tranche ≤ k × organic/day and ≤ 1 % of liquidity; a red today halves tranche 1 and only tranche 1; consecutive UTC dates, ≤ 90 of them, expectedDays ≥ days ≥ 1; the decision hash is deterministic and invariant to timing and context fields. Run 1 found a real defect — a liquidity cap underflowing at a dust price produced 90 tranches of zero tokens — now a guarded, fully-unsold thin plan with its own regression test.
  • Key-boundary tests (packages/core/test/boundary.test.ts, apps/web/test/api-boundary.test.ts, e2e/): the server key travels in one request header and nowhere else — plan JSON, provenance, ICS/CSV, the route handler's 400/500 bodies and the built pages are asserted free of nsn_; an upstream body that echoes the key is redacted; /api/plan validates input before the key check and before any fetch.
• 13 fixtures, 13/13 reproduced offline (npm run verify): each stores the raw Nansen responses byte-for-byte, the plan and the clock; replay must match the hash with zero network calls and zero credits.
• Bench (npm run bench, 7 tokens × 3 runs): cold p50 3.5 s / p95 6.0 s, warm p50 5 ms / p95 356 ms, 13.0 credits/plan, 9.3 calls/plan, 2.0 who-bought-sold pages/plan, 7 of 195 calls failed (6 deterministic: tgm/flows refuses stablecoins). Full table and reproduce steps: DEMO.md.

Every number traces to a named Nansen field — the provenance drawer and --explain list them per call. Nothing is estimated silently; when a call fails, the term is null, the warning names the endpoint, and the plan degrades (no history strip, no route quote, k treated as medium) instead of inventing a value. Honest states: no organic demand (< $50/day or < 5 buyers) → "there is nobody to sell to at any pace", numbers shown, no calendar. Calendar beyond 90 days → "N % still unsold after 90 days". Ticker unknown on the chain → the chains where it exists.

1. The impact model is an approximation — see the caveat: one pool, token on one side, optimistic for a single thin pool, no MEV or gas. Only solana/base get a real route quote.
2. The pro share is small. On the 11 tokens tried, Smart Money / funds / whales / exchanges were 0–3.6 % of DEX buys — Glidepath shows that split rather than dramatising it (DX-REPORT.md).
3. Future days cannot be known red or green. Today is live; the 13 complete days before it are real; each ICS event carries the rule to re-check on the morning.
4. A well-formed but nonexistent address still spends 12 credits — the parallel fan-out in facts.ts has no existence gate before it; the plan comes back no-price with no crash (independent review 2026-09-16, left as is: gating on token-information would serialise the hero path).
5. The 12 s organic-breadth timeout is the wall-time ceiling on a slow Nansen day — it timed out once during review (plan took 14.8 s, shown as a red "failed: timeout" row in provenance, "concentration not applied"); not a crash, but visible (independent review 2026-09-16).
6. Bug found and fixed — /p and /api/export had no try/catch and sat outside the spend guard. A missing server key turned a share link into a 500 page, and a loop on either GET URL could spend credits around the per-IP rate and the daily ceiling. One admit() gate now fronts all four credit-spending routes; failures render a banner or a plain-text status (audit 2026-09-23).
7. Bug found and fixed — one-tranche plans said "fits in one day" beside "expect ~2 days at the 15 % red-day rate". expectedDays is now 1 when today's colour is already known; regression in packages/core/test/plan.test.ts (independent review 2026-09-16).
8. Bug found and fixed — ICS escaping was a no-op ("\;") so ; was never escaped, and content lines were not folded at 75 octets (RFC 5545). Both fixed without splitting UTF-8; regression in packages/core/test/export.test.ts (independent review 2026-09-16).
9. Bug found and fixed — Nansen JSON error bodies were cut mid-word on screen ("…is a st"). The body's message is now surfaced as a sentence ("…is a stablecoin. The TGM flows endpoint…") (independent review 2026-09-16).
10. Bug found and fixed — seed --rederive overwrote the USDC fixture's live 422 reason with an offline-cache-miss string. The script now preserves recorded errors; the fixture was restored from the original recording (independent review 2026-09-16).
11. Bug found and fixed — the share-page "computed Ns ago" badge hydrated with a server clock (server/client mismatch), and CLI --explain did not label who-bought-sold rows as (pros)/(organic). Both fixed (independent review 2026-09-16).
12. Docs bug found and fixed — the history strip was described as "the last 14 days". Nansen's tgm/flows from is exclusive, so it is 13 complete days + live today (14 cells); wording fixed here and in SCORING.md (independent review 2026-09-16).

• Node ≥ 20
• NANSEN_API_KEY — an nsn_… key from https://app.nansen.ai/api. Only the live steps need it; without a key, npm run verify replays the 13 recorded plans offline.

Quickstart — runs in under 10 minutes:

git clone https://github.com/edycutjong/glidepath && cd glidepath    # 0:10
npm install                                                          # 0:40  (Node ≥ 20)
export NANSEN_API_KEY=nsn_...                                        # from https://app.nansen.ai/api
npm run glidepath -- PEPE --chain ethereum --amount 12000000000      # 0:05  → the plan, 12 credits
npm run dev                                                          # 0:20  → http://localhost:3000, click "PEPE · 12B"

Timed on a clean clone (macOS, Node 22, warm npm cache, 2026-09-16): clone + npm install 8 s, first live plan 2 s, npm run verify 1 s, web build 12 s — under a minute; budget 10 minutes on a cold npm cache and a slow link. Without a key, npm run verify replays the 13 recorded plans offline.

CLI flags: --json (full plan + provenance) · --explain (every tranche and every call) · --ics plan.ics · --csv plan.csv · --no-cache · --no-quotes.

7-stage pipeline: Quality → Security → Build → E2E → Performance → Deploy gate → Production Deploy (prebuilt vercel deploy to glidepath.edycu.dev, main only, after every gate) — no Nansen key anywhere; the only secret is VERCEL_TOKEN. The product is only exercised live by a human with a key.

# ── Code Quality ────────────────────────────
npm run lint          # ESLint (flat config, TS + React hooks)
npm run format:check  # Prettier
npm run typecheck     # engine + CLI + scripts   ·   npm run typecheck:web
npm test              # 258 vitest tests incl. 60,000 property cases
npm run test:coverage # + v8 coverage (100% statements/branches/functions/lines, engine + API)
npm run verify        # 13/13 recorded plans replay offline — no key, no network, 0 credits
npm run check         # submission-readiness audit (files, secrets, kitchen leaks, fixtures, verify, tests, README claims)
npm run ci            # audit + format + lint + typecheck ×2 + coverage + verify + check

# ── Advanced Testing ────────────────────────
npm run e2e           # Playwright, 4 suites × chromium + Pixel 7, built app, no key
npm run e2e:ui        # Playwright interactive mode
npm run lighthouse    # Lighthouse CI on / and /judge (a11y ≥ 0.9 is a hard gate)
npm run ci:full       # ci + next build + e2e

# ── Security / live ─────────────────────────
npm run audit         # npm audit on production dependencies (high+)
npm run bench         # live, ~270 credits for 7 tokens × 3 runs

packages/core   engine (client, cache, facts, plan, impact, export, fixtures)   packages/cli   the CLI
apps/web        Next.js 15 planner (/api/plan, /api/export, /api/og, /p)       scripts/       spike · seed · verify · bench · check
fixtures/       13 recorded live runs                                           docs/          SCORING.md · DX-REPORT.md · screenshots
e2e/            Playwright suites (no key)                                      JUDGE.md       the /judge page, mirrored for the repo reader

• Live: https://glidepath.edycu.dev — no wallet, no account; five example chips (PEPE · BONK · BRETT · TURBO · SHIB2), ICS/CSV export, share card with OG image.
• Reproduce every number: DEMO.md — the recorded PEPE plan, offline replay, tests, bench table, re-recording the fixtures, the day-one spike, and the credits spent.
• Formulas with the real PEPE numbers: docs/SCORING.md · API findings from the spike: docs/DX-REPORT.md.

MIT — see LICENSE. Built for the Nansen Meridian Buildathon (Sep 2026) by @edycutjong.