FarGraph

MVP docs

Current implementation notes for the Referral OS MVP. This is the operator-facing reference for the code that already exists in the repository.

Open dashboard

What is implemented

  • App provisioning with hashed API key and per-app server secret.
  • Owner-scoped builder onboarding inside the dashboard for apps, campaigns, and referral links.
  • Unified event ingestion with rate limits, idempotency, and trusted conversion gating.
  • App-scoped referral links, redirect routing, and session-aware attribution context.
  • Queue-based conversion derivation plus first-touch and last-click attribution.
  • Campaign reports, funnel, top creators, channels, casts, links, payout CSV, and trace debugging.

Current guardrails

  • Management endpoints are owner-scoped through a Sign In With Farcaster session cookie.
  • Conversions are derived by the conversion_jobs queue and processor endpoint, not inline in the request path.
  • Automatic payouts, graph intelligence, and creator marketplace workflows remain out of MVP scope.
  • Schema changes still need to be pushed into the target database before a real deployment.

Core endpoints

POST /api/v1/apps

Create an app and receive the raw API key plus per-app server secret once.

POST /api/v1/events

Single ingestion endpoint for SDK events, client-side started conversions, and trusted completed server-side conversions.

POST /api/v1/referral-links

Create app-scoped referral links that can optionally belong to a campaign.

POST /api/v1/campaigns

Create a minimal campaign object for grouped reporting and onboarding flow.

GET /r/[code]

Resolve the referral link and forward source context into the destination mini app.

POST /api/internal/jobs/process-conversions

Internal queue processor for trusted conversion derivation. Protect with JOB_RUNNER_SECRET.

Event model

  • Client events: link_clicked, miniapp_opened, miniapp_added, sign_in_completed, wallet_connected, notification_opted_in, cast_shared, invite_sent, invite_accepted, session_engaged_30s, tutorial_completed
  • Conversion events: claim_started, claim_completed, swap_started, swap_completed, checkout_started, payment_completed
  • Started conversion events can come from the client or server and do not require trusted auth
  • Completed conversion events are trusted-only and require x-server-secret plus idempotency_key
  • The ingestion path validates campaign_id and referral_link_id against the app before storing the event
  • Successful conversion events enqueue background derivation work instead of building conversions inline

Example trusted event

curl -X POST https://your-domain/api/v1/events \
  -H "x-api-key: <app-api-key>" \
  -H "x-server-secret: <app-server-secret>" \
  -H "content-type: application/json" \
  -d '{
    "event_name": "payment_completed",
    "session_id": "anon_123",
    "referral_link_id": "<optional-link-id>",
    "idempotency_key": "tx:0xabc",
    "tx_hash": "0xabc",
    "value_usdc": "24.99"
  }'

Queue operations

Use the processor endpoint directly from a scheduler, or run the packaged helper command below inside the deployed environment.

npm run jobs:process-conversions

Required env: APP_BASE_URL, JOB_RUNNER_SECRET, and optionally PROCESS_CONVERSIONS_LIMIT.

Recommended next phase

  1. 1. Push schema changes into the target database and run the queue against seeded traffic.
  2. 2. Hook the processor command into your production scheduler or cron surface.
  3. 3. Seed real design-partner integrations and watch trace views against live traffic.
  4. 4. Move into graph intelligence only after enough trustworthy conversion history exists.

Builder onboarding flow

  1. 1. Sign in with Farcaster on the landing page.
  2. 2. Create an app in the dashboard and save the one-time credentials.
  3. 3. Create a campaign from the app overview.
  4. 4. Create campaign-scoped referral links and distribute them in casts, channels, or creator outreach.