FarFISH LogoDocs

API Overview

FarFISH's backend services are primarily designed for internal use by the official FarFISH applications. This page provides a conceptual overview for developers interested in understanding how the ecosystem operates.

No public API documentation is currently available. The backend services are not designed for third-party integration at this time.

Architecture Concepts

Off-Chain and On-Chain Separation

FarFISH uses a two-layer architecture:

Off-Chain Layer:

  • Handles social features: leaderboards, referral tracking, user preferences
  • Provides fast, real-time updates without blockchain transaction costs
  • Stores non-financial data that doesn't require immutability
  • Powers instant rewards attribution and rankings

On-Chain Layer:

  • Manages financial operations: NFT ownership, staking, token balances
  • Ensures security, transparency, and user asset control
  • Smart contracts enforce all critical rules
  • Immutable blockchain records for all asset transfers

This separation allows FarFISH to offer instant social features (leaderboard updates, referral rewards) while keeping user assets secure on the blockchain.

Data Accessibility

What's Public

Blockchain Data (Fully Public):

  • All NFT ownership records
  • All staking positions and lock durations
  • All FRH token balances and transfers
  • All smart contract interactions
  • Available via Base blockchain explorers

Off-Chain Data (Display Only):

  • Leaderboard rankings
  • Referral relationships
  • Task completion status
  • User streaks and statistics

What's Private

FarFISH never stores:

  • Private keys or seed phrases
  • Wallet passwords
  • Personal identifying information
  • Financial data beyond public blockchain records

All sensitive data remains in your wallet under your control.

Cross-App Data Sharing

All FarFISH applications (Web App, Base App, Farcaster Mini App) share the same backend infrastructure:

Shared Across Apps:

  • User identity (wallet-based)
  • Leaderboard positions
  • Referral networks
  • Daily chest progress
  • All on-chain assets (NFTs, tokens, stakes)

Synchronization:

  • Blockchain data syncs automatically (same smart contracts)
  • Off-chain data syncs in real-time (shared backend)
  • No manual sync required when switching apps

Example: Mint an NFT in Web App → Immediately visible and stakeable in Base App

For Developers

Current Status

No Public API: FarFISH does not currently offer public APIs for third-party integration.

Why: The system is optimized for official FarFISH applications and not yet designed for external developers.

Future Plans: Economic Coordination SDK

Long-term vision includes developer tools for integrating FarFISH features into third-party applications:

Potential Future Features:

  • Embeddable referral system
  • Reputation data access (with permissions)
  • Reward distribution APIs
  • Webhook event notifications
  • JavaScript/TypeScript SDK

Status: Conceptual design phase, not yet implemented

Timeline: To be announced

The Economic Coordination SDK is a long-term vision, not a current feature. No public APIs or SDK packages are available at this time.

Integration Options Today

Smart Contract Interactions

Developers can interact with FarFISH on-chain components directly:

Available via blockchain:

  • Read NFT balances
  • Query staking positions
  • Check FRH token balances
  • Monitor contract events

See: Smart Contract Addresses for contract details

Tools:

  • Web3 libraries (ethers.js, viem, web3.js)
  • Base blockchain RPC endpoints
  • Block explorers (BaseScan)

No Off-Chain API Access

Off-chain features (leaderboards, referrals, tasks) are not accessible via public APIs.

If you need to:

  • Display user leaderboard rank → Not possible without official app
  • Attribute referrals programmatically → Not possible without official app
  • Track user streaks → Not possible without official app

Alternative: Direct users to official FarFISH apps for these features

Community and Support

Developer Resources

Questions about FarFISH architecture?

  • Review public documentation
  • Check open-source smart contracts (if published)
  • Join FarFISH community channels (links on website)

Want to build on FarFISH?

  • Wait for Economic Coordination SDK announcement
  • Focus on on-chain integrations using smart contracts
  • Reach out via official channels to express interest

For Users

Need help using FarFISH?

Next Steps

FarFISH is user-focused first. Developer tools and integrations will come as the ecosystem matures. For now, the best way to participate is as a user.