{
  "markdown": "# AntSeed Demand Explorer\n\n> Live at **[antfeed.org](https://antfeed.org)**\n\nAn open-source, on-chain index of **buyer activity** on the [AntSeed](https://antseed.com) P2P AI services network. Provider/seller activity is already surfaced on `antseed.com/network`; this app fills the gap on the demand side: who is spending USDC on inference, with which providers, and how reliably.\n\nNot affiliated with the AntSeed team.\n\n---\n\n## What it does\n\n1. **Funded buyers** — per-depositor volume, sessions, unique sellers, ghost-session count, and a derived **Buyer Trust Score** (0–100).\n2. **Network leaderboard** — sortable, filterable buyer ranking.\n3. **Network overview** — daily settlement volume, active buyers, last 30 days.\n4. **Token usage detail** — input/output tokens and request count from `AntseedStats.MetadataRecorded`, with legacy settled-session metadata decoded only after validation.\n5. **Public scoring API** — `GET /api/score/[address]` returns the trust score JSON for any address.\n\n---\n\n## Stack\n\n- Next.js 15 (App Router) + TypeScript\n- [viem](https://viem.sh) for Base reads (no wallet, read-only)\n- Neon Postgres + Drizzle ORM (HTTP driver, serverless-friendly)\n- Tailwind CSS, Recharts\n\n---\n\n## Getting started locally\n\n```bash\ncp .env.example .env       # fill DATABASE_URL with a Neon DB or a local Postgres\nnpm install\nnpm run db:push            # apply schema to your DB\nnpm run dev\n```\n\n| Script | What it does |\n|---|---|\n| `npm run dev` | Local Next.js dev server |\n| `npm run build` | Production build |\n| `npm run db:generate` | Diff schema and emit a new migration in `drizzle/` |\n| `npm run db:push` | Apply schema directly (dev-only, no migration history) |\n| `npm run db:migrate` | Apply pending migrations from `drizzle/` |\n| `npm run db:studio` | Open Drizzle Studio for browsing the DB |\n| `npm run sync` | Run a one-shot indexer pass against the configured DB |\n| `npm run sync loop` | Loop until caught up to chain head |\n\n---\n\n## Environment variables\n\n| var | default | meaning |\n|---|---|---|\n| `DATABASE_URL` | required | Postgres connection string. |\n| `RPC_URL` | `https://base.drpc.org` | Base RPC. DRPC and Tenderly free tiers allow large `eth_getLogs` ranges. |\n| `CHAIN_ID` | `8453` | `8453` Base mainnet, `84532` Base Sepolia. |\n| `CRON_SECRET` | none | Required in production. Cron requests must send `Authorization: Bearer <CRON_SECRET>`. |\n| `LOG_BATCH_SIZE` | `2000` | Max blocks per `getLogs`. Indexer auto-shrinks if RPC complains. |\n| `CHANNELS_ADDRESS` | `0xBA66d3b4f...` | Override only if you've forked to a different contract. |\n| `START_BLOCK` | deployment block | First block to index from. |\n\n---\n\n## Contract integration\n\nCore settlement contract: **`AntseedChannels`** on Base mainnet,\n[`0xBA66d3b4fbCf472F6F11D6F9F96aaCE96516F09d`](https://basescan.org/address/0xBA66d3b4fbCf472F6F11D6F9F96aaCE96516F09d), deployed at block `45,667,842`.\nAuxiliary indexers also read AntseedStats, ANTS, staking, deposits, and identity events for token accounting, holder state, DAU, and address enrichment.\n\n| event | semantic |\n|---|---|\n| `Reserved` | session opened (buyer locks `maxAmount` for a seller). |\n| `ChannelSettled` | seller called settle; `delta` USDC moved this batch. `metadata` is seller-provided opaque bytes and is stored only after validation. |\n| `MetadataRecorded` | authorized stats writer recorded per-inference input/output tokens and request count; canonical source for network token totals. |\n| `ChannelClosed` | channel closed. `settledAmount=0` + no prior `ChannelSettled` → ghost. |\n| `ChannelTopUp` | buyer added more deposit to an existing channel. |\n| `ChannelWithdrawn` | buyer pulled refund. |\n| `CloseRequested` | grace-period close started. |\n\nPer-buyer aggregates are recomputed in SQL on every sync — no event replay needed for score recomputes. The indexer runs `reconcileDrift()` after each pass to catch rare partial-sync races.\n\n---\n\n## Buyer Trust Score\n\n[`lib/score.ts`](lib/score.ts), 0–100, four sub-scores:\n\n- **Volume (0–30)** — `log10(USDC + 1) / log10(100) × 30`. $100 settled = 30.\n- **Consistency (0–25)** — `log10(sessions + 1) / log10(50) × 25`.\n- **Diversity (0–25)** — `<3` unique sellers = 0; 3 = 10; 10+ = 25.\n- **Reliability (0–20)** — `settled / (settled + ghost) × 20`.\n\nA buyer with ≥3 distinct settled sellers earns the **Qualified Proven Sign** badge.\n\n---\n\n## Public APIs\n\n```\nGET  /api/stats                      Network aggregates + 30d daily series\nGET  /api/buyers?limit=&offset=&qualified=&minScore=&sort=\nGET  /api/buyers/{address}           Buyer detail + sessions + top sellers\nGET  /api/score/{address}            Trust score JSON\nPOST /api/sync?force=1               Manual indexer pass (Bearer sync secret required)\n```\n\n`/api/score/{address}` example:\n```json\n{\n  \"address\": \"0x…\",\n  \"score\": 73,\n  \"tier\": \"trusted\",\n  \"qualified\": true,\n  \"breakdown\": {\n    \"total\": 73,\n    \"volume\": 24.1,\n    \"consistency\": 18.0,\n    \"diversity\": 18.6,\n    \"reliability\": 12.0,\n    \"qualified\": true\n  },\n  \"stats\": { \"…\": \"raw indexed counters\" }\n}\n```\n\n---\n\n## Operations\n\n- Vercel cron is the scheduled indexer owner. `vercel.json` runs `/api/cron/sync`\n  every five minutes; do not add an external minute-level cron for the same\n  endpoint.\n- `/api/cron/hero` is an authenticated manual repair endpoint only. Call it\n  with `?repair=1` after confirming `/api/cron/sync` cannot refresh the hero\n  snapshot.\n- Runtime contract checks require an explicit target:\n  `API_RUNTIME_BASE_URL=http://localhost:3000 npm run test:api-runtime` and\n  `CSP_RUNTIME_URL=http://localhost:3000 npm run test:csp-runtime`.\n- Verify shared public API rate-limit storage after migrations with\n  `npm run check:rate-limit-storage`; otherwise the app falls back to\n  per-instance limits until the table exists.\n\n---\n\n## Project layout\n\n```\nantseed-explorer/\n  app/\n    layout.tsx                  # nav + Sync button\n    page.tsx                    # / overview + top 10\n    buyers/page.tsx             # /buyers leaderboard\n    buyers/[address]/page.tsx   # buyer detail\n    api/\n      cron/sync/route.ts        # cron-driven indexer pass\n      sync/route.ts             # authenticated manual sync endpoint\n      buyers/route.ts\n      buyers/[address]/route.ts\n      stats/route.ts\n      score/[address]/route.ts\n    components/                 # Charts, Badges, CopyButton, UI helpers\n  lib/\n    schema.ts                   # Drizzle Postgres schema\n    db.ts                       # Neon HTTP client + state helpers\n    queries.ts                  # all reads used by pages/APIs\n    indexer.ts                  # getLogs loop, ghost detection, recompute, reconcile\n    antseed.ts                  # contract addresses + ABI\n    chain.ts                    # viem client\n    score.ts                    # Buyer Trust Score\n    format.ts\n  scripts/\n    sync-cli.ts                 # local CLI sync against DATABASE_URL\n  drizzle/                      # generated migrations\n  vercel.json                   # cron config + maxDuration\n```\n\n---\n\n## Contributing\n\nIssues and PRs are welcome. The most useful contributions right now:\n\n- Improved scoring models or new score dimensions\n- Additional on-chain event types or contract support\n- UI improvements and new views (e.g. seller-side explorer)\n- Better RPC resilience / retry logic in the indexer\n\nOpen an issue to discuss before submitting a large change.\n",
  "bytes": 7410,
  "sha": "ef0773ffa25197028b4be61920fffa24981b24b26a6a8473416aa611af165cf4",
  "repo_slug": "augustas11/antseed-explorer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_augustas11_antfeed_mcp_0c096486/readme"
}