# Hevium Protocol Specification & Autonomous MCP Reference (llms-full.txt)

> Domain: https://hevium.xyz | Docs: https://docs.hevium.xyz
> Networks: Elysium (99901), Base (8453), Robinhood Chain (4663), Solana (Mainnet-Beta)
> Protocol Treasury: `0x3eF368806fa91e16C2775A155a937C0Da81F0Bc2`
> Twitter / X: https://x.com/heviumpad | Package: `@hevium/mcp-server`

---

## 1. Multi-Chain Architecture Overview

Hevium is a non-custodial multi-chain fair-launch bonding curve protocol and trading terminal:
- **Total Supply**: `1,000,000,000 * 1e18` fixed (no owner mint).
- **Curve Allocation**: `800,000,000` tokens (`80%`) sold along the virtual constant-product curve.
- **DEX Liquidity Seed**: `200,000,000` tokens (`20%`) paired atomically on graduation.
- **Trading Fee**: `1.0%` (`100 bps`), split `20%` (`0.20%`) instant atomic affiliate payout to referrer via `HeviumV2FeeEscrow` and `80%` (`0.80%`) to Treasury & `HeviumV2BuybackVault`.
- **Anti-Snipe Guard**: Decaying launch snipe tax + strict slippage/deadline enforcement + `ReentrancyGuard`.

---

## 2. Verified On-Chain Contract Registry

### 2.1 Elysium Mainnet (Chain ID 99901)
- RPC: `https://rpc.elysium.kinetiq.xyz` | Explorer: `https://elysium.kinetiq.xyz/explorer`
- `HeviumV2Factory`: `0x5f8dDBA84D3E7f4cdcF43c8841722Ae75e66DEA4`
- `HeviumSwapRouter`: `0xaEEE06f17f6B54ED7B9fcE7540D5D1bDf7C93b91`
- `HeviumUniswapV3Adapter`: `0xc1fBC3414Eb5a48edeABD265A67CeB47eC876285`
- `HeviumV2Deployer`: `0x3ec1ca12e759Ff1dC253c4D04b7c911e0ad8B337`
- `HeviumV2FeeEscrow`: `0x650E9355344aAC682f023881EE962e5A7c940d13`
- `HeviumV2BuybackVault`: `0xE33160CF9Ea46AFa5901a8d4F0f1f91e76eaaC06`
- `WHYPE`: `0xbA876237B0F021A6c6D852d6c26E107997cC5E81` | `USDC`: `0xb47c4C8F73F009CC0C0d3f92B388d13E293F0B65`
- Curve Targets: `500 HYPE` (phantom `100 HYPE`), `35,000 USDC` (phantom `7,000 USDC`).

### 2.2 Base Mainnet (Chain ID 8453) — Verified on BaseScan
- RPC: `https://mainnet.base.org` | Explorer: `https://basescan.org`
- `HeviumV2Factory`: `0x70Cc494D04a9245b463Fe6fc60E76Fb60ff98B95`
- `HeviumSwapRouter`: `0xf6C19c5B5E46d5958a4C1462C2b69103fA1aD85F`
- `HeviumV2Deployer`: `0x6fbd5C0C5aA1cBc15af882D7fa3D0454F39CbAA0`
- `HeviumV2FeeEscrow`: `0x87c78b44f3C2AdD6b7244fC60519B337c3C3F95C`
- `HeviumV2BuybackVault`: `0x9D7e15ADD8C8e071B372afc1eB0Bd1d6d10171a7`
- `Uniswap V2 Router02`: `0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24`
- `WETH`: `0x4200000000000000000000000000000000000006` | `USDC`: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Curve Targets: `3.0 ETH / WETH` (phantom `1.0`), `8,000 USDC` (phantom `2,000`), `10,000 USD+` (6 dec), plus B20 (`8` dec: `AAPLc`, `NVDAc`, `METAc`, `GOOGLc`, `MSFTc`, `AMZNc`, `SPCXc`) and ST0x (`18` dec: `wtCOIN`, `wtSPYM`, `wtMCD`).
- Graduation Fees (3 ETH curve): `0.1125 ETH` platform + `0.075 ETH` creator reward.

### 2.3 Robinhood Chain Mainnet (Chain ID 4663) — Verified on Robinhood Etherscan
- RPC: `https://rpc.mainnet.chain.robinhood.com` | Explorer: `https://robin.etherscan.io`
- `HeviumV2Factory`: `0x3b4856f587080d551C805806CcaC3C3697458B49`
- `HeviumSwapRouter`: `0x87c78b44f3C2AdD6b7244fC60519B337c3C3F95C`
- `HeviumV2Deployer`: `0x70Cc494D04a9245b463Fe6fc60E76Fb60ff98B95`
- `HeviumV2FeeEscrow`: `0x9D7e15ADD8C8e071B372afc1eB0Bd1d6d10171a7`
- `HeviumV2BuybackVault`: `0x6fbd5C0C5aA1cBc15af882D7fa3D0454F39CbAA0`
- `Robinhood DEX Router`: `0x89e5DB8B5aA49aA85AC63f691524311AEB649eba`
- `WETH`: `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` | `USDG`: `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`
- Curve Target: `8.0 ETH` (phantom `2.0 ETH`), `20,000 USDG`, plus tokenized equities (`NVDA`, `TSLA`, `AAPL`, `SPY`, `AMZN`, `MSFT`, `PLTR`, `AMD`, `CRCL`, `USO`, `MCD`, `DIS`).

### 2.4 Solana Mainnet-Beta
- RPC: `https://api.mainnet-beta.solana.com` | Explorer: `https://solscan.io`
- Meteora DBC: `dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN` | DLMM: `LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo` | Jupiter v6: `JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4`

---

## 3. Virtual Bonding Curve Math (Dynamic Calibration)

In `HeviumV2BondingCurve`, virtual token offset `x_v` is computed dynamically per curve from `CURVE_SUPPLY = 800,000,000`:
$$x_v = \frac{(y_v + Y_{\text{grad}}) \cdot 800,000,000}{Y_{\text{grad}}}$$
$$k = (800,000,000 + x_v) \cdot y_v = x_v \cdot (Y_{\text{grad}} + y_v)$$
This guarantees 100% of `800,000,000` curve tokens are exhausted at exact quote collection `Y_grad` across 6-decimal, 8-decimal, and 18-decimal pairs.

---

## 4. MCP Server Setup

```json
{
  "mcpServers": {
    "hevium": {
      "command": "npx",
      "args": ["-y", "@hevium/mcp-server"],
      "env": {
        "HEVIUM_AGENT_PRIVATE_KEY": "0xYOUR_KEY",
        "ROBINHOOD_RPC_URL": "https://rpc.mainnet.chain.robinhood.com",
        "HEVIUM_MAX_TRADE_ETH": "0.05",
        "HEVIUM_DAILY_BUDGET_ETH": "0.5"
      }
    }
  }
}
```