# HartiiLabs

> HartiiLabs (hartiilabs.com) is a token launchpad and DEX on Quai Network mainnet (chain id 9, zone Cyprus-1). Anyone can launch an ERC-20 on a bonding curve; tokens graduate to an internal pool. HartiiSwap is a Uniswap V2 port for token/QUAI pools and farms. A free, read-only JSON API exposes every token, trade, candle, holder and wallet.

Key facts for agents:

- All money values in the API are **wei as decimal strings** (18 decimals). Parse with BigInt, never float, and divide by 1e18 only for display.
- Market cap = spot price × (1,000,000,000 minted − burned). Spot price and pricing rules: https://docs.hartiilabs.com/labs/pricing/
- Quai addresses are zone-sharded: Cyprus-1 addresses start with `0x00`. Send checksummed addresses to contracts. Use the `quais` SDK (not ethers) with RPC `https://rpc.quai.network/cyprus1`.
- The API is read-only and public (CORS open). Be polite: at most a few requests per second, and cache responses. Rate-limited requests get HTTP 429.
- Trading, launching and adding liquidity are on-chain transactions signed by the user's wallet (Pelagus). There is no custodial or API-key trading endpoint.
- User-created tokens are unverified. Nothing here is investment advice.

## Read API (GET, JSON, base https://hartiilabs.com)

