# GoDegen.fun — full agent reference > GoDegen.fun is a Base-native memecoin launchpad with permanent Uniswap v4 liquidity, on-chain creator and referrer fees, soulbound Uxp rewards, and ETH staking rewards. This document is the complete machine-readable reference for the GoDegen.fun website, product rules, public API, and security posture. It is maintained for AI agents, researchers, and integrators. The canonical short index is `/llms.txt`. ## Status GoDegen.fun is pre-launch software. The frontend, backend, and contracts are implemented and tested locally. A Base Sepolia smoke test, production deployment, and an external audit remain before mainnet. The website runs in local preview mode when no backend or contract addresses are configured. Do not treat preview data as live market data. Official site: `https://godegen.fun` Published contract addresses: `https://godegen.fun/contracts` Do not use an address that is not published on the Contracts page. ## Canonical pages - `/`: Home, live market overview, earnings vault, and token feed. - `/explore`: Full token explorer with search and filters. - `/trade`: Token selector and trading terminal entry point. - `/token/`: Canonical token page. Slug URLs redirect to the contract address and preserve query parameters. - `/launch`: Create a B20 token and open its Uniswap v4 launch pool. - `/earn`: Claim Uxp, stake Uxp, claim direct ETH, claim staking ETH, referrals, and leaderboard. - `/promo`: Five UTC promo slots with a 12-hour bidding window and a 12-hour live window. - `/docs`: Product, fee, Uxp, referral, promo, market data, architecture, and security documentation. - `/contracts`: Published contract address book and roles. - `/security`: Security model and responsible disclosure. ## Launch A creator chooses a starting market cap of $10,000, $20,000, or $50,000 and may add an optional dev buy in the same transaction. The full 1,000,000,000 token B20 supply enters a permanent single-sided Uniswap v4 position. There is no graduation, migration, or later liquidity unlock. - The ETH side of the pool is funded by buyers. The creator does not need to provide initial ETH liquidity. - The creator dev buy is atomic with launch, pays the normal 1.30% trading fee, and respects the 2% launch buy cap. The launch surcharge is waived for that atomic buy. - Launch protection is buy-only. A maximum 5% hook surcharge decays linearly to zero over at most 200 blocks or 45 seconds, whichever ends first. - A 2% cumulative per-transaction buy cap applies during the protected window. Sells are never capped or surcharged. - The first 100 unique wallets get one free launch. After that, the launch fee is 0.001 ETH. Paid launch fees are credited to the platform's claimable balance in the staking vault. - The launch form requires verification. A builder proves control of a public GitHub repository by adding a short single-use code to its README. The dashboard checks the default branch every 30 seconds for two minutes, then confirms automatically. The builder can remove the code afterwards; the verification stays with the wallet. One repository launches one coin, and a wallet can verify several repositories. Each wallet gets ten repository checks per UTC day. - Creator verification uses X. The creator pastes a short code into their X bio; the backend checks at 30 seconds and again at 60 seconds. Codes are single use and expire after 60 seconds (with a five second grace for the final check). The backend stores the X numeric id, so a later username change does not break the verification. One X profile can launch one coin, while a wallet can verify several profiles. Each wallet gets five checks per UTC day. ## Trading fees Every trade pays a fixed 1.30% fee. The split is enforced on-chain: | Recipient | Share | | - | - | | Platform | 0.30% | | Creator | 0.25% | | Referrer | 0.20% | | Stakers, with a referrer | 0.55% | | Stakers, without a referrer | 0.75% | Without a referrer, the 0.20% referrer share goes to stakers, so the total non-platform share remains 1.00%. Creator and referrer ETH is credited per trade and is claimable immediately. Staker ETH accrues per trade and has a separate claim path. `claimDirectRewards()` claims creator, referrer, and platform ETH; `claimStakingRewards()` claims staking ETH; `claimAllRewards()` claims both. External router and aggregator trades pay the same fee through the Uniswap v4 hook and are attributed to the transaction origin. ## Uxp Uxp is a soulbound reward token. Trading mints Uxp to an unclaimed balance. Claiming Uxp to a wallet and staking Uxp are separate actions. Mint rate by market cap: - Below $20,000: 1.00 Uxp per $1 of volume. - $20,000 to $74,999.99: 0.50 Uxp per $1. - $75,000 and above: 0.25 Uxp per $1. Sells earn 0.25 Uxp per $1 after a five-minute hold. Quick flips earn zero. A qualifying 50% net loss after two minutes triggers Rekt Insurance and doubles the sell reward to 0.50 Uxp per $1. Creators earn 25% of trader Uxp and referrers earn 20% of trader Uxp. A creator can also be a referrer. Self-referral is rejected. Minting is capped at 20,000,000 Uxp per wallet per UTC day. There is no global cap. The owner can lower the cap, with an immutable hard ceiling of 100,000,000 per wallet. Claimed and staked Uxp burn 10% per full UTC day after the wallet's first-ever claim. A trade worth at least $10 on a UTC day lowers that day's burn to 5%. Unclaimed Uxp is never burned. Later claims do not reset the burn clock. ## Staking rewards Staker rewards accrue continuously from every trade into the vault's reward-per-share accumulator. There is no fixed daily UTC payout. - A staker's accrued ETH is checkpointed into `claimableStakerEth` when they claim, stake, or otherwise interact with the vault. Creator and referrer ETH stays in `claimableDirectEth`. - The vault's view functions and the backend expose uncheckpointed rewards, so the UI can show live pending earnings. - Claims are pull-based. There is no keeper distribution, no batching delay, and no snapshot window for just-in-time staking. - The daily UTC checkpoint in the product refers to Uxp decay, not to ETH staking distributions. ## Referrals Referrals are optional and bind once. A referrer earns 0.20% ETH and 20% of trader Uxp on every referred trade. - Every wallet has a stable eight-character referral code. - Referral link format: `https://godegen.fun/?ref=YOURCODE`. - A wallet cannot refer itself. - The app validates every code or referrer address through the backend before binding. An unknown code, or an address that has no referral code, is rejected without a transaction. - Referral rewards settle in ETH and Uxp on every referred trade. - A referrer can open the downline list on `/earn` to see each referred wallet, its join time, and its all-time volume. The API returns the same rows newest first. ## Promo slots Five promo slots run on a fixed UTC clock. Bidding is 00:00-12:00 UTC. Every bid is on the tape instantly and is replaced by the next bid. The last bid at 12:00 UTC owns the slot for the 12:00-24:00 UTC live window. Every slot resets at 00:00 UTC. - Opening bid: $5 in USDC. - Minimum raise: $1. - A bid names the launched token. - Any wallet can promote any launched GoDegen token. The token is checked against the factory on-chain. - Bids are never refunded. Every payment goes directly to the treasury. - Each wallet pays only the difference between its new total and its previous total for the same UTC day and slot. - The contribution ledger resets at 00:00 UTC. - Promo entries carry a megaphone mark on the live tape. - The free daily top 10 by volume remains separate from paid promo slots. - Live tape priority is 33%, 25%, 17%, 15%, and 10% for slots 1-5. - There is no user-controlled timer, token-selection step, or buyout in the product flow. ## Market data The browser reads market data from the GoDegen backend, not directly from an RPC. The backend indexes platform events, writes durable history, keeps a hot cache, and streams live updates. - Chart intervals: 1m, 5m, 15m, 1h, 4h, 1d. The live overlay also carries 1s and 1m bars. - Price modes: USD, ETH, and market cap. - Pool scope: GoDegen launch pools. - Token identity: the B20 token address. - Canonical token URL: `/token/`. ## Public HTTP API Base URL: `https://godegen.fun/api/v1` Local backend default: `http://127.0.0.1:8080/api/v1` The read API is unauthenticated. Default HTTP rate limit is 180 requests per minute per IP. Errors use: ```json { "error": { "code": "TOKEN_NOT_FOUND", "message": "Token not found" } } ``` ### Read endpoints - `GET /config`: Chain ID, supply, initial market-cap options, fee split, Uxp zones, decay constants, and promo configuration. - `GET /stats`: Global volume, fees, Uxp supply, staked Uxp, participant fees, and staker metrics. - `GET /bootstrap`: Tokens, stats, leaderboard, recent trades, config, and server time in one payload. - `GET /tokens`: Paginated token list. Query: `sort=trending|new|gainers|sniper|marketcap`, `status=all|live`, `limit=1..100`, `offset=0..100000`, `q`. - `GET /tokens/{id}`: Token by contract address or slug. Returns holders. - `GET /tokens/{id}/trades`: Token trade tape. Query: `limit=1..200`, `before`, `beforeLogIndex`. - `GET /tokens/{id}/candles`: Candles. Query: `interval=1s|1m|5m|15m|1h|4h|1d`, `limit=1..2000`, `from`, `to`. - `GET /tokens/{id}/holders`: Holder ranking. Query: `limit=1..100`. - `GET /trades`: Recent global trades. Query: `limit=1..200`. - `GET /users/{address}`: User state, positions, referral summary, and balances. - `GET /users/{address}/trades`: A user's recent trades. Query: `limit=1..200`. - `GET /users/{address}/referrals`: Referred wallets with join time and all-time volume. Query: `limit=1..500`, `offset`. Newest first. - `GET /referrals/validate/{value}`: Validate a referral code or a registered referrer address before binding. Returns `valid`, the checksummed `address`, and the canonical `code`; unknown values return 404. - `GET /referrals/code/{address}`: Stable referral code for a wallet. - `GET /referrals/resolve/{code}`: Resolve a referral code to an address. - `GET /builders/{address}`: Builder verification status for a wallet, plus any open challenge and its expiry. - `GET /creators/{address}`: Creator verification status, open challenge, checks used today, and whether X is configured. - `GET /leaderboard`: Staker leaderboard. Query: `limit=1..100`. - `GET /promo`: Current five-slot promo state. Optional query: `address` for that wallet's per-slot contribution totals. - `GET /token-list`: Public Uniswap-format token list with logo and metadata extensions. - `GET /admin/token-assets`: Full confirmed asset export; requires `Authorization: Bearer `. - `GET /health` and `GET /ready`: Service health. ### Token logo assets Every launched token can have a normalized logo stored in two places: - Lighthouse IPFS is the canonical public logo for the token and external consumers. - Cloudflare R2 is a fast CDN mirror used by the GoDegen.fun platform and token list extensions. - The on-chain metadata image is `ipfs://`; R2 is exposed as `image_url` and `extensions.cdnLogoURI`. - The response includes `uploadId`, `metadataUri`, `logoCanonicalUrl`, `logoCdnUrl`, `logoCid`, and `expiresAt`. Upload a logo before the launch transaction: - `POST /token-assets` (multipart): `logo`, `wallet`, `timestamp`, `nonce`, `signature`, `name`, `ticker`, `description`, `socials`. - Accepted input: PNG, JPEG, or WebP only. ZIP, SVG, GIF, PDF, and arbitrary files are rejected by magic-byte validation. - Hard size limit: 1.1 MB. The backend normalizes the image, strips metadata, crops to a square 512px PNG, and applies lossless compression. It does not force lossy palette reduction or 256px downscaling. - Pass `metadataUri` to the factory as the token metadata URI. - After the launch confirms, call `POST /token-assets/confirm` with `uploadId`, `wallet`, `tokenAddress`, and `txHash`. The backend matches the indexed token metadata URI and creator wallet; a reconciliation timer retries if the indexer is behind. - Pending uploads expire after two hours and then wait through a 24-hour safety grace period. Before deleting anything, the backend checks whether a token exists for that metadata URI; a launched token's logo is never removed. - The public list at `/tokenlist.json` uses the canonical Lighthouse/IPFS URL as `logoURI` and includes `extensions.cdnLogoURI`, `extensions.ipfs`, `extensions.fallbackLogoURI`, `extensions.metadataURI`, and launchpad information. ### Signed write endpoints This endpoint requires an EIP-191 signature. The backend verifies the signer and does not hold private keys. Promo bids are not backend writes; they are USDC transactions sent directly to the promo contract. - `POST /tokens/{id}/socials`: Update creator social links. Body: `socials` (`x`, `telegram`, `website`), `timestamp`, `nonce`, `signature`. - `POST /builders/challenge`: Start builder verification. Body: `address`, `repo` (`owner/repo` or a github.com URL), `timestamp`, `nonce`, `signature`. Returns `id`, `code` (`GDX-XXXXX-XXXXX`), `expiresAt`, and `status`. - `POST /builders/verify`: Check the README for the code. Body: `address`, `id`, `proof` (the challenge signature). The frontend calls this every 30 seconds for two minutes. A missing code returns 422; an expired code returns 410. - `POST /builders/reserve`: Hold a verified repository for one launch. Body: `address`, `id`, `proof`. - `POST /builders/confirm`: Bind the repository to the launched token. Body: `address`, `id`, `tokenAddress`, `proof`. - `POST /builders/release`: Free a reservation when a launch fails. - `POST /creators/challenge`: Start X creator verification. Body: `address`, `handle` (any format), `timestamp`, `nonce`, `signature`. Returns `id`, `code`, `handle`, and `expiresAt`. - `POST /creators/verify`: Check the X bio. Body: `address`, `id`, `proof` (the signature from the challenge). Called at 30 seconds and 60 seconds. A missing code returns 422; an expired code returns 410. - `POST /creators/reserve`: Hold a verified profile for one launch. Body: `address`, `id`, `proof`. Reservations last 10 minutes. - `POST /creators/confirm`: Bind the profile to the launched token. Body: `address`, `id`, `tokenAddress`, `proof`. A profile can bind once. - `POST /creators/release`: Free a reservation when a launch fails. Body: `address`, `id`, `proof`. Signatures must be recent (five-minute window), use a single-use nonce, and match the authorized wallet. Existing social links can be changed once every 30 days; missing links can be added at any time. Builder codes are single use, tied to the wallet, and rate limited per wallet and per IP. The backend fetches the README from `raw.githubusercontent.com` on the default branch; the client never supplies the README body. A repository can only be verified by one wallet at a time. ### WebSocket Connect to `https://godegen.fun/ws` with Socket.io. - Server emits `bootstrap` on connect. - `subscribe` with `{ tokens: ["0x..."], user: "0x..." }` joins token and user rooms. - `unsubscribe` with `{ tokens: ["0x..."] }` leaves token rooms. - Events include `token:new`, `token:update`, `trade`, `candle`, `stats`, `user:update`, `user:snapshot`, and `leaderboard`. - Message rate limit is 20 subscription messages per 10 seconds per socket. The full OpenAPI 3.1 document is at `https://godegen.fun/openapi.json`. ## Contracts The contracts are Solidity on Base and use Uniswap v4. Published addresses and roles are listed at `https://godegen.fun/contracts`. The main components are: - `GoDegenFactory`: Creates launch pools and records token metadata. Enforces the free-launch limit and launch fee. - `GoDegen launch curve`: Per-token controller. Emits canonical `TradeExecuted` events. - `GoDegenInitHook`: Pool initialization, launch protection, and external fee routing. - `GoDegenStakingVault`: Uxp claims, staking, decay, creator and referrer ETH credit, and staker reward accounting. - `GoDegenPromoSlots`: Five UTC promo slots with a 12-hour bid window, a 12-hour live window, on-chain token lookup, direct treasury payments, and per-wallet contribution deltas. - Uniswap v4 `PoolManager`: Base PoolManager used by the hook and launch pools. Never send funds to an address that is not published on the Contracts page. ## Security GoDegen.fun is non-custodial. The backend has no private keys and never asks for a seed phrase. On-chain actions are signed by the user's wallet. - Creator social updates require wallet signatures. Promo bids are signed wallet transactions sent to the promo contract. - Backend queries use positional parameters; writes are idempotent and validated. - Production database connections require TLS and scoped credentials. - Rate limits apply to HTTP requests, WebSocket messages, nonces, and creator edits. Report vulnerabilities to `security@godegen.fun` or through the GitHub security advisory flow. Do not open a public issue or publish a proof of concept before a fix is available. Security page: `https://godegen.fun/security` ## Agent resources - `https://godegen.fun/llms.txt`: Concise index. - `https://godegen.fun/llms-full.txt`: This document. - `https://godegen.fun/agent.md`: Short entry point. - `https://godegen.fun/openapi.json`: OpenAPI 3.1. - `https://github.com/Fernarc/GoDegen/blob/main/AGENTS.md`: Repository guide for coding agents. - `https://godegen.fun/docs`: Human-readable documentation. - `https://godegen.fun/security`: Security model. ## Disclaimer GoDegen.fun is pre-launch software. Crypto assets are volatile and can lose value. Nothing on the site or in these files is financial advice. Preview data, demo balances, and local simulations are not live on-chain state.