Fomo API acts as a developer layer over social trading information. It turns profile, wallet, holdings, swap and performance data into consistent REST resources while preserving the fields needed for independent verification.
The core identities
A trader has three identifiers with different jobs:
| Identifier | Example | Use |
|---|---|---|
| Handle | starcatcher444 | Human-facing lookup |
| Fomo user ID | UUID | User-specific API routes |
| Wallet | Solana or EVM address | Onchain verification |
Resolve a handle to establish the mapping, then store all three. Handles are useful in interfaces, IDs are stable API keys and wallets connect social identity to independent blockchain data.
Normalized responses
Most endpoints return a predictable envelope around endpoint-specific data. This gives clients one location for the success flag, message and represented status. Wallet fields are normalized to solana and evm, which avoids leaking inconsistent upstream names into every integration.
Normalization does not mean every field is always populated. Public profiles can omit biographies or pictures, a trader may have only one wallet type and ranking windows can return null.
Network-aware token identity
A token address alone is not a safe primary key. The same textual address model can mean different things on different networks. Fomo API includes networkId, inNetworkId and outNetworkId so integrations can use:
networkId + tokenAddress
as the normalized token identity. This also makes it possible to route verification to the correct RPC or indexer.
Caching and freshness
Not every resource changes at the same rate. Leaderboards are cached by window for up to one hour. Wallet mappings are reused after they are stored by normalized handle. Balances, swaps and prices depend on upstream indexing.
This creates two important rules:
- Poll according to the expected update rate; more requests do not guarantee fresher data.
- Treat API data as observed state, not as the latest finalized blockchain state.
For execution, fetch a current quote and confirm relevant transactions on the target chain.
A reliable consumer architecture
API response
→ immutable raw event
→ schema validation
→ normalized record
→ idempotent state transition
→ signal candidate
→ independent validation
Raw storage protects against accidental data loss during parser changes. Schema validation catches malformed assumptions. Idempotency ensures retries cannot duplicate a signal. Independent validation separates social observations from financial execution.
Why balances and swaps both matter
Swaps describe events, while balances describe state. An event stream may be delayed or incomplete, and a state change can result from a transfer rather than a swap. Comparing both provides stronger evidence:
- A new swap plus a matching balance increase is a strong position-open signal.
- A balance increase without a swap may be a transfer or correction.
- A swap without an immediate balance change may still be indexing.
- A price-only valuation change is not a token movement.
Failure behavior
The API distinguishes caller errors from transient upstream failures. Clients should fail fast on 401, 403 and 422, while retrying 429, 502, 503 and 504 under strict limits.
Good retries include jitter, a maximum delay, an attempt cap and a total time budget. Emit metrics for latency, status code, retries and stale checkpoints.
Trust boundaries
Profile descriptions and comments are user-generated content. Token metadata can also contain unexpected strings. Escape content for its output context and never interpret social text as system or execution instructions.
The ideal mental model is simple: Fomo API helps your software observe and organize social trading activity. Your application remains responsible for validation, risk policy, user consent and execution.