Build with verified support.

How the pieces fit

Early separates four questions: who is signed in, what happened on a source platform, whether that activity meets a campaign, and whether a reward was paid. Each service answers one of them.

Active deployment: Monad testnet, chain 10143, escrow 0x32192Beb858561c67CCe7C1b2dbdD60E8484Df41, deployment block 70207421. Older Base, Zama and Stellar code in the repository is historical and not part of this flow.

Three providers, three different claims

Each route has its own Reclaim provider, target format, extraction and evidence. A rule names the route explicitly; one route never satisfies another.

Timestamps are stored in UTC microseconds with a precision window. A record whose window overlaps a cutoff is indeterminate, not eligible. A missing record on a loaded page does not prove the activity never happened. Provider IDs, versions and recipe hashes are pinned in src/lib/early/providers.ts; the server rejects proofs from any other version, and the deployment’s environment must match the pin or sessions fail with PROVIDER_CONFIGURATION_MISMATCH. resolve-target turns a public share link (open.spotify.com, youtube.com/watch, youtu.be, Shorts) into the canonical target.

Verify one accepted alternative

The typed browser client lives at src/lib/early/client.ts. Import it within this application; it is not a published SDK. The variables below come from the signed-in account and the user’s campaign selection.

import { createEarlyClient } from "@/lib/early/client";

// Within Early's browser app, with its Privy account context:
const early = createEarlyClient({ wallet: walletAddress, getAccessToken });
const { rules } = await early.listCampaigns();
// Let the user select a published campaign and give consent.
const { evaluation } = await early.inspect(selectedRule.id, consent);
if (evaluation.status !== "eligible") {
  // Only after the user chooses an alternative and clicks Verify:
  const session = await early.startVerification(
    selectedRule.id, selectedRule.definition.alternatives[selectedIndex], consent
  );
  // Show session.requestUrl as a link or QR. Never auto-open/auto-collect.
  const status = await early.verificationStatus(selectedRule.id, session.sessionId);
  if (status.status === "verified") {
    const result = await early.evaluate(selectedRule.id);
    // result.status is eligibility, not a confirmed payout.
  }
}

Each campaign supplies immutable targets and explicit UTC cutoffs, such as 2026-10-01T00:00:00.000Z. Spotify saved-track evidence can match a track or its verified artist relationship. YouTube subscription evidence matches a channel; YouTube like evidence matches one exact video. Alternatives use OR. Repeat-support rules still require their stated distinct event/day counts.

Access, ownership and consent

• Authentication: every operation requires Authorization: Bearer <Privy access token> and a wallet field. The server checks that the wallet is linked to that Privy account; otherwise it returns 401 UNAUTHENTICATED.
• Origin: browser requests must come from an origin in ALLOWED_APP_ORIGINS, or the server returns 403 ORIGIN_FORBIDDEN. Third-party sites cannot call these endpoints today.
• Session ownership: a verification session belongs to the account and wallet that created it. Knowing a session ID does not grant access (403 SESSION_FORBIDDEN).
• Source binding: the first accepted proof binds a source account (a Spotify or Google account) to the Early account. A proof from the same source on another Early account is rejected with SOURCE_ALREADY_BOUND. One Google binding covers both YouTube routes.
• Consent: inspect and sessions require consent: true. Ask for it in the interface before reading saved records or starting a proof, and never open the Verifier automatically.
• Campaign management: creating, publishing and funding campaigns requires an Early team account and an approved organizer. Public sign-in does not grant those permissions.

Request and response contract

All operations below use POST /api/early/{operation}, JSON, Authorization: Bearer <Privy access token>, and a wallet field owned by that account. Browser requests must originate from the configured Early app origin. Responses are private and uncached; request bodies are limited to 1 MiB.

POST /api/early/sessions
Authorization: Bearer <Privy access token>
Content-Type: application/json

{
  "wallet": "0xYourLinkedWallet",
  "ruleId": "<published campaign ID>",
  "consent": true,
  "selection": { "route": "youtube_like", "targetId": "dQw4w9WgXcQ", "cutoff": "2026-10-20T00:00:00.000Z" }
}

200 OK
{
  "sessionId": "<Reclaim session ID>",
  "requestUrl": "<Reclaim Verifier link — show as a button or QR>",
  "expiresAt": "2026-10-13T12:15:00.000Z",
  "rewardReady": false
}

POST /api/early/session-status
{ "wallet": "0xYourLinkedWallet", "ruleId": "<campaign ID>", "sessionId": "<Reclaim session ID>" }

200 OK
{ "sessionId": "…", "status": "verified", "errorCode": null,
  "evidenceId": "…", "expiresAt": "…", "rewardReady": false }

// A rejected proof is reported on the session, not as an HTTP error:
200 OK
{ "sessionId": "…", "status": "technical_failure", "errorCode": "SOURCE_ALREADY_BOUND",
  "evidenceId": null, "expiresAt": "…", "rewardReady": false }

The Verifier submits signed proofs to Early’s callback. Keep callback capabilities, raw proofs and source identifiers out of logs, analytics and public URLs. Never embed a service-role key, signer key or Privy app secret in client code.

