How UCI Works

Everything you need to know

TL;DR: Buy $UCI → Lock it → Earn daily tips → Reward great casters

🪙

What is UCI?

Universal Caster Income ($UCI) is a community-driven tipping token for Farcaster. Buy UCI, lock it up, and earn a daily tipping allowance to reward your favorite casters.

🔒

How Locking Works

Lock your UCI tokens for 100 days to earn a daily tipping allowance. The longer your remaining lock time, the higher your daily allowance. You can re-lock anytime to reset the timer and maximize your earnings.

📊

Daily Allowance Formula

Your daily allowance is based on TWO factors: your personal max and your share of the global pool. Your personal max = your calculated lock amount / 100. Your share of the global pool depends on how much you locked vs everyone else. Your actual daily allowance is whichever is lower.

🌐

The Global Daily Pool

Every day, 10,000,000 UCI tip tokens are available for ALL lockers to share. The pool is split based on how much each person locked. You always need at least 100 UCI locked to earn 1 tip token — this is the minimum ratio no matter how small the total locked amount is. Example: if 900M UCI is locked total, then every 900 UCI locked earns you 1 tip token per day.

🐋

Whale Dampening (Dynamic Threshold)

To keep the daily pool fair, the whale limit is reset every UTC day to 1% of the total time-decayed locked supply. Up to that limit, every UCI you have locked counts 1:1 toward your daily allowance. Above the limit, additional UCI counts for less and less, so your allowance grows more slowly the further past the limit you go. So if total time-decayed supply is 1B UCI, the limit is 10M; if it grows to 5B, the limit rises to 50M. Small and mid-size lockers always get a meaningful share of the pool, no matter how big the whales get.

Today's live numbers

Updating… today's snapshot is being prepared.

🧮

Allowance Examples

Numbers below assume today's whale limit is 10M (1% of 1B time-decayed supply). Example 1: You infinite-lock 10M UCI. Personal max = 10M / 100 = 100K. If total locked is 900M, your pool share = 10M / 900 = ~11.1K. You get 11.1K/day (pool share is lower). Example 2: You lock 1M UCI with 50 days left. Time-decayed amount = 500K. Personal max = 5K. Pool share might be higher, so you get 5K/day. Example 3: You infinite-lock 100M UCI. Because that is well above the 10M whale limit, the effective amount after dampening lands around 27M — the curve flattens beyond the limit, so the extra 90M counts for much less. Personal max = 27M / 100 = 270K. Your pool share is calculated from the 27M, not the 100M.

♾️

Infinite Lock

Go all-in with an infinite lock! Your calculated lock amount equals your full locked amount, giving you the highest personal max. If you change your mind, you can start a 100-day unlock countdown.

🎁

Referral Program

Share your referral link! When someone locks tokens using your link, you automatically earn 0.1% of their locked amount. Paid directly by the smart contract.

💬

Tipping

Tip any Farcaster post by replying "1 uci" for 1 token, "100 uci" for 100, or the 🪎 palm-tree emoji for 1000 UCI. Tips are pulled from your daily allowance and paid out on-chain — claim what you receive on the Claim tab. Receivers must have a username, profile picture, a verified address, and a minimum Neynar quality score.

⚡ Quick Reference

Lock period: 100 days

Daily pool: 10,000,000 UCI

Personal max: Calculated lock / 100

Minimum ratio: 100 UCI per tip token

Whale threshold: 1% of total time-decayed supply (resets every UTC day)

Referral bonus: 0.1%

Infinite unlock: 100-day countdown

Re-lock: Anytime, resets timer

🛠️

Public API

These read-only endpoints let anyone build on Universal Caster Income data. All responses are JSON.

Base URL: https://universal-caster-income.vercel.app

GET/api/tips/received/{fid}

Tips received by a Farcaster user, with a 30-day daily rollup.

Path params

fid — Numeric Farcaster ID

Query params

limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "fid": 366713,
  "total": { "count": 42, "requested_amount": "5200", "final_amount": "5100" },
  "daily": [
    { "day": "2026-04-18", "count": 3, "requested_amount": "300", "final_amount": "300" }
  ],
  "items": [
    {
      "receiver_fid": 366713,
      "giver_fid": 1234,
      "cast_hash": "0xabc...",
      "requested_amount": "100",
      "final_amount": "100",
      "status": "sent",
      "created_at": "2026-04-18T10:00:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "has_more": true }
}

GET/api/tips/given/{fid}

Tips sent by a Farcaster user, with a 30-day daily rollup.

Path params

fid — Numeric Farcaster ID

Query params

limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "fid": 1234,
  "total": { "count": 10, "requested_amount": "1000", "final_amount": "900" },
  "daily": [ ... ],
  "items": [
    {
      "giver_fid": 1234,
      "receiver_fid": 366713,
      "cast_hash": "0xabc...",
      "final_amount": "100",
      "status": "sent"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "has_more": false }
}

GET/api/tips/cast/{hash}

Look up a single cast. Tells you whether the cast is a tip, and if so its details.

Path params

hash — 0x-prefixed cast hash (hex)

Sample response

{
  "is_tip": true,
  "tip": {
    "giver_fid": 1234,
    "receiver_fid": 366713,
    "cast_hash": "0xabc...",
    "requested_amount": "100",
    "final_amount": "100",
    "status": "sent",
    "created_at": "2026-04-18T10:00:00.000Z"
  }
}

GET/api/tips/cast/{hash}/received

All tips whose replies targeted this parent cast.

Path params

hash — 0x-prefixed parent cast hash (hex)

Query params

limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "parent_cast_hash": "0xabc...",
  "total": { "count": 5, "requested_amount": "500", "final_amount": "500" },
  "daily": [ ... ],
  "items": [ ... ],
  "pagination": { "limit": 20, "offset": 0, "has_more": false }
}

