> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/overview.md). # Overview Kumbaya is a real-time DEX and social launchpad on **MegaETH**. This page is the architecture map for integrators - what's deployed on-chain, what's hosted by Kumbaya, what's open-source, and how the pieces fit together. ## The shape of the stack ``` ┌──────────────────────────────────────────────────────────────────────┐ │ YOUR INTEGRATION │ │ (frontend, bot, agent, aggregator, dashboard) │ └──────────────┬───────────────────────────────────────┬───────────────┘ │ │ ▼ ▼ ┌──────────────────────────────┐ ┌─────────────────────────────────┐ │ @kumbaya_xyz SDKs │ │ Hosted services (kumbaya.xyz) │ │ • sdk-core │ │ ─────────────────────────────── │ │ • v3-sdk │ │ • Exchange API │ │ • router-sdk │ │ exchange.kumbaya.xyz │ │ • universal-router-sdk │ │ quotes, pools, stats │ │ • smart-order-router │ │ • Client API │ └──────────────┬───────────────┘ │ clients.kumbaya.xyz │ │ │ auth (SIWE/Privy), social, │ │ │ launch metadata, claims │ │ │ • Search Service │ │ │ search.kumbaya.xyz │ │ │ tokens, pools, typeahead │ │ │ • Hasura GraphQL (read-only) │ │ │ ql.kumbaya.xyz │ │ │ indexed on-chain data │ │ └────────────────┬────────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ On-chain (MegaETH 4326) │ │ • Uniswap V3 fork (factory, pools, router, quoter, position mgr) │ │ • Kumbaya launchpad (FireLaunch, Graduator, Token, Stream, │ │ Vault, Registry) │ │ • Permit2, WETH9, TickLens │ └──────────────────────────────────────────────────────────────────────┘ ``` ## What's open and what's gated | Layer | What it is | Access | | --------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **On-chain contracts** | V3 fork + Kumbaya launchpad on MegaETH | Permissionless. Call directly via RPC. | | **SDKs** (`@kumbaya_xyz/*`) | npm packages for typed contract interaction | Permissionless. `npm install`. | | [**Agent Kit**](/developers/building-agents/agent-kit.md) | MCP servers + skill pack that expose the platform as LLM tools | Permissionless. `npx @kumbaya_xyz/onchain-mcp` / `kumbaya-mcp`. | | **Exchange API** | Hosted REST at `exchange.kumbaya.xyz` | Mix: most read endpoints public; partner quote endpoints require an API key. See [Authentication](/developers/apis/exchange-api/authentication.md). | | **Client API** | Hosted REST at `clients.kumbaya.xyz` | User accounts, social, launches, claims. JWT-based. | | **Search Service** | Hosted REST at `search.kumbaya.xyz` | Public token + pool search. No auth. | | **Hasura GraphQL** | Public read-only indexer at `ql.kumbaya.xyz` | On-chain data: pools, swaps, tokens, positions, time-series. No auth. | | **Frontend** ([kumbaya.xyz](https://kumbaya.xyz)) | The Kumbaya web app | Anyone. End users only - not a public API. | ## Two protocols, one DEX Kumbaya runs two distinct protocols on a shared V3 fork: ### 1. The DEX - a Uniswap V3 fork Pools, positions, quoting, swapping, fee tiers - all standard V3. The single material change is a wider protocol-fee range *at the contract level* (up to 50%, vs. upstream's 25%), Kumbaya's own deployments, and the pool init code hash. Currently-set protocol-fee values sit within Uniswap's standard range (see [Differences from Uniswap V3](/developers/dex-integration/differences-from-uniswap.md)). **Reference:** [**DEX Integration**](/developers/dex-integration/overview.md), plus Uniswap's [V3 protocol docs](https://developers.uniswap.org/docs/protocols/v3/overview). Don't use V2 or V4 docs. ### 2. The Kumbaya launchpad - bonding-curve launches A six-contract system that lets anyone launch a new token. The token starts trading on a V3 pool seeded with overlapping concentrated positions that simulate a bonding curve. When the price reaches a configured graduation tick, the seed positions consolidate into a single full-range NFT and the pool becomes an ordinary V3 pool. The contracts are prefixed `Fire*` (`FireLaunch`, `FireGraduator`, `FireStream`, …) - a campfire metaphor that fits the "Kumbaya" theme. They're part of Kumbaya, not a separate protocol. **Reference:** [**Launchpad**](/developers/launchpad/overview.md). ## Three things to read first 1. [**Contract Addresses**](/developers/networks-and-contracts/contract-addresses.md) - every deployed address, mainnet and testnet 2. [**SDK Quickstart**](/developers/sdks/quickstart.md) - get a real quote in \~12 lines of TypeScript 3. [**Pool Init Code Hash**](/developers/dex-integration/pool-init-code-hash.md) - the one easy gotcha when computing pool addresses ## Networks | Network | Chain ID | RPC | | --------------- | -------- | --------------------------------- | | MegaETH Mainnet | `4326` | `https://mainnet.megaeth.com/rpc` | | MegaETH Testnet | `6343` | `https://carrot.megaeth.com/rpc` | See [**Networks & Contracts**](/developers/networks-and-contracts/contract-addresses.md) for the full set of details. ## Versions The Kumbaya SDKs track Uniswap upstream closely. Today's published versions: | Package | Version | | ----------------------------------- | ------- | | `@kumbaya_xyz/sdk-core` | 7.12.2 | | `@kumbaya_xyz/v3-sdk` | 3.15.5 | | `@kumbaya_xyz/router-sdk` | 1.17.3 | | `@kumbaya_xyz/universal-router-sdk` | 4.26.3 | Always check the [npm registry](https://www.npmjs.com/org/kumbaya_xyz) for current versions. ## Help * GitHub issues on the relevant repo * Twitter [@kumbaya\_xyz](https://twitter.com/kumbaya_xyz) * Email **** for partner API keys, indexer access, or anything that needs a human