docs

nilly docs

How nilly works, and everything you need to build on it: bots, terminals, wallets, aggregators, Telegram channels.

Testnet. Everything here runs on Base Sepolia (chain id 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.

WhatAmountGoes to
Trade fee1% of every buy and sellsplit below
On the curve0.50% creator · 0.50% nilly
After graduation0.60% creator · 0.30% nilly · 0.10% takeover reservecreator 0.75% (nilly 0.15%) once the coin is 7 days past graduation with volume and holders
Creator tax0 to 5%, optional, fixed at launchcreator
Sniper fee98% → 24% → 2% → 0.5% → 0.1% extra in seconds 0-4, buys onlyhalf creator, half nilly
Referral0.10% of trades you routeyou, paid out of nilly's share
Copy royaltyhalf of a copy's creator trade fee, while the original keeps tradingthe original coin's creator; the copy's creator keeps it all while the original is inactive
Launch feenone on testnet
Launch deposit0.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
Graduation2% of what the curve raisednilly; 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

Protections

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.

get/v1/statstry ↗

Totals: coins, graduated, launches24h, trades24h, volume24h, indexedBlock.

get/v1/contractstry ↗

Chain id, addresses, wrapped native, ABIs link.

get/v1/coins?sort=new|active|mcap|graduated&limit=50&offset=0&graduated=true|false&creator=0x…&q=pepetry ↗
get/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":[] }
get/v1/coins/{token}/trades?limit=100&beforeBlock=
get/v1/coins/{token}/candles?tf=60|300|900|3600|14400|86400&limit=500

OHLC in quote per token, volume in quote.

get/v1/coins/{token}/holders?limit=50

Labels: creator, curve, pool, burned.

get/v1/trades/latest?limit=50try ↗
get/v1/launches/latest?limit=50try ↗
get/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