nilly docs
How nilly works, and everything you need to build on it: bots, terminals, wallets, aggregators, Telegram channels.
84532) with test ETH (free, see the faucet page). On Zero mainnet the same contracts and API run with $ZRO as the quote coin; addresses below update automatically.What is nilly
A launchpad on Zero. Anyone launches a coin in one transaction. Every coin trades on a bonding curve until it sells out, then graduates into its own pool, with liquidity locked forever. Creators earn on every trade, snipers pay, copies pay the original, and holders can take over a coin its creator abandoned.
Fees
Every number is fixed in the contract when a coin launches.
| What | Amount | Goes to |
|---|---|---|
| Trade fee | 1% of every buy and sell | split below |
| On the curve | 0.50% creator · 0.50% nilly | |
| After graduation | 0.60% creator · 0.30% nilly · 0.10% takeover reserve | creator 0.75% (nilly 0.15%) once the coin is 7 days past graduation with volume and holders |
| Creator tax | 0 to 5%, optional, fixed at launch | creator |
| Sniper fee | 98% → 24% → 2% → 0.5% → 0.1% extra in seconds 0-4, buys only | half creator, half nilly |
| Referral | 0.10% of trades you route | you, paid out of nilly's share |
| Copy royalty | half of a copy's creator trade fee, while the original keeps trading | the original coin's creator; the copy's creator keeps it all while the original is inactive |
| Launch fee | none on testnet | |
| Launch deposit | 0.0001 ETH on testnet, ~$5 on mainnet (shown on the launch screen) | back to the creator at graduation; nilly's if the coin goes a week without real trading before graduating |
| Graduation | 2% of what the curve raised | nilly; the pool opens at the last curve price |
All fees are paid in the quote coin (ETH on testnet, $ZRO on Zero), never in the token. Fees build up as balances and are claimed anytime with claim().
Life of a coin
- Launch. One transaction: name, ticker, image, links, optional creator tax, optional fee split across up to 10 wallets, optional first buy. 1,000,000,000 supply, no mint, no owner, no blacklist.
- Curve. 793.1M tokens sell on a constant-product curve (pump-style). Sells always work.
- Graduation. The buy that empties the curve graduates the coin in the same transaction. Overshoot is refunded. Everything raised (minus 2%) and the reserved tokens become a pool inside the coin's own contract. It has no LP tokens and no withdraw function, so the liquidity is locked forever.
- Pool. Constant product, 1% fee on the native side.
Protections
- Sniper fee on buys in the first 5 seconds. The creator and the wallets they name at launch are exempt.
- Copies. A launch whose ticker AND name both match (lowercased, letters and digits only) a coin that traded real volume in the last 7 days is marked a copy. A copy pays the original half its creator trade fee on every trade made while the original still has real volume in its last 7 days (
isAlive()); if the original goes quiet the copy keeps its whole fee, and the royalty resumes when the original trades again. Same ticker with a different name is a separate coin and pays nothing. SeecopyKey(symbol, name)andoriginalOf(key)on the factory. To be sure a launch comes out the way you saw it, uselaunchExpect(params, expectCopyOf): it reverts if someone launched the same name and ticker just before you. - Launch deposit refunded at graduation. Spam pays, real coins launch free.
- Dust trades under 0.000001 are rejected.
Takeovers
If a graduated coin's fee side stops claiming for 14 days, or the creator sells over 90% of their launch buy, anyone can post a bond (bondFor(market) on the takeover contract, capped per coin) and propose a new fee wallet. Holders vote for 72 hours. A vote counts the lowest of three balances: one day before the proposal, one second before it, and at the moment of voting, so buying in late or moving a bag between wallets adds nothing. A proposal passes with more yes than no votes and yes ≥ 20% of circulating supply, then waits 48 hours. If the creator comes back in that window, it doesn't execute. The winner receives the coin's takeover reserve.
Who controls what
A launched coin keeps the terms it launched with: nobody, nilly included, can change its fees, curve, supply or liquidity afterwards. nilly's settings (launch fee, deposit, curve size, activity bars, treasury address) only apply to coins launched later, each has a hard limit in the contract, and every change goes through a timelock contract that owns the factory. The fee percentages themselves are constants with no setter. On this testnet the timelock delay is zero so things can be tuned quickly; on mainnet it is a forced wait behind a multisig.
Testnet points
The app counts points per wallet from on-chain testnet activity: launching, trading on different days and coins, graduating a coin, claiming fees, voting in takeovers, referring traders. The list and the leaderboard are on the points page. Points give early access when nilly goes to mainnet, and decide whitelist priority for the nilly NFT (1:1 pieces). They are not a token, no airdrop or payout is promised, and the rules can change while the testnet runs.
Contracts
| loading… |
ABIs: /abis.json. Each coin has two contracts: the token (ERC-20) and its market (curve + pool). token.market() gives the market; the router accepts the token address.
Router
One entry point for every coin, curve or pool. Pass your own address as referrer to earn 0.10%.
getAmountOutBuy(address token, uint256 nativeIn, address to) view returns (uint256 tokensOut)
getAmountOutSell(address token, uint256 tokensIn) view returns (uint256 nativeOut)
poolInfo(address token) view returns (address market, bool graduated, uint256 nativeReserve, uint256 tokenReserve)
swapExactNativeForTokens(address token, uint256 minOut, address to, address referrer, uint256 deadline) payable
swapExactTokensForNative(address token, uint256 tokensIn, uint256 minOut, address to, address referrer, uint256 deadline)
// approve the router for tokensIn first
Quotes include all fees, including the sniper fee for to in a coin's first 5 seconds. A buy that would overshoot graduation is refunded to the caller.
Events
Every market also looks like a Uniswap V2 pair to indexers: token0(), token1() (the coin and wrapped native), getReserves(), and V2 Swap + Sync on every trade. On the curve, reserves are the virtual reserves (they set the price); after graduation they are the real pool.
// factory
Launched(address indexed market, address indexed token, address indexed creator, string name, string symbol, string meta, address copyOf, uint16 creatorTaxBps)
PairCreated(address indexed token0, address indexed token1, address pair, uint256) // V2-style, pair = market
// market
Trade(address indexed trader, address indexed to, bool isBuy, uint256 quoteGross, uint256 tokens, uint256 fee, bool pool, address referrer)
Swap(address indexed sender, uint256 amount0In, uint256 amount1In, uint256 amount0Out, uint256 amount1Out, address indexed to)
Sync(uint112 reserve0, uint112 reserve1)
Graduated(uint256 quote, uint256 tokens)
Claimed(address indexed who, uint256 amount)
DepositRefunded(address indexed creator, uint256 amount)
meta is JSON: {"image","desc","x","tg","web"}.
Referral
Any address passed as referrer (router, market.buy, market.sell, or the SDK option) earns 0.10% of that trade, paid out of nilly's share. The trader and creator pay nothing extra. Earnings accrue per coin; claim with market.claim() or sdk.claim(wallet, market). Self-referral is ignored.
REST API
Base: /v1. Read-only, JSON, CORS open. Addresses are lowercase. Amounts come as wei strings (…Wei) plus floats for convenience. Coin paths accept the token or the market address.
Totals: coins, graduated, launches24h, trades24h, volume24h, indexedBlock.
Chain id, addresses, wrapped native, ABIs link.
/v1/coins?sort=new|active|mcap|graduated&limit=50&offset=0&graduated=true|false&creator=0x…&q=pepetry ↗/v1/coins/{token}One coin, plus its copies.
{ "token":"0x…","market":"0x…","name":"…","symbol":"…","creator":"0x…","image":"…","description":"…",
"links":{"x":null,"telegram":null,"website":null},"createdAt":1794603793,"graduated":true,"graduatedAt":1794603794,
"progress":100,"price":5.5e-12,"marketCap":0.0055,"volume24h":0.002,"trades24h":6,"tradesTotal":6,"lastTradeAt":1794605525,
"creatorTaxBps":0,"copyOf":null,"takenOver":false,"holders":1,"quote":{"symbol":"ETH","decimals":18},"copies":[] }
/v1/coins/{token}/trades?limit=100&beforeBlock=/v1/coins/{token}/candles?tf=60|300|900|3600|14400|86400&limit=500OHLC in quote per token, volume in quote.
/v1/coins/{token}/holders?limit=50Labels: creator, curve, pool, burned.
/v1/quote?token=0x…&side=buy|sell&amount={wei}&to=0x…Exact on-chain quote through the router. Buy: tokens out for amount wei of native. Sell: native out for amount token wei.
Live stream
Server-Sent Events at /v1/stream (optionally ?token=0x…). Events: launch, trade, graduate. A trade arrives a few seconds after it's mined.
curl -N /v1/stream
event: trade
data: {"type":"trade","token":"0x…","symbol":"NILLY","side":"buy","trader":"0x…","quoteWei":"20000000000000",
"quote":0.00002,"tokensWei":"5028833805948523419730264","price":3.97e-12,"phase":"pool","tx":"0x…", …}
// browser
const es = new EventSource('/v1/stream');
es.addEventListener('launch', (e) => console.log('new coin', JSON.parse(e.data).coin));
es.addEventListener('trade', (e) => console.log('trade', JSON.parse(e.data)));
RPC
You can use any RPC of the chain (Base Sepolia on testnet). nilly also runs a read-only JSON-RPC proxy at POST /rpc, cached and backed by several upstreams with automatic fallback. It allows eth_call, eth_getBalance, eth_getLogs (address required, ≤200 blocks), receipts, blocks, gas and nonce reads. Batches up to 20. It never sends transactions: those go through your own wallet or RPC.
curl -s /rpc -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
SDK
@nilly/sdk wraps all of the above with viem. Your referrer address rides on every trade.
npm i @nilly/sdk viem // published at mainnet launch; testnet build: /sdk/nilly-sdk.tgz
import { createNilly } from '@nilly/sdk';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
const nilly = await createNilly({ referrer: '0xYOUR_ADDRESS' }); // earns 0.10% of every trade you route
// server side only: a dedicated hot wallet, key from the environment, never in a browser
const wallet = createWalletClient({ account: privateKeyToAccount(process.env.NILLY_KEY), chain: nilly.chain, transport: http('https://sepolia.base.org') });
// read
const coins = await nilly.coins({ sort: 'active', limit: 20 });
const out = await nilly.quoteBuy(coins[0].token, '0.01'); // tokens for 0.01 ETH/ZRO
// trade
await nilly.buy(wallet, coins[0].token, '0.01', { slippageBps: 500 });
await nilly.sell(wallet, coins[0].token, 1_000_000n * 10n ** 18n);
// launch (first buy in the same tx, fee split across wallets)
const { token, market } = await nilly.launch(wallet, {
name: 'Something', symbol: 'SMTH', meta: { image: '/img/.png', x: 'https://x.com/smth' }, // image: upload it first, see below
firstBuy: '0.005', split: [{ wallet: '0xA…', percent: 70 }, { wallet: '0xB…', percent: 30 }],
});
// fees
await nilly.claim(wallet, market);
// live
const stop = nilly.watch((e) => { if (e.type === 'launch') console.log('new', e.coin.symbol); });
Amounts: a bigint is wei; a number or string is whole units ('0.01' = 0.01 ETH/ZRO). Typescript types included.
Limits & keys
- API and RPC proxy: 240 requests per minute per IP. Need more for a bot or terminal? Ask @nillyfun for a free key, sent as
x-api-key. - Live stream: one connection per app is enough; it carries every event.
- The API is a convenience. Everything in it can be rebuilt from the contracts' events.