Project documentation

Walper turns Solana wallets into measurable identities. It ranks real wallets by on-chain trading performance, shows each wallet's verified record (PnL, win rate, activity), and lets anyone open a YES/NO position — with play money — on whether that wallet keeps performing over the next 7 or 30 days.

Project status

Working prototype, deployed at walper.markets. It covers Phase 1 (wallet intelligence) and Phase 2 (paper markets) of the concept document. Phase 3 — real money, oracles, compliance — is intentionally out of scope.

Design principle

The hard part of this product is defining performance — realized vs. unrealized PnL, cost basis, benchmarking. Walper does not re-derive any of that. It is a thin application layer over data providers that already compute it for Solana, so the codebase stays small and the numbers stay auditable.

Prerequisites

• Node.js 20.9 or later (required by Next.js 16) and npm.
• A Postgres database — the project uses Neon. Required for any page that touches markets.
• Free API keys for Vybe Network, Helius and Birdeye (optional to start — see below).

Install and run

The repository is private — ask the maintainer for access, then:

git clone <repository-url>
cd walper
npm install
cp .env.local.example .env.local   # then fill in your keys
npm run dev                        # http://localhost:3000

Without API keys the app still runs: every provider call falls back to clearly labelled demo data (an amber banner shows when this is happening), so the whole product can be explored before signing up for anything. The database, however, is required for markets and the portfolio.

Scripts

All configuration is through environment variables in .env.local (gitignored). The committed .env.local.example documents each one — never put real keys in it.

DATABASE_URL is marked sensitive on Vercel, so vercel env pull cannot export it — copy it from the Vercel Storage tab or the Neon dashboard.

Next.js 16 (App Router) with TypeScript and Tailwind CSS v4, deployed on Vercel. Pages are React Server Components that call provider wrappers and the database directly; client components talk to a small set of route handlers so API keys never reach the browser.

Layers

Source layout

src/
  app/
    page.tsx              landing page
    docs/page.tsx         this documentation
    app/                  the product: Discover, wallet, watchlist,
                          markets, market detail, portfolio
    api/                  route handlers (see API reference)
  components/             UI pieces; landing/ holds landing-page sections
  lib/
    config.ts             env vars + hasVybe()/hasHelius()/hasBirdeye()
    types.ts              shared domain types
    providers/            vybe.ts, birdeye.ts, helius.ts
    amm/lmsr.ts           market-maker maths (pure, client + server safe)
    db/                   Postgres pool, schema, per-table queries
    market-kinds.ts       the four market templates
    market-seed.ts        keeps the featured-market pool topped up
    market-settlement.ts  settles or voids markets when their window closes
    market-eligibility.ts which wallets can have a community market
    solana-address.ts     wallet address validation (client + server)
    session.ts            anonymous paper-trading session cookie
    watchlist.ts          browser-local watchlist
    mock-data.ts          demo-mode fallback data

Failure handling

Every provider call is wrapped in try/catch. A missing key or failed request never crashes a page: display paths fall back to demo data and log to the server console. Settlement is the exception — it never uses demo data, and leaves a market open rather than resolving it on missing or bad data.

Vybe was the original choice for everything, but its per-wallet PnL endpoint is only on the paid Developer plan (confirmed with a live 403 on a free key). Birdeye offers the equivalent on its free package, so wallet PnL comes from Birdeye and the leaderboard stays on Vybe.

Birdeye reports win_rate as a 0–1 fraction; Walper scales it to a percentage in one place (providers/birdeye.ts).

Every wallet profile shows a Reputation Score from 0 to 100: one number summarising how well the wallet has traded over the last 30 days, with the breakdown shown next to it. It is built only from signals Walper can measure reliably, and the full method is published here.

At a glance

Design principles

• Only reliable signals. If an input can't be measured accurately for a wallet, that signal is marked “not measurable” and its weight is shared among the others. Nothing is estimated or filled in.
• Fixed, published curves. Each signal becomes 0–100 through a fixed formula, not a ranking against other wallets — so a wallet's score doesn't change because other wallets were viewed.
• Evidence over luck. Small samples are pulled toward average, so a handful of lucky trades can't produce a top score.
• Realised gains count more. Unrealised profit is marked at prices the wallet may not be able to sell at, so it counts at 50.0%.

The three signals

How the score is calculated

1. return      = (realised + 0.5 × unrealised) ÷ invested
   Performance = 50 + 50 × tanh(return ÷ 0.4)

2. trades      = winning trades + losing trades
   adjusted    = (win rate × trades + 10 × 0.5) ÷ (trades + 10)
   Consistency = clamp((adjusted − 0.15) ÷ 0.7) × 100

3. share       = best token's PnL ÷ sum of all profitable tokens' PnL
   Risk        = clamp((1 − share) ÷ 0.8) × 100

4. blend       = weighted average of the measurable signals
                 (45% / 30% / 25%, re-normalised if one is missing)

5. score       = round(50 + (blend − 50) × trades ÷ (trades + 30))

Step 2 adds 10 imaginary trades at a 50% win rate, which barely moves a wallet with thousands of trades but stops a 9-for-10 streak reading as a 90% win rate. Step 5 does the same for the whole score: at 30 trades the score sits halfway between the blend and 50.

Scoring curves

Reference points, computed from the live formulas:

Sample size and confidence

A wallet with no closed trades, or nothing invested in the window, is not scored — the profile says so instead of showing a number.

Tiers

Warnings

Shown under the breakdown. They don't change the score; they tell you how to read it.

Worked example

A wallet invested $100,000, realised $18,000, holds $6,000 unrealised, won 58.0% of 120 trades, and its best token made 40.0% of its profit.

