creator-profile-enrichment

Quick Start (most common)

• Decide the input type:

- Creator EOA address - Creator coin address (will be resolved to creator address)

• Fetch aggregated reputation using the existing aggregator (read-only, no writes):

- frontend/src/lib/reputation-aggregator.ts → getOnchainReputation(address)

• If a source is missing/empty, debug that source’s client + its API key/proxy path (Talent and Neynar are proxied through server routes).
• Treat enrichment as optional: failures should degrade gracefully (no hard crashes, no blocking core flows).

System Model (how enrichment works here)

• Aggregator (single entrypoint):

- frontend/src/lib/reputation-aggregator.ts - Fetches in parallel: Talent passport + Talent socials + Base Guild stats + Basename profile + Zora creator profile + DeBank total balance (optional) - Produces a weighted composite score + badges + trust score + social reach estimate

• Source clients:

- Talent (proxied): frontend/src/lib/talent-api.ts → calls /api/social/talent - Server handler: frontend/api/handlers/social/talent.ts (requires server env TALENTAPIKEY) - DeBank (proxied): frontend/src/lib/debank/client.ts → calls /api/debank/totalBalanceBatch - Server handler: frontend/api/handlers/debank/totalBalanceBatch.ts (requires server env DEBANKACCESSKEY) - Guild.xyz (direct): frontend/src/lib/guild-api.ts - Basenames (onchain): frontend/src/lib/basename-api.ts - Zora (direct): frontend/src/lib/zora-api.ts

• Address resolution:

- frontend/src/lib/reputation-aggregator.ts first calls resolveCreatorAddress(...) (creator coin → creator address) before fetching sources.

Required Inputs

• Target identifier: creator EOA address or creator coin address
• Runtime context:

- local dev vs preview vs production (affects env vars + serverless availability)

Never include secrets (API keys, private keys, full .env contents) in responses.

Repo Map (where to look / what to run)

• Aggregation logic: frontend/src/lib/reputation-aggregator.ts
• Talent API client: frontend/src/lib/talent-api.ts
• Talent server proxy: frontend/api/handlers/social/talent.ts
• Guild client: frontend/src/lib/guild-api.ts
• Basename client: frontend/src/lib/basename-api.ts
• Zora client: frontend/src/lib/zora-api.ts
• UI:

- frontend/src/components/cca/OnchainReputationCard.tsx - frontend/src/components/cca/CreatorProfileCard*.tsx

• System documentation: frontend/docs/onchain-reputation-system.md

Preflight Checks (fast)

• Confirm you’re not trying to call Talent directly from the browser:

- Client must call /api/social/talent (proxy keeps TALENTAPIKEY server-only).

• Confirm server env is configured for Talent:

- TALENTAPIKEY must be present in the server environment (Vercel / local env used by Vercel functions).

• Confirm server env is configured for DeBank (if you want portfolio signals):

- DEBANKACCESSKEY must be present in the server environment.

• Confirm expected degradation:

- Talent 404 is treated as a soft miss (proxy returns { success: true, data: null }). - DeBank should be treated as optional (rate limiting / missing key should not break pages).

Debug Workflows (source-by-source)

A) Aggregator returns mostly empty / score is 0

1. Confirm input is a creator address (or that resolution worked):

- Look at resolveCreatorAddress usage in frontend/src/lib/reputation-aggregator.ts

1. Check each source independently by calling its client function:

- Talent: getTalentPassport, getTalentSocials - DeBank: fetchDebankTotalBalanceBatch({ addresses: [...] }) - Guild: getBaseGuildStats - Basename: getBasenameProfile - Zora: getZoraCreatorProfile

B) Talent is always null / errors

Common causes:

• TALENTAPIKEY not set in server environment
• Request is blocked because it’s not going through the proxy

Where to fix:

• frontend/api/handlers/social/talent.ts (proxy)
• frontend/src/lib/talent-api.ts (client uses /api/social/talent)

Notes:

• The proxy sets Cache-Control: public, s-maxage=120, stale-while-revalidate=300 to reduce rate-limit risk.

C) Guild.xyz roles look wrong or missing

Check:

• frontend/src/lib/guild-api.ts uses a heuristic for “Base guild” membership (name includes “base” or guildId match).
• If the Base guild ID changes, update the matching logic there.

D) Basename missing

Check:

• frontend/src/lib/basename-api.ts uses viem ENS methods on Base/Base Sepolia.
• Ensure correct chainId and that the address has a primary name set.

Output Format (when using this skill)

Return a structured result:

• Summary: what enrichment was requested and the outcome
• Inputs: target address/coin, environment (local/preview/prod)
• Data sources:

- Talent: passport present? verified? score/rank? - DeBank: totalUsdValue present? top chains? (if configured) - Guild: roles found? key flags (isBuilder/isOnchain/etc)? - Basename: name present? key text records? - Zora: profile present?

• Aggregated result: totalScore, reputationLevel, trustScore, badges, socialReach
• Issues + fixes: missing env, proxy miswire, rate limits, invalid address resolution