# SAME DEX — CoinGecko Exchange API

Read-only market-data API for **SAME DEX**, an automated market maker (AMM)
decentralized exchange on **KleverChain**. Implemented to the CoinGecko
Trades & Tickers specification.

- **Base URL:** `https://api.want-same.com/api/dex/coingecko`
- **This documentation:** `https://api.want-same.com/api/dex/coingecko/docs` (raw markdown at `/docs.md`)
- **Format:** JSON over HTTPS, `GET` only, no authentication
- **Update frequency:** pair/ticker data refreshes every ~90s; trades every ~60s
- **Pair / pool model:** constant-product AMM pools. `ticker_id` uses the
  `BASE_TARGET` convention where `base` = `token_a`, `target` = `token_b`.
  Token identifiers are KleverChain KDA asset IDs (e.g. `SAME-3LRL`, `KLV`).
- **Order book:** not applicable — this is an AMM DEX with no central order book.
  `/orderbook` is therefore not implemented; pool depth is provided as
  `liquidity_in_usd` in `/tickers`. A synthesized order book can be added on
  request.

---

## GET /pairs

Returns every trading pair on the exchange.

**Request:** `GET /api/dex/coingecko/pairs`

**Response:** array of objects.

| Field | Type | Description |
|---|---|---|
| `ticker_id` | string | Pair identifier, `BASE_TARGET` |
| `base` | string | Base asset ID (token_a) |
| `target` | string | Target asset ID (token_b) |
| `pool_id` | string | Unique pool/pair identifier |

**Example**
```json
[
  { "ticker_id": "KLV_SAME-3LRL", "base": "KLV", "target": "SAME-3LRL", "pool_id": "KLV-SAME-3LRL" }
]
```

---

## GET /tickers

Returns 24-hour market data for every pair.

**Request:** `GET /api/dex/coingecko/tickers`

**Response:** array of objects.

| Field | Type | Description |
|---|---|---|
| `ticker_id` | string | Pair identifier, `BASE_TARGET` |
| `base_currency` | string | Base asset ID (token_a) |
| `target_currency` | string | Target asset ID (token_b) |
| `pool_id` | string | Unique pool/pair identifier |
| `last_price` | number | Last price of 1 base expressed in target |
| `base_volume` | number | 24h trading volume in base-token units |
| `target_volume` | number | 24h trading volume in target-token units |
| `liquidity_in_usd` | number | Pool liquidity in USD |
| `high` | number | 24h high price (target per base) |
| `low` | number | 24h low price (target per base) |

**Example**
```json
[
  {
    "ticker_id": "KLV_SAME-3LRL",
    "base_currency": "KLV",
    "target_currency": "SAME-3LRL",
    "pool_id": "KLV-SAME-3LRL",
    "last_price": 0.651655,
    "base_volume": 63448.651851,
    "target_volume": 40933.19192,
    "liquidity_in_usd": 1037.48,
    "high": 0.6570928242178131,
    "low": 0.6470594705888824
  }
]
```

---

## GET /historical_trades

Returns recent trades for a single pair.

**Request:** `GET /api/dex/coingecko/historical_trades?ticker_id={id}&type={buy|sell}&limit={n}`

**Query parameters**

| Param | Required | Description |
|---|---|---|
| `ticker_id` | yes | Pair identifier, `BASE_TARGET` (e.g. `KLV_SAME-3LRL`) |
| `type` | no | Filter to `buy` or `sell` (from the base-token perspective) |
| `limit` | no | Max trades to return (default 200, max 1000) |

**Response:** object with `buy` and `sell` arrays. Each trade:

| Field | Type | Description |
|---|---|---|
| `trade_id` | number | Unique, increasing trade identifier |
| `price` | number | Trade price of 1 base in target |
| `base_volume` | number | Trade size in base-token units |
| `target_volume` | number | Trade size in target-token units |
| `trade_timestamp` | number | Unix timestamp in milliseconds |
| `type` | string | `buy` or `sell` (from the base-token perspective) |

**Example**
```json
{
  "buy": [],
  "sell": [
    {
      "trade_id": 182,
      "price": 0.6516558277666668,
      "base_volume": 30000,
      "target_volume": 19549.674833,
      "trade_timestamp": 1783665888000,
      "type": "sell"
    }
  ]
}
```

---

## Trading fees

SAME DEX charges a **1% fee on each swap**. The entire fee is distributed to the
liquidity providers of the pair being traded; no portion is taken as a protocol
fee. There are **no deposit or withdrawal fees** — assets are held
non-custodially in on-chain liquidity pools. Network transaction (gas) fees on
KleverChain apply separately and are paid to the network, not to the exchange.

The fee is enforced on-chain and can be read from the DEX contract:
`getAmmFeeBps` returns `100` (1%), and `getLpFeeBps` returns `10000` (100% of the
fee to liquidity providers).

---

## Exchange details

- **Exchange name:** SAME DEX
- **Type:** Decentralized (AMM), on-chain on KleverChain
- **Website:** https://want-same.com
- **Contract (DEX):** `klv1qqqqqqqqqqqqqpgq2np843y2ag4yv064rf70e78kjxm68g6mscxq62hs0x`
- **Explorer:** https://kleverscan.org