> For the complete documentation index, see [llms.txt](https://docs.everstake.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.everstake.com/integrations/everstake-products/fomo.md).

# FOMO

### What is FOMO?

**FOMO** is a **high-load data service** providing **historical and current balance snapshots** for any Ethereum address. It enables to seamlessly integrate comprehensive financial histories and up-to-date on-chain balances into wallets, DeFi services, analytics platforms, and other blockchain infrastructure products. 

FOMO enables users to retrieve **historical balance data** for a specified Ethereum address via a simple HTTP endpoint

**Main Objectives:**

The system aims to solve various problems related to the lack of quick access to historical balances in public RPCs, among which FOMO can provide an answer to

* How many staking opportunities were lost?
* Quick access to historical balances
* What opportunities and investments available now? 

### System and reliability

FOMO is an elaborate project aimed at facilitating the real-time loading and retrieval of historical Ethereum balances associated with specific addresses

<table><thead><tr><th width="209">Service</th><th>Description</th></tr></thead><tbody><tr><td><strong>Node</strong></td><td>The Node service is a custom-built database that securely stores all balance data. Its optimized structure enables fast, reliable data access across the entire FOMO system.</td></tr><tr><td><strong>Writer</strong></td><td>The Writer service transfers balances from traditional database to Nodes using gRPC. It ensures efficient data loading, keeping the system synchronized and up to date.</td></tr><tr><td><strong>Parser</strong></td><td>The Parser service continuously parses real-time balance data directly from Ethereum nodes. It updates balances instantly, ensuring the system always reflects the latest state.</td></tr><tr><td><strong>Reader</strong></td><td>The Reader service handles all balance read requests, accepting queries over HTTP. It retrieves data from Nodes via gRPC to deliver fast and consistent results.</td></tr><tr><td><strong>Checker</strong></td><td>The Checker service verifies data accuracy and completeness stored in Nodes. It performs routine audits by comparing random Node entries with ClickHouse records to ensure integrity.</td></tr></tbody></table>

{% hint style="info" %}
FOMO has a cluster architecture, where each cluster is independent. Replication is also implemented, which ensures the reliability of the system: if one cluster fails, the other clusters replace it.

* Backup mechanism that increases system reliability
* Scaling logic, which makes it easier to maintain
  {% endhint %}

### Performance Overview

When a request is made, the system reads the relevant file and returns clean JSON — all in <100ms.

* One API call
* No sync time
* Clear gRPC interface

Just plug in an Ethereum address - <mark style="color:yellow;">FOMO handles the rest!</mark>

***

**Stress Test** (4 nodes)

{% columns %}
{% column %}
**Results**

* The average response time is about 100 ms

* The service’s approximate RPS is over 1000

* At a load of 1000 concurrent requests, the system remains completely stable

* The 99th percentile response time - in average 700 ms
* Ethereum balances indexed in 6 hours

  {% endcolumn %}

{% column %}
**Input parameters**

1. 100k addresses (for each test case)
2. 100 / 100 concurrent requests
3. All addresses / tokens are unique
   {% endcolumn %}
   {% endcolumns %}

<table data-view="cards"><thead><tr><th></th><th data-type="rating" data-max="5"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Average response time</strong></td><td>5</td><td><a href="https://1249209355-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsyXGefmWNIENxOOHmKgY%2Fuploads%2FbTFpvKf8RcClmHEVi4gg%2F100ms.png?alt=media&amp;token=d939166a-dba7-439c-bdd5-ded2fa431907">100ms.png</a></td></tr><tr><td>Approximate RPS</td><td>4</td><td><a href="https://1249209355-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsyXGefmWNIENxOOHmKgY%2Fuploads%2FlAPxWTZI8V5AEQuLY38z%2F1000rps.png?alt=media&amp;token=839a576f-bb6a-4df4-8331-16afb03ba4c3">1000rps.png</a></td></tr><tr><td>Longest response time</td><td>4</td><td><a href="https://1249209355-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsyXGefmWNIENxOOHmKgY%2Fuploads%2FgxYPxTISvtNmGoxY8obO%2F700ms.png?alt=media&amp;token=759b803a-f5c8-4fd1-8b46-e4331e5320e8">700ms.png</a></td></tr></tbody></table>

### Use Cases

{% tabs %}
{% tab title="Wallet Providers" %}
**Why FOMO is needed?**

Wallet providers aim to **enrich user experience and transparency** by showing complete financial histories and real-time balances inside the wallet app. Many wallets currently only show the **current balance** or require heavy infrastructure to display historical states.

**How FOMO helps?**

* Retrieve **historical snapshots** to display how a user's ETH or token holdings changed over time.
* Show users **their net worth trends directly in-app**.
* Enable users to verify their portfolio at specific dates (e.g., tax reporting, proof of funds).
* Provide **pre-send transaction validation** by instantly checking the live on-chain balance before broadcasting a transaction.

**Where display?**

* Portfolio or Assets screen showing historical balance charts.
* Transaction History extended with contextual balances before and after transactions.
* Tax and Reports section for exporting historical balances for accounting.

<details>

<summary><strong>Example</strong></summary>

A user with pubkey `0xfcfe0c43c952c946bd21b5d8d6c3577ede2a0e88` opens his wallet and sees:

<table><thead><tr><th width="165.5555419921875">Date</th><th width="224.555419921875">Balance, ETH</th><th>Balance, USD</th></tr></thead><tbody><tr><td>2025-01-04</td><td>0.1000</td><td>320.000</td></tr><tr><td>2025-04-28</td><td>0.3012</td><td>963.860</td></tr><tr><td>2025-06-20</td><td>0.3342</td><td>1069.440</td></tr></tbody></table>

{% hint style="info" %}
All powered by instant retrieval from FOMO without the wallet needing its own blockchain node and archive infrastructure'
{% endhint %}

**Request**:

```
https://fomo.everstake.one/0xfcfe0c43c952c946bd21b5d8d6c3577ede2a0e88/balances
```

**Response**:

```json
[
  {
    "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
    "block": 22443020,
    "time": "2025-01-04T02:41:23Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "100000000000000000",
    "balance_usd": "320.000"
  },
  {
    "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
    "block": 22443039,
    "time": "2025-04-28T02:45:11Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "301200000000000000",
    "balance_usd": "963.860"
  },
  {
    "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
    "block": 22443039,
    "time": "2025-06-20T02:45:11Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "334200000000000000",
    "balance_usd": "1069.440"
  }
]
```

**Response time**: 0.0789103 sec

</details>
{% endtab %}

{% tab title="Analytics Platforms" %}
**Why FOMO is needed?**

Analytics platforms require **clean, fast, historical on-chain data** to analyze user behavior, whale movements, token distribution, and trends. DeFi protocols may require historical balances for advanced risk models or reward distribution calculations.

**How FOMO helps?**

* Retrieve **monthly snapshots** of holdings across wallets to analyze user retention and accumulation patterns
* Track **whale wallets** for inflows and outflows of specific tokens
* Power **portfolio trackers** and **wallet explorers** with historical data charts.
* Calculate **holding periods** for governance or rewards distribution.

**Where display?**

* Wallet explorer dashboards showing historical token balances
* Token distribution charts segmented by wallet size over time.
* Whale tracking dashboards displaying balance changes on tracked addresses.
* Custom on-chain analytics dashboards for researchers or institutional clients.

<details>

<summary><strong>Example</strong></summary>

An analytics platform shows:

> “Wallet 0x0a4c79cE84202b03e95B7a692E5D728d83C44c76 accumulated 50,000 ETH over the last 6 months, with consistent monthly increases, indicating long-term holding behavior.

{% hint style="info" %}
All powered by instant retrieval from FOMO without the wallet needing its own blockchain node and archive infrastructure
{% endhint %}

**Request**:

```
https://fomo.everstake.one/0x0a4c79ce84202b03e95b7a692e5d728d83c44c76/balances?offset=2
```

**Response**:

```json
[
  {
    "address": "0x0a4c79ce84202b03e95b7a692e5d728d83c44c76",
    "block": 22443020,
    "time": "2025-02-04T02:41:23Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "100000000000000000",
    "balance_usd": "320000000.000"
  },
  {
    "address": "0x0a4c79ce84202b03e95b7a692e5d728d83c44c76",
    "block": 22443039,
    "time": "2025-05-30T02:45:11Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "150000000000000000",
    "balance_usd": "480000000.000"
  }
]
```

**Response time**: 0.0800832 sec

</details>
{% endtab %}
{% endtabs %}

### Endpoint Overview

To test the Reader service, you may execute a sample request using the following curl command:

```bash
curl -X GET https://fomo.everstake.one/0xfcfe0c43c952c946bd21b5d8d6c3577ede2a0e88/balances
```

**JSON schema of response:**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "address": {
        "type": "string",
        "pattern": "^[a-fA-F0-9]{40}$"
      },
      "block": {
        "type": "integer",
        "minimum": 0
      },
      "time": {
        "type": "string",
        "format": "date-time"
      },
      "token": {
        "type": "string",
        "pattern": "^0x[a-fA-F0-9]{40}$"
      },
      "balance": {
        "type": "string",
        "pattern": "^[0-9]+$"
      },
      "balance_usd": {
        "type": "string",
        "pattern": "^[0-9]+(\\.[0-9]+)?$"
      }
    },
    "required": ["address", "block", "time", "token", "balance", "balance_usd"],
    "additionalProperties": false
  }
}
```

**Example Response:**

```json
[
  {
    "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
    "block": 22443020,
    "time": "2025-05-09T02:41:23Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "300000000000000000",
    "balance_usd": "66087"
  },
  {
    "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
    "block": 22443039,
    "time": "2025-05-09T02:45:11Z",
    "token": "0x0000000000000000000000000000000000000000",
    "balance": "3880535904000",
    "balance_usd": "1"
  }
  // Additional entries can be added here
]
```

The `/last_balance` endpoint retrieves the most recent balance entry for a specified account, focusing on either native or token balances. It shares the same JSON schema as the `/balances` endpoint, ensuring consistency across responses.

**Request**

```bash
curl -X GET https://fomo.everstake.one/0xfcfe0c43c952c946bd21b5d8d6c3577ede2a0e88/last_balance
```

**JSON schema of response:**

The response will adhere to the same JSON structure as the `/balances` endpoint.

**Example Response:**

```json
{
  "address": "fcfe0c43c952c946bd21b5d8d6c3577ede2a0e88",
  "block": 22443039,
  "time": "2025-05-09T02:45:11Z",
  "token": "0x0000000000000000000000000000000000000000",
  "balance": "3880535904000",
  "balance_usd": "1"
}
```

This endpoint is useful for obtaining the latest balance quickly without querying the full balance history.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.everstake.com/integrations/everstake-products/fomo.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.