- [Token list](https://hartiilabs.com/api/tokens?limit=50&sort=trending): `sort` = trending|new|volume|price|change|marketcap|graduation|holders|age|latest. Also takes `limit` and `cursor` (pagination via `nextCursor`).
- [One token](https://hartiilabs.com/api/token/0x0035187a7660f595d93cd53a4d16c635d6cffc8f): `/api/token/{address}` returns metadata, curve address, supply, burned, price, market cap and 24h stats.
- [Candles](https://hartiilabs.com/api/token/0x0035187a7660f595d93cd53a4d16c635d6cffc8f/candles?tf=1h&limit=100): `/api/token/{address}/candles?tf=1m|5m|15m|1h|4h|1d&limit=N` returns OHLC in wei per token and volume in QUAI wei.
- [Trades](https://hartiilabs.com/api/token/0x0035187a7660f595d93cd53a4d16c635d6cffc8f/trades?limit=50): `/api/token/{address}/trades?limit=N`
- [Holders](https://hartiilabs.com/api/token/0x0035187a7660f595d93cd53a4d16c635d6cffc8f/holders?limit=50): `/api/token/{address}/holders?limit=N`
- [Recent trades, all tokens](https://hartiilabs.com/api/trades/recent?limit=50)
- [Wallet portfolio](https://docs.hartiilabs.com/labs/api/): `/api/portfolio/{wallet}`, `/api/trades/{wallet}`, `/api/wallet/{wallet}/stats`, `/api/creator/{wallet}`
- [Ecosystem stats](https://hartiilabs.com/api/ecosystem-stats): launches, volume, holders, graduations, burns.
- [Graduations](https://hartiilabs.com/api/graduations), [Burns](https://hartiilabs.com/api/burns), [Top traders](https://hartiilabs.com/api/traders/top), [Volume series](https://hartiilabs.com/api/volume-series?days=30), [QUAI/USD price](https://hartiilabs.com/api/quai-price), [Health](https://hartiilabs.com/api/health)
- [Full API reference with response shapes](https://docs.hartiilabs.com/labs/api/)

## Contracts (Quai mainnet, Cyprus-1)

- TokenFactory (launches): `0x001AF1BbB40807fcb99C9Eeaa49dF5E91e7Efd42`. Each token has its own BondingCurve; find it with `curveOf(token)` or the `curveAddress` field in the API.
- HartiiSwap Factory: `0x002E75653C6189087Eb9E512cE7319eC21140956`. Always resolve pairs with `getPair(tokenA, tokenB)`; pair addresses are not CREATE2-derivable.
- HartiiSwap Router: `0x006B3450cca780066A3A8aA8b508103d25315Ea4` (Uniswap V2 interface, 0.3% fee, WETH = WQUAI).
- HartiiSwap Lens: `0x00295dFCA930646abAC327C9CcB2f4e1E206C5Ec` returns all pools and a wallet's positions in one call.
- WQUAI: `0x006C3e2AaAE5DB1bCd11A1a097cE572312EADdBB`
- QuaiRelay (pay any address in one call): `0x0031B09e63592B713768761cdDACC603974c10bD`
- [Contract references and ABIs](https://docs.hartiilabs.com/labs/contracts/) · [HartiiSwap contracts](https://docs.hartiilabs.com/swap/contracts/)

## Site pages (deep-linkable)

- [Token page](https://hartiilabs.com/token/0x0035187a7660f595d93cd53a4d16c635d6cffc8f): `/token/{address}` has the chart, trade panel, holders, comments and pool card.
- [Swap](https://hartiilabs.com/swap): `/swap?in=QUAI&out={tokenAddress}`
- [Pools](https://hartiilabs.com/pools) · [Create or add to a pool](https://hartiilabs.com/pools/add): `/pools/add?token={tokenAddress}&quote=QUAI` · [Remove liquidity](https://hartiilabs.com/pools/remove) · [Farms](https://hartiilabs.com/farms)
- [Discover tokens](https://hartiilabs.com/launchpad/discover) · [Launch a token](https://hartiilabs.com/launchpad/create) · [Analytics](https://hartiilabs.com/analytics)
- [Portfolio](https://hartiilabs.com/portfolio): uses the connected wallet.

## Docs

- [Developer docs home](https://docs.hartiilabs.com/): full docs index for agents at https://docs.hartiilabs.com/llms.txt, and all pages in one file at https://docs.hartiilabs.com/llms-full.txt
- [Integrating with quais: quote, buy, sell, index](https://docs.hartiilabs.com/labs/integrate-contracts/)
- [Integration recipes against the API](https://docs.hartiilabs.com/labs/integrate-api/)
- [HartiiSwap: swap, add and remove liquidity from code](https://docs.hartiilabs.com/swap/integrate/)
- [Bonding curve math](https://docs.hartiilabs.com/labs/bonding-curve/)

## Agents

**Launching soon — not live yet.** The Agent Terminal is built but its contracts are not deployed on mainnet yet: `/api/agent/manifest` reports `"deployed": false`, the build endpoints return 503, and `@hartii/agent-mcp` is not published yet. This section describes what goes live at launch.

- [Agent Terminal](https://hartiilabs.com/agent): let your own AI agent trade, launch tokens, swap,
  manage liquidity, launch NFT collections and play Fish/Fly — from a wallet whose spending limits
  are enforced **on-chain** by the `AgentVault` contract, not by Hartii's API or MCP server. Hartii
  hosts no model and holds no agent keys.
- [Agent API manifest](https://hartiilabs.com/api/agent/manifest): machine-readable tool list,
  contract addresses, caps and the Fish/Fly randomness recipe.
- [`@hartii/agent-mcp`](https://www.npmjs.com/package/@hartii/agent-mcp): the official MCP server —
  `npx -y @hartii/agent-mcp` with `HARTII_AGENT_KEY` and `HARTII_VAULT` set. Works with Claude Code,
  Claude Desktop, Codex, or any MCP-capable client.
- [Agent API reference](https://docs.hartiilabs.com/agent/api/), [AgentVault contract reference](https://docs.hartiilabs.com/agent/contracts/), [MCP setup](https://docs.hartiilabs.com/agent/mcp/), [Security](https://docs.hartiilabs.com/agent/security/)
- Beta. An agent's key can only call `AgentVault.execute`, which enforces a target allowlist,
  forbids moving tokens out of the vault, and enforces per-transaction and rolling-24h QUAI caps
  on-chain. Fund a vault only with what you can afford to lose.

## Optional

- [QuaiAxe (QAXE) burn vault: mining rewards that buy and burn QAXE](https://docs.hartiilabs.com/qaxe/)
- [FAQ for holders and creators](https://docs.hartiilabs.com/labs/faq/)
- [Sitemap](https://hartiilabs.com/sitemap.xml)