Developers

Integration Guide

Hyped is a bonding-curve token launchpad on HyperEVM. Coins launch with their full 1B supply on a constant-product curve traded in native HYPE; when the curve collects 85 HYPE, anyone can trigger a permissionless migration that seeds a DEX pool at the exact curve exit price. This document is for anyone building on top of Hyped.

Everything here is verifiable on-chain; the HTTP API is a convenience layer over the same events.

Networks

Contract addresses are published per network in the repository root and via the site (NEXT_PUBLIC_FACTORY_ADDRESS, NEXT_PUBLIC_CURVE_ADDRESS, NEXT_PUBLIC_ROUTER_ADDRESS). Three contracts matter to integrators:

• Factory — creates coins (launch), holds the default curve constants.
• Curve — all pre-migration trading, one contract for every coin.
• Router — optional convenience for post-migration swaps that preserves creator fee routing.

Coins themselves are vanilla ERC-20s (18 decimals, fixed 1B supply, no owner functions), deployed as EIP-1167 clones.

Coin lifecycle

launch() ──▶ bonding ──(85 HYPE collected)──▶ ready ──graduate()──▶ graduated

A protocol bot calls graduate() within seconds of ReadyToGraduate, but the call is permissionless — integrators may race it.

Curve constants (defaults, set at launch time per pool)

Invariant: (v0 + realHype) * virtualToken == k. Spot price = (v0 + realHype) / virtualToken (HYPE per token). Do not derive prices from tokensLeft; virtualToken is the pricing reserve.

On-chain: launching

function launch(
    string  name,          // ≤ 32 chars recommended
    string  symbol,        // ≤ 10 chars, any casing — stored verbatim
    string  metadataURI,   // ipfs://… (see Metadata)
    address feeRecipient   // address(0) ⇒ msg.sender
) external payable returns (address token);

• msg.value = creationFee + optional dev-buy. Everything above the creation fee is spent as a first buy in the same transaction — nothing can front it.
• The dev-buy is subject to the anti-snipe cap like any other buy (see below).
• Emits on the factory: Launched(address indexed token, address indexed creator, string name, string symbol, string metadataURI, address feeRecipient).
• Reverts: BadFee() (value below creation fee), CreationPaused().
• Gas: ≤ ~410k — fits HyperEVM small blocks; launches confirm at trade speed.

Metadata

