# overview

basefun has **four on-chain contracts** and **three off-chain services**.

```
                ┌──────────────────────┐
                │  basefun.app (web)   │
                │  Next.js + wagmi     │
                └──────────┬───────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌─────────┐  ┌─────────┐  ┌────────────┐
        │  API    │  │ Keeper  │  │  Telegram  │
        │ Fastify │  │ Node.js │  │    bot     │
        └────┬────┘  └────┬────┘  └─────┬──────┘
             │            │              │
             └────────────┴──────────────┘
                          │
                  ┌───────▼────────┐
                  │  Postgres (RW) │
                  └────────────────┘

                  Base mainnet on-chain
   ┌────────────┬────────────┬──────────────┬─────────────────┐
   │ FactoryV3  │ LTFactory  │ BondingCurve │ BasefunTokenV2  │
   │ (current)  │            │  (per token) │   (per token)   │
   ├────────────┴────────────┴──────────────┴─────────────────┤
   │            LeveragedToken (shared per pair/lev/dir)      │
   ├──────────────────────────────────────────────────────────┤
   │                  Avantis perpetuals                      │
   └──────────────────────────────────────────────────────────┘
```

## On-chain components

| Contract                                                                  | Purpose                                                                                                                    |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [FactoryV3](broken://pages/a9756182af5d750a7869ee97ddd0bc36eeea5847)      | Current launchpad. Deploys curve + V2 token, charges $1 deploy fee, does the mandatory initial buy, owns `migrateToUniV2`. |
| FactoryV2                                                                 | Legacy launchpad. Same role, but deploys V1 tokens (no fee-on-transfer post-grad).                                         |
| [LTFactory](broken://pages/2ff69fc33423a312df2ab01ff5aca73ca8281a84)      | Deploys (or returns existing) LeveragedToken per `(pairIndex, leverage, direction)`.                                       |
| [BondingCurveV2](broken://pages/ae1e6a5b0dd30d90d6eceda857b1a1a4afb2d8b4) | One per token. Constant-product AMM with virtual reserves; routes USDC into the LT.                                        |
| [BasefunTokenV2](broken://pages/2f74fa1e9b722d5fde0bea0603c8da21bcb13957) | One per token. ERC-20 with 1% FOT on pair-touching transfers; immutable treasury + creator addresses.                      |
| [LeveragedToken](broken://pages/2ff69fc33423a312df2ab01ff5aca73ca8281a84) | One per `(pair, lev, dir)`. Shared across every basefun token with the same triplet. Wraps an aggregated Avantis perp.     |

## Off-chain components

| Service                                                                 | Purpose                                                                                                                                                                                |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [API](broken://pages/0ba32516f077e7022ce5e234d43910fcf765f481)          | Fastify HTTP server (Postgres + viem) on Railway. Indexer + REST. Serves the home list, token pages, trades, holders, earnings, candles. Also acts as image proxy.                     |
| [Keeper](broken://pages/ab2e04f2e1a5e5bc6e904c617917bb21b3319dd9)       | Node.js worker. Listens to LT events, opens Avantis perps with delegated calls, auto-migrates graduated curves, swaps post-grad FOT fees to USDC and dispatches to treasury + creator. |
| [Telegram bot](broken://pages/0b881f93cf6ddc09c111191163cabbdf10d72ad3) | Polls the DB and posts a launch alert (image + caption + Buy button) into the basefun Telegram group on every new token.                                                               |

## On-chain interactions

```
┌──────────┐  createToken      ┌────────────┐
│ Creator  │ ────────────────▶ │ FactoryV3  │
└──────────┘                   └─────┬──────┘
                                     │ deploys
                                     ▼
                          ┌────────────────────┐
                          │  BondingCurveV2    │ ← buy/sell → ┌────────────┐
                          │  BasefunTokenV2    │              │  Trader    │
                          └─────────┬──────────┘              └────────────┘
                                    │ lt.mint(usdc) on buys
                                    │ lt.redeem(lt)  on sells
                                    ▼
                          ┌────────────────────┐
                          │  LeveragedToken    │ ← USDC pull → ┌────────────┐
                          │  (shared LT)       │               │ Keeper EOA │
                          └────────────────────┘               └─────┬──────┘
                                                                      │
                                                                      ▼
                                                          ┌────────────────────┐
                                                          │  Avantis Trading   │
                                                          │  (open / close)    │
                                                          └────────────────────┘
```

## Postgres schema (high-level)

| Table                                           | Rows                       | Used by                                       |
| ----------------------------------------------- | -------------------------- | --------------------------------------------- |
| `Token`                                         | One per launched token     | API list, token page, keeper feeSwap, indexer |
| `Trade`                                         | Every Bought/Sold/Swap     | Chart, trades tab, earnings, recent trades    |
| `Holder`                                        | (token, address) → balance | Holders tab                                   |
| `HolderTransferCursor`                          | Per Transfer log applied   | Idempotency for the indexer                   |
| `IndexerCursor`                                 | Last block scanned         | Indexer resume                                |
| `Image`                                         | Uploaded launch images     | Image proxy                                   |
| `TgBotSent`                                     | Per-token alert dedupe     | Telegram bot                                  |
| `TgBotCursor`                                   | Cursor for the alert loop  | Telegram bot                                  |
| `KeeperCursor`, `KeeperLT`, `KeeperPendingMint` | Keeper bookkeeping         | Keeper                                        |

The DB is shared across the API, keeper, and tgbot — schema is owned by the API's Prisma project, with the keeper / tgbot creating their own auxiliary tables via raw SQL.


---

# 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://basefun.gitbook.io/basefun-docs/overview.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.