Build an Indexer

This page explains how to track every token launched on the bonding curve protocol: which events to index, and which reads to call when you need state that events do not carry.

An indexer for the bonding curve protocol listens to two contracts per chain:

VaultPortal launches a tax token through Portal, so a token launched with a vault emits events from both contracts in the same transaction. Addresses for each chain are in Deployed Contract Addresses → Bonding curve protocol.

All events below are emitted by the Portal or VaultPortal proxy address. Unless noted, their fields are not indexed: decode them from the log data.

1. Index from events

Token creation (Portal)

A launch emits several events in one transaction. Always index TokenCreated, then enrich the token record with the other events of the same transaction for the same token. Older tokens do not emit every event; apply the default listed when an optional event is missing.

Vault (VaultPortal)

Risk levels: 0 UNVERIFIED · 1 LOW_RISK · 2 LOW_MEDIUM_RISK · 3 MEDIUM_RISK · 4 HIGH_RISK. Do not use FactoryAuditReportSubmitted for a factory's effective risk level: it records a report, not the level new tokens get.

Trading and progress (Portal)

Agent ID gate and buy cap (Portal)

A launch can be Agent ID-gated: while the token is on the curve, only wallets holding at least one NFT from a chosen ERC-721 collection (the "Agent ID") can buy or sell it, and each wallet can buy at most 2% of the supply. In short:

• The gate is checked on tx.origin, collection-wide (any NFT of the collection counts). It applies only to curve trades: transfers are free, and after migration the DEX is open to everyone.
• Gated launches get a buy cap of 200 bps of the max supply per tx.origin. What counts against it is max(netBought, balanceOf(origin)): curve buys add to netBought and curve sells subtract from it (never below zero), while tokens received by transfer count through the balance. A buy above the remaining allowance is filled up to the cap and the excess input is refunded. Sells are never capped.
• Only collections on the Portal's whitelist can be used, and an admin can remove a token's gate (never add or change one) after launch.
• The gate is set at launch through the extension fields; see Extension encoding.

Migration to DEX (Portal)

DEX destination

You know where a token will migrate as soon as it is created: TokenDexPreferenceSet.dexId picks the DEX and TokenMigratorSet.migratorType the pool shape.

Suggested flow

1. Listen to TokenCreated on Portal and FlapTaxVaultTokenCreated on VaultPortal.
2. For each new token, collect the optional creation events of the same transaction and apply the defaults above for any that are missing.
3. Store the token record, its metadata CID and (if any) its vault and vaultFactory.
4. Follow TokenBought / TokenSold for trades, and LaunchedToDEX (plus FlapTokenCLPoolCreated) for migration.
5. Keep factory and token risk levels from FlapTaxVaultFactoryRegistered and AuditReportSubmitted.
6. Mark gated tokens from FlapNFTGated (and un-mark them on FlapNFTGateUpdated).

2. Read state from the chain

When you need the current state of one token, or want to fill gaps in your indexed data, read it directly. These calls are views; batch them with Multicall.

Token state: getTokenV8Safe

Portal.getTokenV8Safe(token) returns the whole state of a token in one call. Enum fields come back as uint8, so a newer enum value never breaks your ABI decoding.

struct TokenStateV8Safe {
    uint8 status;                  // TokenStatus
    uint256 reserve;               // quote reserve held by the curve
    uint256 circulatingSupply;
    uint256 price;                 // current price (quote per token, 18 decimals)
    uint8 tokenVersion;            // TokenVersion
    uint256 r;                     // curve parameters
    uint256 h;
    uint256 k;
    uint256 dexSupplyThresh;       // circulating supply at which it migrates
    address quoteTokenAddress;     // address(0) = native gas token
    bool nativeToQuoteSwapEnabled;
    bytes32 extensionID;           // bytes32(0) = no extension
    uint256 buyTaxRate;            // bps, 0 for non-tax tokens
    uint256 sellTaxRate;
    address pool;                  // DEX pool, address(0) before migration
    uint256 progress;              // towards migration, 1e18 = 100%
    uint8 lpFeeProfile;            // V3LPFeeProfile
    uint8 dexId;                   // DEXId
}

