Documentation

The Grimoire

Everything you need to hunt. Everything you need to survive. The protocol is immutable — these rules are law.

I. The Hunt

HUNT Protocol is an on-chain price prediction game where your NFT creature lives or dies based on your predictions.

Buy $HUNT tokens → receive a creature NFT automatically (every 300,000 HUNT = 1 creature).

Predict whether ETH/USD goes up or down in 3 minutes.

Win → your creature evolves toward Legendary.

Lose → your creature degrades.

Lose at Common → your creature burns forever. The hunter who beat you receives a Relic NFT trophy.

Everything is on-chain. The creature art is SVG generated by the contract. The Relic is permanent proof of a hunt.

II. $HUNT Token

$HUNT is the protocol token. Fixed supply of 1,000,000 HUNT. Deflationary.

How to get creatures:

Every 300,000 HUNT purchased → 1 Creature NFT minted automatically

500,000 HUNT → 1 Creature NFT (+ 200k spare)

1,000,000 HUNT → 3 Creature NFTs

$HUNT burns on every creature death:

Common creature burned → 0.1% of equivalent ETH value in HUNT burned

Uncommon creature burned → 0.3%

Rare creature burned → 0.5%

Epic creature burned → 1.0%

Legendary creature burned → 2.0%

The more creatures that die, the scarcer HUNT becomes. Hunt or be hunted.

III. Creature NFTs

Creatures are fully on-chain SVG NFTs. The art is generated by the smart contract — no IPFS, no servers, no dependencies. The creature lives on Ethereum forever.

Five ranks (ascending):

Common → gray, humble beginnings

Uncommon → green, gaining power

Rare → blue, seasoned hunter

Epic → purple, elite predator

Legendary → gold, apex of the food chain

State reflects your current round:

Flourishing → winning streak, creature glows

Aging → losing ground, colors fade

Critical → one loss from death, creature trembles

Dead → burned, a Relic was minted from your ashes

Creatures are transferable. You can sell your Legendary creature on OpenSea. The new owner inherits its rank and history.

IV. Price Prediction

Each round lasts exactly 3 minutes. The price feed is ETH/USD from Chainlink — trustless, on-chain, tamper-proof.

Solo mode (vs Protocol):

·Predict UP or DOWN

·Chainlink resolves at the 3-minute mark

·Win → creature rank goes up one level

·Lose → creature rank goes down one level

·Lose at Common → creature burned, Relic minted to protocol treasury

PvP mode (vs another Hunter):

·Challenge a specific hunter

·Both predict opposite directions (one says UP, other says DOWN)

·Chainlink resolves — one wins, one loses

·Loser's creature degrades, winner's evolves

·If loser was at Common → creature burned, winner receives the Relic NFT

The price used for resolution is the Chainlink ETH/USD price at the exact block when the round expires.

V. Relics

A Relic is a permanent on-chain skull NFT minted when a creature is burned.

The relic carries:

·The original creature's rank (determines relic rarity)

·The hunter who caused the burn

·The block number of the kill

·The hunter's total kill count at time of mint

Relic rarity matches the burned creature's rank:

Common creature burned → Common Relic (gray skull)

Uncommon creature burned → Uncommon Relic (green skull + crown)

Rare creature burned → Rare Relic (blue skull + ornate crown)

Epic creature burned → Epic Relic (purple skull + spikes)

Legendary creature burned → Legendary Relic (gold skull + full regalia, animated)

Relics are fully transferable. They are trophies. Trade them, collect them, flex them.

VI. Technical Stack

Smart Contracts (Solidity 0.8.26, Ethereum Mainnet):

·HUNTToken.sol — ERC-20, 1M supply, Solmate base

·CreatureNFT.sol — ERC-721, on-chain SVG, 5 ranks × 4 states

·RelicNFT.sol — ERC-721, on-chain SVG skull, 5 rarity tiers

·PredictionPool.sol — round management, solo + PvP modes

·PriceResolver.sol — Chainlink ETH/USD integration

Price Feed:

·Frontend: Binance WebSocket (wss://stream.binance.com) — real-time, free

·On-chain resolution: Chainlink ETH/USD feed (trustless)

Indexing:

·The Graph subgraph — indexes all on-chain events

·Leaderboard, history, stats — all from the subgraph

·No centralized database

Frontend:

·Next.js 15.5 + CSS Modules (no Tailwind)

·wagmi v2 + viem for wallet connection

·Deployed on Vercel

VII. Contract Addresses

Testnet (Sepolia):

HUNTToken: TBD — deploying soon

CreatureNFT: TBD

RelicNFT: TBD

PredictionPool: TBD

PriceResolver: TBD

Mainnet:

Deploying after Sepolia audit is complete.

All contracts will be verified on Etherscan.

No upgradability. No owner keys post-deploy. Protocol is immutable.

Chainlink ETH/USD feeds:

Sepolia: 0x694AA1769357215DE4FAC081bf1f309aDC325306

Mainnet: 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419