API Documentation

FOUNDER Score API v1.0.0 -- REST endpoints for wallet scoring, collection analysis, project registration, and mint signatures.

Base URL

https://api.score.founderfi.xyz

All endpoints are prefixed with /v1.

Authentication

Public endpoints (score lookup, tiers, leaderboard) require no authentication. Project management uses the FOUNDERFi Glyph cookie or Bearer JWT. Mint signatures and billing endpoints use project API keys.

// Project API endpoints
Authorization: Bearer ff_access_token

// Mint and billing API endpoints
X-API-Key: fs_proj_your_api_key_here

Endpoints

GET/v1/score/:address

Get the FOUNDER Score for any wallet address.

Auth: None (rate limited)

Parameters

address(path)Ethereum address (0x...)

chains(query)Comma-separated chains (ethereum,base,apechain). Default: all.

Response Example

{
  "address": "0x1234...5678",
  "score": 78,
  "tier": "solid_holder",
  "tierLabel": "Solid Holder",
  "breakdown": {
    "holdBehavior": { "name": "Hold Behavior", "score": 82, "weight": 0.35, "signals": [...] },
    "collectionQuality": { "name": "Collection Quality", "score": 71, "weight": 0.25, "signals": [...] },
    "walletMaturity": { "name": "Wallet Maturity", "score": 68, "weight": 0.15, "signals": [...] },
    "riskSignals": { "name": "Risk Signals", "score": 90, "weight": 0.15, "signals": [...] },
    "community": { "name": "Community", "score": 45, "weight": 0.10, "signals": [...] }
  },
  "chains": { "ethereum": { "score": 80, "nftCount": 45 }, "base": { "score": 72, "nftCount": 12 } },
  "flags": { "newWallet": false, "noNFTActivity": false },
  "meta": { "computedAt": "2026-04-03T12:00:00Z", "version": "1.0.0", "chains": ["ethereum", "base", "apechain"] }
}

GET/v1/score/:address/history

Get score history for a wallet. Requires Pro+ subscription.

Auth: Required (Pro+)

Parameters

address(path)Ethereum address (0x...)

days(query)Number of days of history. Default: 30.

Response Example

{
  "address": "0x1234...5678",
  "days": 30,
  "history": [
    { "score": 72, "tier": "solid_holder", "computedAt": "2026-03-15T12:00:00Z" },
    { "score": 78, "tier": "solid_holder", "computedAt": "2026-04-03T12:00:00Z" }
  ]
}

GET/v1/collections/:address

Get the FOUNDER Score for an NFT collection. Scores the aggregate holder quality.

Auth: Optional

Parameters

address(path)Collection contract address (0x...)

chain(query)Chain (ethereum, base, apechain). Default: ethereum.

Response Example

{
  "contractAddress": "0xBC4CA0...",
  "chain": "ethereum",
  "score": 82,
  "tier": "solid_holder",
  "breakdown": {
    "holderQuality": { "score": 85, "weightedAvg": 78, "scoredHolders": 450, "totalHolders": 500 },
    "concentrationRisk": { "score": 72, "hhi": 0.032, "topHolderShare": 0.15 },
    "badActorExposure": { "score": 88, "badActorCount": 12, "totalImpact": 0.04 }
  },
  "holderCount": 500,
  "topHolders": [...],
  "metadata": { "name": "Bored Ape Yacht Club", "symbol": "BAYC", "totalSupply": 10000, "imageUrl": "..." }
}

GET/v1/collections/:address/history

Get score history for a collection. Requires Growth+ subscription.

Auth: Required (Growth+)

Parameters

address(path)Collection contract address

days(query)Number of days. Default: 30.

chain(query)Chain. Default: ethereum.

Response Example

{
  "address": "0xBC4CA0...",
  "days": 30,
  "history": [
    { "score": 80, "tier": "solid_holder", "computedAt": "2026-03-15T12:00:00Z" }
  ]
}

GET/v1/tiers

Get tier definitions and scoring category weights.

Auth: None

Response Example

{
  "tiers": [
    { "slug": "diamond_hands", "label": "Diamond Hands", "range": [90, 100], "color": "#6D28D9" },
    { "slug": "solid_holder", "label": "Solid Holder", "range": [70, 89], "color": "#8B5CF6" }
  ]
}

POST/v1/projects

