# KHACN — Exchange & Market-Maker Integration (Coinstore and partners)

**KharYsma Coins (KHACN)** — 10,000,000 total supply, live on Ethereum
(`0x11c1b94294A7967092F747434dEE4876EcA5fD53`), launching on **Base** (chainId 8453) through a public
price-discovery auction, then open liquidity on Uniswap V4 and Aerodrome. Every KHACN on Base is backed 1:1 by
KHACN locked on Ethereum. The Base token is immutable: no owner, no tax, no blacklist, no pause.

This README explains how an exchange can **list KHACN with a live order book from day one, without pre-funding
inventory**, and how its market makers can plug in.

---

## 1. What you get
| | |
|---|---|
| Live KHACN liquidity for your order book | our on-chain **OTC desk** publishes ask / bid and available size in real time |
| No inventory to pre-fund | buy from the desk *just in time*, when your client's order fills |
| Two-way market | the desk also buys KHACN back (within a published budget), so your clients can buy **and** sell |
| Instant settlement | one Base transaction, ~2 s, payment and delivery are atomic |
| Free | no integration fee, no API fee for the desk endpoints, no whitelist |

## 2. Endpoints (free)
Base URL: `https://145-241-171-169.sslip.io` (a project domain will be announced at launch on https://startarcoins.com)

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/v1/desk` | desk address, accepted payment tokens, live `ask_per_khacn` / `bid_per_khacn`, `available_to_buy_khacn`, `available_to_sell_khacn`, buyback budget, paused flag (15 s cache) |
| POST | `/api/v1/desk/quote` | firm EIP-712 quote, valid 60 s, one taker, one nonce |
| GET | `/api/v1/khacn` | contract addresses, total / circulating supply, Ethereum reserve |
| GET | `/api/v1/market` | price, liquidity, 24 h volume (GeckoTerminal) |
| GET | `/api/public/khacn/circulating` | plain number (CMC / CoinGecko format) |

Quote request:
```json
POST /api/v1/desk/quote
{"taker": "0xYourSettlementWallet", "side": "buy", "pay_token": "USDC", "khacn_amount": "25000"}
```
Response: `quote` (struct), `signature`, `msg_value` (for ETH), `human` (readable price, amount, validity).

## 3. Order-book integration (recommended flow)
1. **Mirror the desk:** poll `GET /api/v1/desk` every 5–15 s. Display on your KHACN/USDT book, for example:
   - asks at `ask_per_khacn` (USDT/USDC) up to `available_to_buy_khacn`,
   - bids at `bid_per_khacn` up to the buyback budget.
   Add your own fee / spread on top as you wish.
2. **Client buys on your book:** request a `buy` quote for the filled size, call `fill(quote, signature)` on the desk
   from your settlement wallet, paying USDC / USDT / ETH / cbBTC. KHACN arrive in the same transaction; credit your
   client internally.
3. **Client sells on your book:** request a `sell` quote, `approve` KHACN to the desk, call `fill`. The desk pays you.
4. **Withdrawals / deposits** of your clients use KHACN on Base like any ERC-20.

Contract call:
```
fill((address taker, uint8 side, address payToken, uint256 khacnAmount, uint256 payAmount,
      uint256 nonce, uint256 deadline) quote, bytes signature)      // side: 0 = BUY, 1 = SELL
```
BUY with ETH: send `msg_value`. BUY with a token: `approve(desk, payAmount)` first. SELL: `approve(desk, khacnAmount)`.

## 4. Market makers
Your market makers are welcome to:
- quote continuously on your book using the desk as their hedge (no inventory needed);
- provide liquidity on our public pools (Uniswap V4, Aerodrome, Uniswap V3) and arbitrage freely between your book,
  our pools and the desk — competition with other market makers and with the project's own bots is open.

The only rule (market-abuse law, MiCA): never trade with yourself or between your own wallets to create volume or
candles.

## 5. Guarantees enforced by the smart contract
- **Pay first, deliver in the same transaction:** no payment, no KHACN. The project never lends or deposits tokens.
- **Self-refilling two-way liquidity:** a share of every purchase (30 % at launch, published in `GET /api/v1/desk` as
  `payment_split`) stays in the desk as buyback liquidity, so partners can always sell back; the rest goes to the
  project wallet in the same transaction.
- **Price bounds:** the desk never sells below a floor nor buys back above a ceiling (always below the floor), per
  payment token.
- **Daily limits** per side; **quotes** bound to one taker, one nonce, 60 s (no replay, no front-running).
- **Built for size:** a single fill of 1,000,000 $ is covered by the contract tests; quotes are served in parallel
  (≈ 44 signed quotes per second measured on our server, settlement limited only by Base itself). Large orders get a
  size premium (up to +5 % when taking the whole available stock), so the price stays fair for everyone.
- **Prices protected by our own on-chain oracle:** ask on the higher of the pool spot and its 10-minute median, bid on
  the lower; the sale floor follows the market upward automatically (it can never be lowered by the quote server).
- **Always read the desk address from `GET /api/v1/desk`** (field `desk`): it is the single source of truth, also after
  a contract upgrade.
- Payment tokens on Base: ETH, USDC, USDT, cbBTC (the live list is in `GET /api/v1/desk`).

## 6. Test it today (Base Sepolia testnet, chainId 84532)
- Desk: `0x0325CCba4Bf9da6B9f8F64a4eD9BC67C62418955`
- Test KHACN: `0xeed2411879c47a972dadd9fd6fe4112acb096a8d`
- Test USDC: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
- Public API above already serves the testnet desk. An end-to-end run (buy 100 KHACN with ETH, sell back 50) passed
  on 17 Nov 2026. A reference script is available on request (Python, web3).

The mainnet desk is deployed with the launch; its address is published on our official channels and in
`GET /api/v1/desk`.

## 7. Listing information
- Name / symbol / decimals: KharYsma Coins / KHACN / 18
- Ethereum: `0x11c1b94294A7967092F747434dEE4876EcA5fD53`
- Base: published at launch (immutable, verified on Basescan)
- Website: https://startarcoins.com — Contact: contact@startarcoins.com
- Policy: no listing fee, no token deposit; performance-based terms welcome, in writing.