What v0 leaves out, and why

Limitations

• Win rate and PnL are Birdeye's figures; Walper inherits their definitions (including a win-rate denominator that isn't exactly wins + losses).
• The weights and curve anchors are judgement calls, chosen to be easy to explain — not fitted to outcomes. They will be revisited once there is data on how scores relate to later performance.
• A 30-day window can't tell a lasting edge from a good month.
• Scores are computed on demand and not stored, so they aren't yet shown on the leaderboard.
• Any change to the method will increase the version number shown on each score and be recorded here.

A market asks a YES/NO question about one wallet's performance over a fixed window. Each share pays $1 if its side wins and $0 otherwise, so a price of $0.62 reads as a 62% implied probability.

Market kinds

Windows are limited to 7 or 30 days because those are the periods the providers return in a single call. Thresholds are fixed constants in src/lib/market-kinds.ts, which also holds each kind's question and resolution-rule text so creation, settlement and the UI never disagree.

Featured and community markets

Featured markets keep the page populated: whenever fewer than 20 featured markets are open, the markets page tops the pool back up. Community markets don't count toward that floor. Every wallet has at most one open market at a time — trying to create a second takes you to the existing one.

Creating a community market

Search a wallet address in the app header, open its profile, choose “Create market” and pick a question. Because a community market can be on any wallet, creation runs behind guardrails, enforced by the server (POST /api/markets), not just the page:

The wallet's profile shows the same eligibility check before you try, with the reason when a wallet doesn't qualify. Wallet ownership isn't verified, so someone can create a market on their own wallet and then trade to influence it — acceptable with play money, and labelled as a community market, but a hard blocker for any real-money phase.

Pricing

Prices come from the Logarithmic Market Scoring Rule (LMSR), the standard automated market maker for binary prediction markets without an order book. Its worst-case loss is bounded at b · ln 2 — about $693 at the liquidity parameter b = 1000 used here — which is what makes running unbacked play markets sound. b is tuned for visible price movement on $25–500 trades, not validated for production.

Sessions and balances

No signup. On first use, an anonymous session id is stored in an httpOnly cookie (valid one year) and a $10,000 paper balance is created for it. Clearing cookies starts a new balance.

Settlement

Markets settle lazily: there is no scheduled job. The first request that reads a market after its window closes settles it against live data (Birdeye for the wallet, plus Vybe's SOL price for “Outperform SOL”) and pays out every open position in one transaction.

• Market detail pages and the trade endpoint settle their one market before doing anything else, so no one can trade on a decided market.
• List views settle at most 4 due markets per request, one at a time, sharing a single Birdeye lookup per wallet and window. This keeps a burst of due markets inside Birdeye's free-tier rate limit.
• After Birdeye returns HTTP 429, settlement skips Birdeye for 60 seconds instead of retrying into the limit.
• If data is missing, the market stays open and is retried on a later request — it is never settled on a guess. After 7 days it is voided instead (see below).

Void and refunds

A market is voided, and every position refunded at its cost basis, when:

• the data provider reports no qualifying trades for the wallet in the measured window — a win rate or return over zero trades has no answer, so it isn't resolved NO; or
• the wallet's data can't be fetched for 7 days after the window closed, so no market stays open forever.

Voided markets appear under the Settled tab marked “Void · refunded”, with the reason on the market page.

Every market page prints its exact resolution rule under “Resolution rules”.

Four Postgres tables, created automatically on first connection (src/lib/db/client.ts). Trades and payouts run in real transactions, which is why the app uses Neon's Pool rather than its stateless HTTP client.

Internal JSON endpoints used by the app's client components. They are not a public, versioned API. Endpoints that create a session set the session cookie.

• Light-first, with a real light/dark toggle. One restrained accent, chartreuse #C8FF3D; green and red are reserved for performance, never decoration.
• Typography: Geist and Geist Mono.
• Tokens live in src/app/globals.css — defined on :root (light) and .dark — and are mapped into Tailwind utilities such as bg-surface and text-text-dim.
• An inline script in the root layout applies the saved or system theme before first paint, so there is no flash of the wrong theme.
• Motion (Framer Motion) is restrained and respects prefers-reduced-motion.

• Hosted on Vercel (project walper), built with next build.
• Set DATABASE_URL, BIRDEYE_API_KEY, VYBE_API_KEY and HELIUS_API_KEY in the Vercel project's environment variables.
• The database must be hosted (Neon): serverless functions have a read-only, ephemeral filesystem, which is why an earlier local-SQLite version failed in production.
• After changing this page, run npm run docs:pdf and commit the regenerated PDF.

• Only four fixed market kinds; no user-defined thresholds, windows or market types.
• No accounts: the paper balance lives in a cookie and the watchlist in browser storage.
• Settlement only happens when someone views a market after its window, so quiet markets can stay open longer than their deadline — and a late settlement is measured on the most recent window, not the market's own (see Paper markets → Void and refunds).
• Search takes a full wallet address only; .sol names aren't resolved yet.
• Wallet ownership isn't verified, so community markets can be created on — and influenced by — the creator's own wallet.
• There is no way yet for a wallet's owner to ask for a community market on their wallet to be removed.
• Discover is a single leaderboard, not the concept document's six discovery categories.
• No wallet-vs-SOL performance chart yet (Birdeye's /wallet/v2/pnl/chart could provide it).
• Helius sometimes returns blank descriptions for unrecognised transactions; the feed falls back to “<source> transaction”.
• First-seen date is approximated from the latest 100 activity items, not a full history walk.
• Provider failures on display pages fall back to demo data silently (apart from the banner) rather than showing an error state.