function getTokenV8Safe(address token) external view returns (TokenStateV8Safe memory state);

status: 0 Invalid (unknown token) · 1 Tradable (on the curve) · 4 DEX (migrated) · 5 Staged. Values 2 and 3 are obsolete.

Token versions

tokenVersion (from getTokenV8Safe or TokenVersionSet) tells you which token implementation a token uses:

Tax token details: TaxTokenHelper

For a tax token, TaxTokenHelper.getTaxTokenInfoV2(token) returns its tax split, cumulative statistics, dividend token and vault in one call. It is what the Flap website uses.

struct MarketingWalletInfo {
    address addr;            // the marketing wallet or vault receiving revenue
    address factory;         // vault factory, zero if not a Flap Vault
    uint8 riskLevel;         // 0 UNVERIFIED · 1 LOW · 2 LOW_MEDIUM · 3 MEDIUM · 4 HIGH
    bool isOfficialVault;
    bool isVault;            // registered through VaultPortal
    bool isAIConsumer;       // uses the Flap AI Oracle
}

struct TaxTokenInfoV2 {
    uint16 marketBps;        // tax split, in bps of the tax
    uint16 deflationBps;
    uint16 lpBps;
    uint16 dividendBps;
    uint16 buyTaxRate;       // bps
    uint16 sellTaxRate;      // bps
    uint256 burntTokenAmount;              // cumulative statistics
    uint256 totalQuoteSentToDividend;
    uint256 totalQuoteAddedToLiquidity;
    uint256 totalTokenAddedToLiquidity;
    uint256 totalQuoteSentToMarketing;
    address dividendToken;   // address(0) = native gas token
    address quoteToken;
    uint256 minimumShareBalance;           // minimum balance to earn dividends
    MarketingWalletInfo vaultInfo;
}

function getTaxTokenInfoV2(address taxToken) external view returns (TaxTokenInfoV2 memory info);
function getDividendInfo(address taxToken, address user) external view returns (uint256 claimed, uint256 pending);

vaultInfo.riskLevel is always the live value, whether it was inherited from the factory or set by the token's own audit, so it answers "is this token low risk?" without any indexing. For Tax Token V1, only marketBps (always 10000), the tax rate, vaultInfo.addr, quoteToken and totalQuoteSentToMarketing are filled in. The helper's address per chain is in Deployed Contract Addresses.

Vault: VaultPortal.tryGetVault

struct VaultInfo {
    address vault;
    address vaultFactory;   // zero if unknown
    string description;     // human-readable, for display only
    bool isOfficial;
    uint8 riskLevel;
}

function tryGetVault(address taxToken) external view returns (bool found, VaultInfo memory info);
function vaultFactories(address factory) external view returns (bool enabled, bool official, uint8 riskLevel, bytes29 reserved);

tryGetVault never reverts (found = false when the token has no vault), so it is safe in batch calls. description is not a stable format: read typed values from the vault itself, branching on vaultFactory. For one vault type worked end to end, see Index & Query a Stocks Vault.

Agent ID gate and buy cap

// The token's Agent ID collection; address(0) = not gated.
function nftGate(address token) external view returns (address nft);

// The token's per-origin buy cap; bps == 0 (and maxBuyAmount == 0) = no cap.
function maxBuyPerOrigin(address token) external view returns (uint16 bps, uint256 maxBuyAmount);

// What counts against `origin`'s cap and what it can still buy; remaining == type(uint256).max = no cap.
function buyQuotaOf(address token, address origin) external view returns (uint256 bought, uint256 remaining);

// Whether a collection may gate new launches.
function nftWhitelisted(address nft) external view returns (bool allowed);

