Docs

Integration guide

For wallets, terminals, bots and aggregators: how to list, price and trade every token launched on Evermor. Each token trades in its own Uniswap v4 pool on the official PoolManager from its first block. No bonding curve, no migration.

New to Evermor? Start with how Evermor works.

Overview

A launch creates an ERC-20 with a fixed supply of 1,000,000,000 (18 decimals) and puts the whole supply into a locked liquidity position in a v4 pool. The pool pairs the token with its quote asset: native HYPE, USDC, KNTQ, a tokenized stock, a basket, or one of the larger Elysium tokens. Every pool uses the same hook, EvermorHook, which runs the token's rules on each swap and charges its fees.

  • Fees on every trade: a 1% protocol fee, the creator's fee (0 to 10%) and a base LP fee. Rules can take a further share within fixed caps: 20% at most on buys and 15% on sells, creator fee included.
  • Native HYPE pools use address(0) as the quote currency, not WHYPE.
  • Some tokens change pair. A creator can turn on a pair wheel that moves the token to another quote asset on a schedule. The pool id changes when it spins: see Find the pool.

Network

FieldValue
Chain id99901
RPC (Kinetiq, official)https://rpc.elysium.kinetiq.xyz
RPC (Evermor relay)https://www.evermor.trade/api/rpc
Native gas tokenHYPE
Block numbers. Inside contracts, block.number on Elysium returns HyperEVM's block number (about 1 per second), not the Elysium block number that eth_getLogs takes. Work from timestamps, and never compare a block number stored in a contract with eth_blockNumber.

Contracts

ContractAddressUse
Launchpad0x1B8748756b2F4F56DcaDCd5366E90b8c59B4609ELaunched events, allTokens, tokenCount
EvermorHook0xc5A2AD712EBBcA9f416Bd9091731A7578c2a68ccPool keys, PoolTrade events, token info
HookRouter0x530B6E7600D24ebe984420d6359D8cf53b29E20DSimple buy and sell, recommended
HookLens0xbD51708Fc7169B7d8f48Ff8ad50a09f1b31326F0All of a token's data in one call
PoolManager (v4)0xE2e105d3F7209A9DA11f83cCf3E7398a753823F1Official Uniswap v4
Universal Router0x1B341FDD55d56F8E08409A2C25DDFad93Eb03C1aStandard v4 swaps
V4 Quoter0x379F556c5a748BD7Cc9baF0F7A344094Ac1814f5Quotes
StateView0x27eD73aE0652fdCf71d6793412A7525f32bE9dfEgetSlot0, liquidity
Permit20x000000000022D473030F116dDEE9F6B43aC78BA3Approvals for the Universal Router
BasketZap0x0cA85F721DC78f559996C1ffad640737d22C7A9DBuy or sell basket-paired tokens with HYPE

Index from Elysium block 1703408. The official token, $EVERMOR, is 0x7f4f3b9770648262fe5133B9CB8A2155173be0d4 (HYPE pair).

Index new launches

Listen to the launchpad. Each launch emits one event, and the pool can be traded in the same block.

// Launchpad
event Launched(
  address indexed token,
  address indexed creator,
  address indexed quote,      // address(0) = native HYPE
  string  name,
  string  symbol,
  string  metadataURI,        // ipfs://… JSON
  bytes32 poolId,
  uint160 sqrtPriceX96        // opening price
);

To backfill, read tokenCount() and allTokens(i), or page through HookLens.page(offset, limit) (newest first). Each TokenView carries the name, symbol, metadata, creator, quote asset, pool id, price (priceE36, quote wei per token wei × 1e36), market cap (mcapUsd, 1e18), the fees and the active rules.

Metadata

metadataURI points to a JSON file pinned on IPFS:

{ "name": "…", "symbol": "…", "description": "…",
  "image": "ipfs://…", "website": "…", "x": "…", "telegram": "…" }

Find the pool

Read the pool key from the hook. Don't build it from the launch event: the key changes if the pair wheel spins.

// EvermorHook
function poolKeyOf(address token) view returns (PoolKey);
// → { currency0, currency1 (sorted; address(0) for HYPE),
//     fee: 0x800000 (dynamic), tickSpacing: 60, hooks: EvermorHook }

function quoteOf(address token)        view returns (address);
function creatorOf(address token)      view returns (address);
function creatorFeeBps(address token)  view returns (uint16);
function launchInfo(address token)     view returns (uint64 launchBlock, uint64 launchTime);
function modulesOf(address token)      view returns (address[]);   // active rules
function spotPriceE36(address token)   view returns (uint256);
function mcapUsd(address token)        view returns (uint256);

A wheel spin emits Spun(token, from, to, amountIn, amountOut) on the launchpad. When you see one, read poolKeyOf again. Tokens with a fixed pair never spin: HookLens.getToken(token).wheel is empty for them.

Trade

Option A: HookRouter (recommended)

