# Flair

## 🔮 Flair <a href="#user-content--flair" id="user-content--flair"></a>

Real-time and historical custom data indexing for any evm chain.

[Flair](https://flair.dev/) offers reusable **indexing primitives** (such as fault-tolerant RPC ingestors, custom processors, re-org aware database integrations) to make it easy to receive, transform, store and access your on-chain data.

<figure><img src="/files/BoM7kVxGhA0VwAviXOA7" alt=""><figcaption></figcaption></figure>

### Why Flair? <a href="#user-content-why-flair" id="user-content-why-flair"></a>

Compared to other alternatives the main reasons are:

* 🚀 Adopting **parallel and distributed processing** paradigm means high scalability and resiliency for your indexing stack. Instead of constrained sequential processing (e.g Subgraph).
* 🧩 Focused on **primitives**, which means on the left you plug-in an RPC and on the right you output the data to any destination database.
* 🚄 Native **real-time stream processing** for certain data workload (such as aggregations, rollups) for things like total volume per pool, or total portfolio per user wallet.
* ☁️ **Managed** cloud services avoid DevOps and irrelevant engineering costs for dApp developers.
* 🧑‍💻 Avoid decentralization **overhead** (consensus, network hops, etc) since we believe to enable best UX for dApps reading data must be as close to the developers as possible.

#### Features <a href="#user-content-features" id="user-content-features"></a>

* ✅ Listen to **any EVM chain** with just an RPC URL.
  * Free managed RPC URLs for +8 popular chains already included.
  * Works with both websocket and https-only RPCs.
* ✅ Track and ingest **any contract** for **any event topic.**
  * Auto-track new contracts deployed from factory contracts.
* ✅ **Custom processor scripts** with Javascript runtime (with **Typescript** support)
  * Make external API or Webhook calls to third-party or your backend.
  * Get current or historical USD value of any ERC20 token amount of any contract address on any chain.
  * Use any external NPM library.
* ✅ **Stream** any stored data to your destination database (Postgres, MongoDB, MySQL, Kafka, Elasticsearch, Timescale, etc).

### Getting Started <a href="#user-content-getting-started" id="user-content-getting-started"></a>

1️⃣ Clone the [starter boilerplate](https://github.com/flair-sdk/starter-boilerplate) template and follow the instructions

```
git clone https://github.com/flair-sdk/starter-boilerplate.git
# ... follow instructions in README.md
```

:::info

Boilerplate instructions will create a **new cluster**, generate **an API Key**, and set up a manifest.yml to index your **first contract** with **sample custom processor** scripts.

Learn more about the [structure of manifest.yml](https://docs.flair.dev/reference/manifest.yml).

:::

2️⃣ Configure Planq RPC nodes

Set a unique namespace, Planq chainId and RPC endpoint in your config. Remember that you can add up to 10 RPC endpoints for resiliency.

```
{
  "cluster": "dev",
  "namespace": "my-awesome-planq-indexing-dev",
  "indexers": [
    {
      "chainId": 7070,
      "enabled": true,
      "ingestionFilterGroup": "default",
      "processingFilterGroup": "default",
      "sources": [
        # Highly-recommended to have at least 1 websocket endpoint
        "wss://XXX",
        # You can put multiple endpoints for failover
        "https://evm-rpc.planq.network"
      ]
    }
  ]
}
```

3️⃣ Sync some historical data using [backfill command](https://docs.flair.dev/reference/backfilling). Remember that `enabled: true` flag in your `config` enabled your indexer to capture data in real-time already.

```
# backfill certain contracts or block ranges
pnpm flair backfill --chain 7070 --address 0x6911dE03899e040745bdAC855333E294B927945D -d backward --max-blocks 10000

# backfill for a specific block number, if you have certain events you wanna test with
pnpm flair backfill --chain 7070 -b 10329277

# backfill for the recent data in the last X minute
pnpm flair backfill --chain 7070 --min-timestamp="30 mins ago" -d backward
```

4️⃣ [Query](https://docs.flair.dev/#getting-started) your custom indexed data.

5️⃣ Stream the data to your [own database](https://docs.flair.dev/reference/database#your-own-database).

### Examples <a href="#user-content-examples" id="user-content-examples"></a>

Explore real-world usage of Flair indexing primitives for various use-cases.

#### DeFi <a href="#user-content-defi" id="user-content-defi"></a>

* [Aggregate protocol fees in USD across multiple chains](https://github.com/flair-sdk/examples/tree/main/aggregate-protocol-fees-in-usd)
* [Calculate "Health Factor" of positions with contract factory tracking](https://github.com/flair-sdk/examples/tree/main/health-factor-with-factory-tracking)
* [Index Uniswap v2 swaps with USD price for all addresses](https://github.com/flair-sdk/examples/tree/main/uniswap-v2-events-from-all-contracts-with-usd-price)

#### NFT <a href="#user-content-nft" id="user-content-nft"></a>

* [Index ERC721 and ERC1155 NFTs on any EVM chain with an RPC URL](https://github.com/flair-sdk/examples/tree/main/erc721-and-erc1155-nft-indexing)

### Need help? <a href="#user-content-need-help" id="user-content-need-help"></a>

[Our engineers](https://docs.flair.dev/talk-to-an-engineer) are available to help you at any stage.


---

# Agent Instructions: 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:

```
GET https://docs.planq.network/for-dapp-developers/dev-tools-and-integrations/flair.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.