Auth: Glyph cookie/Bearer

Parameters

name(body)Project name (required)

contractAddress(body)Mint contract address

chain(body)Chain (ethereum, base, apechain)

chainId(body)EVM chain ID

basePriceWei(body)Base mint price in wei

tierMultipliers(body)Array of 5 multipliers [Diamond, Solid, Neutral, Flipper, RedFlag]

Response Example

{
  "projectId": "uuid",
  "apiKey": "fs_proj_...",
  "tierPrices": ["30000000000000000", "50000000000000000", ...],
  "trustedSigner": "0x..."
}

GET/v1/projects/:id

Get project details for a project owned by the authenticated user.

Auth: Glyph cookie/Bearer

Parameters

id(path)Project ID

Response Example

{
  "id": "uuid",
  "userId": "ff_user_id",
  "name": "Project name",
  "status": "active",
  "apiKeys": [{ "id": "uuid", "label": "default", "createdAt": "..." }]
}

POST/v1/mint-signature/nonce

Issue a single-use mint nonce for a wallet. The nonce expires after 15 minutes.

Auth: API Key

Parameters

address(body)Wallet requesting mint (required)

Response Example

{
  "nonce": "0x...",
  "walletAddress": "0x...",
  "projectId": "uuid",
  "expiresAt": "2026-04-21T12:15:00.000Z"
}

POST/v1/mint-signature

Generate an ECDSA signature for tier-based minting. Requires project API key.

Auth: API Key

Parameters

address(body)Wallet requesting mint (required)

nonce(body)Single-use nonce from /v1/mint-signature/nonce

chain(body)Chain for the mint

Response Example

{
  "address": "0x...",
  "score": 78,
  "tier": 1,
  "tierLabel": "Solid Holder",
  "price": "50000000000000000",
  "expiry": 1712170800,
  "nonce": "0x...",
  "signature": "0x...",
  "blocked": false
}

POST/v1/billing/checkout

Create a Stripe Checkout session for tier upgrade.

Auth: API Key

Parameters

tier(body)'creator' ($29/mo) or 'studio' ($99/mo)

Response Example

{ "checkoutUrl": "https://checkout.stripe.com/...", "sessionId": "cs_..." }

GET/v1/billing/status

Get current subscription status and rate limits.

Auth: API Key

Response Example

{
  "tier": "creator",
  "status": "active",
  "limits": { "ratePerMinute": 100, "bulkAddresses": 100, "maxProjects": 1, "wlAnalysis": true, "mintSignatures": true }
}

Rate Limits

Tier	Price	Rate Limit	Bulk	Projects
Free	$0	10/min	10	0
Creator	$29/mo	100/min	100	1
Studio	$99/mo	500/min	1,000	5
Genesis Holder	Free	500/min	1,000	5

Scoring Signals (16)

Hold Behavior (35%)

A1: Median Hold Time -- How long does the wallet hold NFTs before selling?
A2: Flip Rate -- What % of NFTs are sold within 7 days?
A3: Time-to-List -- How quickly does the wallet list minted NFTs?
A4: Still-Held Ratio -- Of recent acquisitions, how many are still held?

Collection Quality (25%)

B1: Collection Diversity -- How many unique collections does the wallet hold?
B2: Bluechip Exposure -- What % of holdings are top-50 collections?
B3: Secondary Market Ratio -- What % of acquisitions are secondary buys?
B4: Collection Affinity -- How focused is the wallet on specific niches?

Wallet Maturity (15%)

C1: Wallet Age -- Days since first transaction.
C2: Total NFTs Held -- Current portfolio size.
C3: Multi-Chain Activity -- Active on 1, 2, or 3+ chains.
C4: Mint Selectivity -- Ratio of mints to total acquired collections.

Risk Signals (15%)

D1: Wash Trading -- Circular transfer patterns (A to B to A within 72h).
D2: Bot Detection -- Consistent timing and gas patterns.
D3: WL Spot Sell -- Transfer to fresh wallet within 1hr of acquisition.
D4: Gas Behavior -- Standard deviation of block gaps (low = automated).

Community (10%)

E1: Social Linking -- ENS name + Gitcoin Passport ownership.
E2: DAO Voting -- Snapshot votes in the last 12 months.
E3: Floor Sweep -- Multiple tokens from same collection in quick succession.