• A token is gated only while it is on the curve (status == 1) and nftGate(token) != address(0).
• Whether a user may trade is IERC721(nft).balanceOf(user) >= 1; check it yourself. quoteExactInput enforces the cap but not the NFT check, and must be called with from = user (the cap is read on tx.origin).
• nftGate and the other reads revert on Portals older than v5.27.0; call them in a try/catch.
• Trade errors to handle: NFTGatedOnly(address wallet) (no NFT), BuyCapExceeded(address origin, uint256 held, uint256 cap) (cap reached).

How the gate and the cap work, and how to trade a gated token: Agent ID Gate.

Token metadata

TokenCreated.meta, and the token's own metaURI(), return the IPFS CID of a metadata JSON:

{
  "description": "OKIE,OKIE",
  "image": "bafkreibwjuzzns6yf4wytfr5nk6vujb4yja4iejff2k76nshn2z5jkmiy4",
  "website": null,
  "twitter": null,
  "telegram": null,
  "creator": "0x7F403F924dDE32bFd4D4432E3996291aeFCe2f89"
}

image is itself a CID. Fetch both through the Flap gateway, https://flap.mypinata.cloud/ipfs/<CID>; see Flap IPFS Gateway.

Migration destination after the fact

Once status is 4 (DEX), pool from getTokenV8Safe is the pool for V2 / V3 migrators. For the CL migrators use the poolId from FlapTokenCLPoolCreated.

3. Extension encoding

A launch carries optional features in two fields of its launch parameters: bytes32 extensionID and bytes extensionData. An indexer reads them back from TokenExtensionEnabled (or extensionID in getTokenV8Safe) to know which features a token was launched with.

Extension IDs

struct Extension {
    bytes32 extensionId;
    bytes extensionData;
}

struct QuoteCurveAuthV2 {
    uint256 price;      // signed USD reference price (18 decimals) the curve is derived from
    uint256 deadline;   // signature expiry (unix seconds)
    bytes signature;    // EIP-712 signature by a Flap curve-auth signer
}

Two forms

• Array form (recommended). extensionID = keccak256("flap.extensions.v1") and extensionData = abi.encode(Extension[]). Several extensions can be combined, for example an Agent ID gate together with a signed curve price. For each extension the first entry with its extensionId is used.
• Single form (legacy). extensionID is the extension's own ID and extensionData is its payload directly, so only one extension per launch.

extensionID == bytes32(0) means no extension.

// Array form: Agent ID gate
Extension[] memory exts = new Extension[](1);
exts[0] = Extension({extensionId: NFT_GATED_EXTENSION_ID, extensionData: abi.encode(nft)});
params.extensionID = EXTENSION_ARRAY_ID;
params.extensionData = abi.encode(exts);

// Single form: the same gate
params.extensionID = NFT_GATED_EXTENSION_ID;
params.extensionData = abi.encode(nft);

Decoding an extension

To find one extension's payload (this is what the Portal does):

import { decodeAbiParameters, keccak256, toHex } from "viem";

const ARRAY_ID = keccak256(toHex("flap.extensions.v1"));

function findExtension(extensionID: `0x${string}`, extensionData: `0x${string}`, wantedId: `0x${string}`) {
  if (extensionID !== ARRAY_ID) {
    // single form: the whole payload belongs to extensionID
    return extensionID === wantedId ? extensionData : null;
  }
  const [exts] = decodeAbiParameters(
    [{ type: "tuple[]", components: [{ name: "extensionId", type: "bytes32" }, { name: "extensionData", type: "bytes" }] }],
    extensionData,
  );
  return exts.find((e) => e.extensionId === wantedId)?.extensionData ?? null;
}

TokenExtensionEnabled only carries extensionID, not the payload. For the Agent ID gate you do not need to decode anything: index FlapNFTGated or read nftGate(token). To read a launch's full extensionData, decode the launch transaction's input.