Keep proof, eligibility and payment separate

• verified: the server accepted and stored a proof. It may still fail a campaign’s cutoff or target rule.
• eligible: stored verified records meet the rule. Funds, expiry and duplicate protection still apply.
• awaiting_proof: collect an accepted activity only with consent.
• not_qualifying: current records do not meet the rule. Incomplete coverage does not prove the user has no other qualifying activity.
• indeterminate: source timestamp precision overlaps the cutoff.
• technical_failure / expired: recover the request or start a fresh one after expiry. Neither establishes ineligibility.

Supported Spotify and YouTube records can qualify for testnet rewards. Authorization checks campaign terms, account-bound evidence, funding, expiry and prior claims. Saving a proof alone does not authorize payment, which is why session responses always return rewardReady: false. Artist-library, album, pre-save, comment, listening and watch routes remain unfinished. The example does not broadcast transactions. A confirmed Monad receipt and canonical indexed event are separate payment evidence.

Errors and retry behavior

Errors use {"error":{"code":"…","message":"…"}}. Never retry a failed proof by weakening verification.

Sessions, replay and duplicates

• Each session carries a signed context: session ID, wallet, route, provider version, recipe hash, selection and a random nonce. A proof whose context does not match the server session is rejected (SESSION_BINDING_MISMATCH).
• The proof must be produced inside the session window (PROOF_TIME_MISMATCH), and a session accepts only one proof (SESSION_CONFLICT). The callback URL carries a random per-session capability; only its hash is stored.
• Recovering a stored record does not need a new proof: reopen /rewards?session=<id> or /dashboard#support while signed in to the same account.
• Reproving the same source event creates no extra support event; events are keyed by a server-side nullifier. Unliking and liking again creates a new, later event.
• Each claim uses a per-benefit source nullifier. The escrow rejects a second claim from the same source or the same wallet.
• Limits: source binding cannot show that two independently controlled accounts belong to different people, and it cannot stop a user from sharing their own session link.

Campaign lifecycle

1. A team member saves a rule (example below). Payout is in wei; claimExpiry is Unix seconds. The cutoff (when activity must have happened) and the claim expiry (when claims close) are different times.
2. Publish it under an approved organizer. Publication does not fund anything.
3. The creator wallet calls transaction with create, then fund, and signs both. Funding cannot exceed payout × capacity.
4. A fan with eligible records calls transaction with claim, signs it, and the app calls reconcile with the hash until it is confirmed. Envio updates follow.
5. After expiry, the creator can refund the unclaimed balance. The admin cannot withdraw campaign funds.

{
  "version": 1,
  "title": "Early demo — exact video like",
  "alternatives": [
    { "route": "youtube_like", "targetId": "dQw4w9WgXcQ", "cutoff": "2026-10-20T00:00:00.000Z" },
    { "route": "spotify_saved_track", "targetId": "spotify:track:<22-character ID>", "cutoff": "2026-10-20T00:00:00.000Z" }
  ],
  "minimumDistinctEvents": 1,
  "minimumDistinctDays": 1,
  "payoutWei": "10000000000000000",
  "capacity": 10,
  "claimExpiry": 1761523200
}

Gas: verification needs no gas. Claims use Privy gas sponsorship only when it is funded; otherwise the user must explicitly choose to pay with their own test MON from the Monad faucet. A failed sponsored transaction is never silently retried as user-paid.

Privacy and retained data

• Stored privately: normalized evidence (route, target, channel, timestamp, coverage), a keyed source-account nullifier, sessions and evaluations.
• Raw proofs are encrypted at rest and deleted after RAW_PROOF_RETENTION_HOURS (1–168, default 24). Cleanup runs once a day, so deletion can lag by up to a day.
• Public onchain: the claiming wallet, benefit ID, amount, transaction and a source nullifier that cannot be reversed into the source account. Source activity and proofs are never written onchain.
• The source platform still holds its own record of the activity. See the privacy policy for user-facing terms.

Run it locally

1. Node 22 and pnpm 9: pnpm install.
2. Copy .env.example to .env.local. You need your own Reclaim app, Privy app, Supabase project, raw-proof encryption key, source-nullifier secret and an eligibility signer. Provider IDs and versions must equal the pins in providers.ts.
3. Apply the SQL in supabase/ in order: early_monad_v3, early_partner_access_v4, early_campaign_publication_v5, early_sponsored_receipts_v6, early_youtube_like_v6.
4. Run pnpm dev. Reclaim must reach your callback, so phone proofs need a publicly reachable NEXT_PUBLIC_APP_URL.
5. Checks: pnpm test:app, pnpm typecheck, pnpm lint, pnpm test:monad (Foundry), pnpm check:indexer and pnpm test:e2e.

Troubleshooting: PROVIDER_CONFIGURATION_MISMATCH means environment provider settings differ from the pins; a Verifier success with no record usually means the callback could not reach your server; a YouTube like that is “not found” is often older than the first loaded likes page.

Try it with your account

Published campaigns and your own records are loaded only when requested. No sample records are substituted when a campaign or service is unavailable.

Loading your account…