metadataURI resolves (usually ipfs://<cid>) to:

{
  "name": "Molten Cat",
  "symbol": "MOLT",
  "description": "optional, ≤ 500 chars",
  "image": "ipfs://… or https://…",
  "website": "https://…",
  "twitter": "https://x.com/…",
  "telegram": "https://t.me/…"
}

All fields except name/symbol optional. Treat the document as untrusted input. Launch tooling may POST to /api/metadata (below) to have Hyped pin it, or pin its own.

On-chain: trading on the curve

function buy(address token, uint256 minTokensOut) external payable;
function buyFor(address token, address recipient, uint256 minTokensOut) external payable; // buy on behalf of another address
function sell(address token, uint256 tokenAmount, uint256 minHypeOut) external; // requires ERC-20 approve to the curve

• Fees come off the HYPE side on both directions: 1.5% total.
• Threshold clamp: a buy whose net HYPE would push realHype past the 85-HYPE threshold is clamped to the remaining room and the excess is refunded to the sender. Quote accordingly, or the minTokensOut you computed from the unclamped amount will revert with Slippage().
• Anti-snipe: during the first 100 blocks of a pool, a single buy cannot take more than 1% of supply (10M tokens ≈ 0.28 HYPE at open). Reverts EarlyBuyTooLarge(). Buys every block are still possible.
• The buy that reaches the threshold sets the pool ready, closes the curve, and emits ReadyToGraduate.
• Sells are never pausable (no code path exists); buys can be paused by the owner in emergencies (BuysPaused()).

Exact quote math (mirror of the contract)

For a buy of value wei with pool state (v0, realHype, V, T):

protocolFee = floor(value * 100 / 10000)          // floored separately
creatorFee  = floor(value *  50 / 10000)
net         = value - protocolFee - creatorFee
room        = T - realHype
if net > room:                                    // threshold clamp
    gross   = ceil(room * 10000 / 8500)           // re-derive gross from room
    net     = room
    refund  = value - gross                       // sent back to recipient
tokensOut   = V * net / (v0 + realHype + net)     // constant product, floor

For a sell of amount tokens: gross = (v0 + realHype) * amount / (V + amount), then the two fees (floored separately, as above) come off gross; the seller receives the remainder. The reference TypeScript implementation lives in web/lib/curve.ts (quoteBuy, quoteSell) and is kept byte-exact against the Solidity — port it rather than re-deriving.

Reading pool state

pools(address token) returns the tuple:

(uint128 virtualHype, uint128 realHype, uint128 virtualToken,
 uint128 tokensLeft, uint128 gradThreshold, uint128 maxEarlyBuy,
 uint64 startBlock, address creator, address feeRecipient,
 bool ready, bool graduated)

Curve progress = realHype / gradThreshold. Market cap (HYPE) = spot price × 1e9 supply.

On-chain: migration and after

• graduate(address token) — permissionless once ready. Creates/funds the DEX pool at the curve exit price and emits Graduated. Big-block caveat: pool creation exceeds HyperEVM's small-block gas limit; the calling address must have big blocks enabled on HyperCore or the tx will never land.
• After migration, swap through the pool directly, or through the Hyped router, which preserves the 1.5% fee split and live creator routing:

router.buy{value: …}(token, poolFee, minOut);
router.sell(token, poolFee, amountIn, minOut);

• curve.feeRecipientOf(token) always returns the current creator fee recipient (creators can redirect at any time; FeeRecipientChanged fires).
• Creator/protocol fees accrue pull-model: accrued(address) / claim().

Events (for indexers)

All amounts are wei (1e18). topic0 values:

Trade fields: (token, trader, isBuy, hypeAmount, tokenAmount, newReserveHype, newReserveToken). hypeAmount is net of fees in both directions: what actually entered the curve on a buy, what the seller actually received on a sell. On a buy, trader is the token recipient (for buyFor, the recipient — not the caller). Marginal price after the trade = newReserveHype / newReserveToken; the reserves include the virtual parts, so this division is the spot price directly. Dedupe on (txHash, logIndex).

HTTP API

Base URL: the Hyped site origin. JSON everywhere; all wei amounts are decimal strings (they exceed IEEE 754 — do not parseFloat them); timestamps are unix seconds. No authentication, CORS open, no websocket yet — poll politely (≥ 3s).

GET /api/tokens?status=&sort=&limit=

Board listing. status: all (default) | bonding | ready | graduated. sort: activity (default) | liquefaction | volume | recent. limit: 1–100, default 60.

{ "tokens": [ {
  "address": "0x…", "name": "Molten Cat", "symbol": "MOLT",
  "metadata_uri": "ipfs://…", "creator": "0x…", "status": "bonding",
  "reserve_hype": "58396453805548108600", "reserve_token": "…",
  "real_hype": "28396453805548108600", "volume_hype": "…",
  "trade_count": 11, "created_at": "1787690000"
} ] }

reserve_hype/reserve_token include the virtual parts: their ratio is the spot price. real_hype is actual HYPE collected (progress = real_hype / 85e18).

GET /api/token/{address}

One coin + its last 100 trades: { "token": {…row as above…}, "trades": [ { "trader", "is_buy", "hype_amount", "token_amount", "price_x96", "ts", "tx_hash" } ] }. price_x96 is the post-trade marginal price in Q96 (price = price_x96 / 2^96, HYPE per token wei). 404 if unknown.

GET /api/candles?token=&res=&limit=

OHLCV built from trades. res in seconds (60, 300, 3600, 86400…), default 300. limit ≤ 1000, default 200. Returns { "candles": [ { "time", "open", "high", "low", "close", "volume" } ] } — time ascending, prices as JS numbers (HYPE per token), volume in HYPE.

GET /api/feed

The 30 most recent trades across all coins, newest first: { "trades": [ { "token", "symbol", "is_buy", "hype_amount", "tx_hash", "log_index", "ts" } ] }.

POST /api/metadata

For launch tooling: pins a metadata document and returns the URI to pass to launch(). Body: the metadata JSON above (name + symbol required; fields are re-validated and re-normalized server-side). Response: { "uri": "ipfs://…", "cid": "…" }. Errors: 400 (malformed), 503 (pinning not configured).

Common flows

• Launching programmatically: POST /api/metadata → factory.launch{value: creationFee + devBuy}(…) → read the token address from the Launched topic 1 → further buys from any wallet via curve.buy, or curve.buyFor(token, recipient, minOut) to buy on behalf of another address. Mind the anti-snipe cap for the first 100 blocks.
• Quoting and routing trades: discover coins via Launched events or GET /api/tokens; quote with the exact math above (or port web/lib/curve.ts); route bonding coins to the curve and graduated coins to the pool/router; candles from /api/candles or from Trade events.
• Indexing the protocol: index the five events; a coin's full history is reconstructible from Launched + Trade + Graduated alone.

Versioning & contact

Breaking changes to the HTTP API will be announced in the repository changelog; on-chain interfaces are immutable once deployed (non-upgradeable contracts). Open an issue in the repository for integration support.