# SAME DEX — GeckoTerminal Integration API

Implementation of the **GeckoTerminal Integration API Standards** (v0.1) for
**SAME DEX**, an AMM decentralized exchange on **KleverChain** (non-EVM).

- **Base URL:** `https://api.want-same.com/api/dex/geckoterminal`
- **This documentation:** `/docs` (raw markdown at `/docs.md`)
- **Format:** JSON over HTTPS, `GET` only, no authentication
- **DEX contract:** `klv1qqqqqqqqqqqqqpgq2np843y2ag4yv064rf70e78kjxm68g6mscxq62hs0x`
- **Explorer:** https://kleverscan.org
- **dexKey:** `same-dex`

## Identifier conventions

- **Asset ids** are KleverChain KDA asset ids exactly as shown on the block
  explorer, e.g. `KLV`, `SAME-3LRL`, `USDT-23V8`. Case-sensitive.
- **Pair ids** are `ASSET0-ASSET1` with assets in alphabetical order, e.g.
  `KLV-SAME-3LRL`. All pools live inside the single DEX smart contract
  (KleverChain has no per-pool LP token contracts), so pair ids are logical
  identifiers rather than contract addresses.
- All amounts, prices and reserves are **decimalized** (whole token units) and
  returned as strings where precision matters.

## GET /latest-block

Returns the newest block for which `/events` data is complete. The indexer
trails the chain head by a few blocks to guarantee this.

```json
{ "block": { "blockNumber": 31745233, "blockTimestamp": 1783927060 } }
```

## GET /asset?id=:string

```json
{
  "asset": {
    "id": "SAME-3LRL",
    "name": "SAME",
    "symbol": "SAME",
    "decimals": 6,
    "totalSupply": 150000000,
    "circulatingSupply": 135034410.869006
  }
}
```

Supply values come live from the KleverChain indexer API and refresh at most
every 10 minutes.

## GET /pair?id=:string

```json
{
  "pair": {
    "id": "KLV-SAME-3LRL",
    "dexKey": "same-dex",
    "asset0Id": "KLV",
    "asset1Id": "SAME-3LRL",
    "createdAtBlockNumber": 26334500,
    "createdAtBlockTimestamp": 1762300000,
    "createdAtTxnId": "…",
    "feeBps": 100
  }
}
```

`createdAt*` reflects the pair's first indexed event (per GT FAQ #9). The swap
fee is 1% (`feeBps: 100`), fully distributed to liquidity providers.

## GET /events?fromBlock=:number&toBlock=:number

Both bounds inclusive. Returns swap and join/exit events ordered by
`(blockNumber, txnIndex, eventIndex)`.

```json
{
  "events": [
    {
      "block": { "blockNumber": 31724162, "blockTimestamp": 1783842700 },
      "eventType": "swap",
      "txnId": "040e0907980c1bb0…",
      "txnIndex": 0,
      "eventIndex": 0,
      "maker": "klv1vlkgmxex2m2n5r6arcg4kpe7ks2ajhax5dnnezkgmtjtu92ugw6qcmd2c0",
      "pairId": "KLV-SAME-3LRL",
      "asset0In": "10000",
      "asset1Out": "6501.852634",
      "priceNative": "0.6501852634",
      "reserves": { "asset0": "1258973.761749", "asset1": "819421.527845" }
    }
  ]
}
```

## Data sourcing & guarantees

- Events are reconstructed from on-chain **transaction transfer receipts** of
  the DEX contract, indexed via the KleverChain indexer API. This covers both
  direct swaps (`market_order_hybrid`, `multiHopSwap`) and cross-contract
  swaps executed by the SAME vault and battle contracts.
- `txnIndex` is the transaction's position within its block; `eventIndex`
  orders events within a transaction. The combination is unique per block.
- `maker` is the account that signed the transaction.
- Reserves are tracked as a running balance per pair and periodically
  re-synced against the live on-chain pool state (`getPairsLiquidityAndStats`
  contract view). LP-fee claims and admin operations that move pool balances
  outside swap/join/exit semantics are absorbed by this re-sync.
- The full DEX history (from contract deployment, block ~26.33M, Nov 2025) is
  backfilled.
- Multi-token (3+) pools do not exist on SAME DEX; every pool holds exactly
  two assets.

## Rate limits

The API is served from our own infrastructure and comfortably supports the GT
indexer's default 2-second polling interval. Contact us to coordinate higher
rates or larger block chunks.

## Contact

- Website: https://want-same.com — DEX app: https://dex.want-same.com/dex
- Twitter/X: https://x.com/want_same_
- Telegram: https://t.me/want_same