# Hyped — 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

| | Chain ID | RPC |
|---|---|---|
| HyperEVM mainnet | 999 | `https://rpc.hyperliquid.xyz/evm` |
| HyperEVM testnet | 998 | `https://rpc.hyperliquid-testnet.xyz/evm` |

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
```

| Status | Meaning | Tradable via |
|---|---|---|
| `bonding` | on the curve | Curve `buy` / `sell` |
| `ready` | threshold hit, curve closed, awaiting migration | nothing (call `graduate`) |
| `graduated` | liquidity lives in the DEX pool | Router or the pool directly |

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)

| | Value |
|---|---|
| Supply | 1,000,000,000 × 1e18 |
| Virtual HYPE reserve `v0` | 30 × 1e18 |
| Virtual token reserve `V` | 1,082,500,000 × 1e18 |
| Graduation threshold `T` | 85 × 1e18 (real HYPE) |
| Sold on the curve | ~80.0% of supply |
| Price multiple start→graduation | ×14.69 |
| Trading fee | 1.5% of HYPE (1.0% protocol — a compile-time constant — + 0.5% creator) |
| Graduation fee | 3.596997690531177829 HYPE, taken from the raise |
| Creation fee | `factory.creationFee()` (currently 0) |

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

```solidity
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:

```json
{
  "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

```solidity
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:

```solidity
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:

| Event (emitter) | Signature | topic0 |
|---|---|---|
| Launched (factory) | `Launched(address,address,string,string,string,address)` | `0xc1ff4cffabb0e468e1de70cc55367f687a8cc1252d1af96bae98230e34c7f780` |
| Trade (curve) | `Trade(address,address,bool,uint256,uint256,uint256,uint256)` | `0x9adcf0ad0cda63c4d50f26a48925cf6405df27d422a39c456b5f03f661c82982` |
| ReadyToGraduate (curve) | `ReadyToGraduate(address,uint256)` | `0xc25f1a785bd9ff9fb6c9be30dc4c46007f5c0e93d818676e3ae83d0e4b6f7352` |
| Graduated (curve) | `Graduated(address,uint256,uint256,uint256)` | `0xcb64f2436060c9575db20c5dcf9cdc11657017ee5b0301949f531b3dd7da6b19` |
| FeeRecipientChanged (curve) | `FeeRecipientChanged(address,address)` | `0x0bc21fe5c3ab742ff1d15b5c4477ffbacf1167e618228078fa625edebe7f331d` |

`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.

```json
{ "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.