Skip to main content

Farcaster Integration API

Overview​

Vartovii Farcaster integration exposes Mini App, Frame-compatible, and deep-link endpoints under /api/farcaster, plus the Farcaster manifest at /.well-known/farcaster.json.

For production rollout and user-facing QA flow, see: /docs/features/farcaster-miniapp-launch-checklist.

The current scanner contract follows a hybrid mode:

  • Deterministic guardrails for validation and baseline risk checks.
  • AI layer for contextual explanation when available within latency budget.

Production Status Snapshot (2026-02-28)​

  • Manifest for sentryanalytic.com validates in Farcaster Developers dashboard.
  • Mini App response includes mode, confidence, reason_codes, analysis_version, cached.
  • Deep-link route /app/forensics/:address is active and linked from Mini App.

Manifest​

GET /.well-known/farcaster.json​

Returns Farcaster account association and Mini App frame metadata.

Key listing/discovery fields now supported:

  • primaryCategory
  • tags[]
  • screenshotUrls[]
  • subtitle
  • tagline
  • ogTitle
  • ogDescription
  • ogImageUrl
  • castShareUrl
  • noindex

Farcaster metadata constraints to respect:

  • subtitle: max 30 chars
  • tagline: max 30 chars

Frame / Mini App Endpoints​

GET /api/farcaster/frame​

Returns the start HTML for the scanner experience.

Includes:

  • fc:miniapp metadata
  • backward-compatible fc:frame metadata
  • in-page scanner UI (address -> score -> risks -> share -> full report)

POST /api/farcaster/frame/check​

Runs contract analysis from Farcaster UI actions.

Accepted input patterns:

  • Frame-style payload: untrustedData.inputText
  • Direct Mini App payload: address

Validation:

  • Strict EVM address format (0x + 40 hex chars)
  • Invalid payloads return deterministic 400 JSON

Response fields (JSON mode)​

{
  "address": "0x...",
  "trust_score": 0,
  "risk_level": "LOW|MEDIUM|HIGH|CRITICAL|UNKNOWN",
  "summary": "string",
  "key_risks": ["string"],
  "positive_factors": ["string"],
  "contract_type": "string",
  "name": "string",
  "symbol": "string",
  "code_size": 0,
  "tx_count": 0,
  "owner": "0x... | null",
  "owner_renounced": "true | false | null",
  "total_supply": "number | string | null",
  "analysis_version": "string",
  "confidence": "low|medium|high",
  "reason_codes": ["string"],
  "mode": "deterministic|hybrid_ai",
  "cached": false,
  "source": "string",
  "latency_ms": {
    "total": 0,
    "chain": 0,
    "ai": 0
  }
}

If the client requests HTML, the endpoint renders frame_result.html.

Deep-Link / Core Platform Endpoint​

GET /api/farcaster/contract/{address}​

Read-only full-view endpoint for dashboard deep-link routing (/app/forensics/:address).

Behavior:

  • Validates address format
  • Returns normalized analysis payload
  • Adds navigation links:
    • links.dashboardUrl
    • links.baseScanUrl

Use query param source to preserve funnel attribution (source=farcaster).

Growth Analytics Endpoint​

POST /api/farcaster/events​

Event ingestion endpoint for Mini App growth funnel instrumentation.

Allowed events:

  • miniapp_open
  • scan_submit
  • scan_success
  • scan_share_click
  • deep_link_open

Request shape:

{
  "event": "scan_submit",
  "source": "farcaster_miniapp",
  "session_id": "optional",
  "payload": {}
}

Unknown events return 400.

Environment Variables​

Important env-backed manifest and behavior controls:

  • FARCASTER_DOMAIN
  • FARCASTER_HOME_URL
  • FARCASTER_WEBHOOK_URL
  • FARCASTER_CAST_SHARE_URL
  • FARCASTER_URL_VERSION (optional cache-busting query suffix for Mini App URLs)
  • FARCASTER_PRIMARY_CATEGORY
  • FARCASTER_TAGS (comma-separated)
  • FARCASTER_SCREENSHOT_URLS (comma-separated)
  • FARCASTER_OG_TITLE
  • FARCASTER_OG_DESCRIPTION
  • FARCASTER_OG_IMAGE_URL
  • FARCASTER_NOINDEX
  • FARCASTER_ANALYSIS_VERSION
  • FORENSIC_CACHE_TTL_SECONDS
  • FORENSIC_AI_TIMEOUT_SECONDS
  • FORENSIC_CHAIN_TIMEOUT_SECONDS
  • BASE_RPC_TIMEOUT_SECONDS

Caching & Client Refresh​

Runtime adds no-cache headers on Farcaster endpoints to reduce stale UI risk.

If Farcaster client still serves older metadata/UI, bump FARCASTER_URL_VERSION and re-refresh the manifest in Farcaster Developers dashboard.