GET/api/allowance/fid/{fid}

Today's tipping allowance for a Farcaster user (aggregated across all their wallets).

Path params

fid — Numeric Farcaster ID

Sample response

{
  "fid": 366713,
  "date": "2026-04-25",
  "wallets": [
    {
      "wallet": "0xabc...",
      "locked": "1000000",
      "infinite": false,
      "locked_timestamp": 1776523207,
      "expires_timestamp": 1785163207,
      "locked_time_decayed": "920000"
    }
  ],
  "total_locked": 1000000,
  "total_locked_time_decayed": 920000,
  "total_effective_locked": 920000,
  "effective_limit": 10000000,
  "allowance": 5000,
  "used": 200,
  "received": 1500,
  "remaining": 4800
}

GET/api/allowance/{address}

Today's tipping allowance for a single wallet address.

Path params

address — 0x-prefixed wallet address (40 hex chars)

Sample response

{
  "wallet_address": "0xabc...",
  "date": "2026-04-19",
  "allowance": 5000,
  "fid": 366713
}

GET/api/whale-dampening/today

Today's UTC whale-curve snapshot from daily_globals — total time-decayed locked supply, the dynamic threshold (1% of supply), and the anchor (half the threshold). Returns status='pending' when the cron has not run yet for the day.

Sample response

{
  "status": "ok",
  "utc_date": "2026-05-02",
  "total_locked_time_decayed": 1000000000,
  "whale_threshold": 10000000,
  "whale_anchor": 5000000,
  "computed_at": "2026-05-02T00:00:01.000Z"
}

GET/api/leaderboard

Today's top FIDs by effective UCI locked. Each entry includes the per-wallet breakdown plus the FID-level totals: raw locked, time-decayed locked (raw scaled by remaining lock time), whale-dampened effective locked, and the effective_limit field — the per-day whale-curve threshold (1% of total time-decayed locked supply, recomputed each UTC day; the anchor is half the threshold). total_locked_time_decayed and total_effective_locked can both exceed effective_limit; the limit is the curve break-point, not a hard cap.

Query params

limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "date": "2026-04-25",
  "fid_total_locked": 1147993147,
  "fid_total_effective_locked": 234399486,
  "fid_count": 28,
  "total_entries": 28,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "entries": [
    {
      "rank": 1,
      "fid": 10956,
      "username": "1dolinski",
      "total_locked": 938900000,
      "total_locked_time_decayed": 873000000,
      "effective_limit": 10000000,
      "total_effective_locked": 27000000,
      "total_allowance": 270000,
      "total_used": 0,
      "total_received": 0,
      "wallet_count": 1,
      "wallets": [
        {
          "wallet": "0xf447...21a6",
          "locked": "938858715",
          "infinite": false,
          "locked_timestamp": 1776523207,
          "expires_timestamp": 1785163207,
          "locked_time_decayed": "873000000"
        }
      ]
    }
  ]
}

GET/api/leaderboard/received

Top FIDs by total UCI tips received in the selected time range.

Query params

range — today | 7d | 30d | this_month (default this_month)
limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "range": "this_month",
  "start": "2026-04-01T00:00:00.000Z",
  "end": "2026-04-19T14:30:00.000Z",
  "total_entries": 42,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "total_amount": "12345",
  "entries": [
    {
      "rank": 1,
      "fid": 366713,
      "username": "nikolaii.eth",
      "display_name": "nikolaii.eth 🚀",
      "pfp_url": "https://...",
      "total_amount": "5000",
      "tip_count": 12
    }
  ]
}

GET/api/leaderboard/given

Top FIDs by total UCI tips given in the selected time range.

Query params

range — today | 7d | 30d | this_month (default this_month)
limit — Page size (1–100, default 20)
offset — Skip N items (default 0)

Sample response

{
  "range": "7d",
  "start": "2026-04-12T14:30:00.000Z",
  "end": "2026-04-19T14:30:00.000Z",
  "total_entries": 18,
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "total_amount": "8400",
  "entries": [
    {
      "rank": 1,
      "fid": 1234,
      "username": "...",
      "total_amount": "2100",
      "tip_count": 9
    }
  ]
}

Built by on