The simplest path. It finds the pool, reports the real trader to the hook and takes a referrer.

// HookRouter
function buy(address token, uint256 amountIn, uint256 minOut,
             address referrer, uint256 deadline) payable returns (uint256 out);
function sell(address token, uint256 amountIn, uint256 minOut,
              uint256 deadline) returns (uint256 out);
  • Buy with HYPE: send amountIn as msg.value. With an ERC-20 quote, approve the router for amountIn and send no value.
  • Sell: no approval needed. Evermor tokens give this router an implicit allowance.
  • Referrer: pass your fee wallet. On tokens with the Referral rule, part of the creator fee on buys goes to the referrer, and the buyer pays the same either way. A buyer's first referrer is kept for good. Pass address(0) if you don't need it.
  • Trades through this router count as verified. Some rules only reward verified trades (King of the Hill, Buyer rewards, Hot potato).

Option B: any Uniswap v4 router

These are standard v4 pools: the Universal Router (command V4_SWAP) or your own router works with the key from poolKeyOf and empty hookData. The hook then treats tx.origin as the trader. Fees and rules apply the same way.

Quotes

Use the V4 Quoter (quoteExactInputSingle) with the same pool key. The quoter runs the hook, so its amount already includes Evermor's fees. A quote that reverts means a rule refused the trade: see below.

Prefer exact input. The hook checks that a fill is complete and reverts with PartialFill() when a price limit stops a swap halfway.

Read trades

Every swap in an Evermor pool emits one event on the hook, whatever router sent it. It is the easiest source for charts, trade lists and volume.

// EvermorHook
event PoolTrade(
  address indexed token,
  address indexed trader,      // router-reported buyer, or tx.origin
  bool    isBuy,
  uint256 quoteAmount,         // quote side, in quote wei (fees included on buys)
  uint256 tokenAmount,         // token side, 18 decimals
  uint256 quoteCut,            // what Evermor fees and rules took, in quote wei
  uint160 sqrtPriceX96         // pool price after the trade
);

Volume in USD is quoteAmount times the quote asset's price. The quote asset is not always HYPE: read it with quoteOf(token) and mind its decimals.

Log ranges. Some public Elysium RPCs refuse eth_getLogs over 1,000 blocks (about 2.5 minutes of chain). The official Kinetiq RPC takes much larger ranges.

Rules that can refuse a trade

Creators choose rules for their token. Most only change fees. A few can make a swap revert, mostly in the first minutes after launch: show the reason to the user rather than a generic failure.

RuleWhat it does
Anti-snipeCaps buys per block and taxes bots right after launch
Whale guardNo single buy above a set size, early on
Max per walletNo wallet holds more than a share of supply
Holder gateFor a window after launch, only holders of a chosen token or NFT can buy
CooldownA wallet can't sell for a set time after its last buy (one hour at most)
Market hoursBuys follow NYSE hours
Custom hooksCreator-drawn taxes and guards (FlowRules). Guards (pause, holders only, min or max size) end within 2 hours of launch
Custom hooks v2FlowRulesV2: the same, plus conditions on the market cap or the trade count, and impact fees that raise the pool fee on a swap that moves the price 1% or more

Quote through the v4 quoter, not from the pool key: the hook overrides the pool fee on each swap, and an impact fee depends on the swap's size. A guard with a condition may start or stop between two quotes, so treat a revert at execution like any slippage failure.

To read a custom hook: rulesOf(token) on FlowRules returns (taxes, guards); on FlowRulesV2 it returns (taxes, guards, fees), each with cond and condValue. stateOf(token) gives the highest market cap seen and the trade count, mcapDelayed(token) the market cap the conditions judge on, and authorOf / authorShareOf the hook's author. Royalties emit AuthorPaid(token, author, currency, amount).

v4 wraps hook reverts as WrappedError(address,bytes4,bytes,bytes); the inner selector names the rule's error. modulesOf(token) lists the rules each token uses.

HTTP API

The public API serves every token, its rules, trades and holders, the KNTQ furnace and platform stats as JSON, with no key, open to any origin, cached for a few seconds at the edge. Base URL https://www.evermor.trade/api/v1. It is best effort with no SLA: in production, read the chain and use it to bootstrap or cross-check.

Endpoints, parameters and examples: the public API guide.

Checklist

  1. 1

    Index Launched from the launchpad, and backfill with HookLens.page.

  2. 2

    Read name, symbol and logo from metadataURI.

  3. 3

    Get the pool from poolKeyOf(token), and read it again after each Spun event.

  4. 4

    Price from StateView.getSlot0(poolId) or the last PoolTrade.sqrtPriceX96, in the quote asset's decimals.

  5. 5

    Quote with the V4 Quoter, and trade through HookRouter with your wallet as referrer.

  6. 6

    Build volume and trade history from PoolTrade events on the hook.

  7. 7

    Show rule reverts to the user in plain words.

Questions or a listing to coordinate: reach the team on X at @TradeEvermor.