# CMC and CoinGecko Reporting — Full API for All Tokens and Liquidity

This document describes the Token Aggregation Service reporting API used to expose **all coins, tokens, liquidity, and other reportable data** in formats suitable for **CoinMarketCap (CMC)** and **CoinGecko** listing submissions and sync.

## Endpoints

Base path: `/api/v1/report`

| Endpoint | Description | Cache |
|----------|-------------|--------|
| `GET /report/all` | Unified report: all tokens, pools, liquidity, volume, summary, and cross-chain data | 2 min |
| `GET /report/coingecko` | Token list and market data in CoinGecko-friendly format (includes crossChain) | 2 min |
| `GET /report/cmc` | Token list and DEX pairs in CoinMarketCap-friendly format (includes crossChain) | 2 min |
| `GET /report/cross-chain` | Cross-chain pools, bridge volume by lane, atomic swaps (138↔1, 138↔651940, etc.) | 2 min |
| `GET /report/token-list` | Flat canonical token list (all chains or `?chainId=138`) | 5 min |
| `GET /report/canonical` | Raw canonical token spec (symbol, name, type, decimals, addresses) | 10 min |

## Query Parameters

- **`chainId`** (optional): For `/report/all` and `/report/token-list`, limit to one chain (e.g. `138`, `651940`). For `/report/coingecko` and `/report/cmc`, set the chain for the response (default `138`).

## 1. Full Report — `GET /api/v1/report/all`

Returns all canonical tokens with DB-backed market data and pools, plus per-chain pool list and summary (total liquidity, volume, counts).

**Example:**

```bash
curl "http://localhost:3000/api/v1/report/all"
curl "http://localhost:3000/api/v1/report/all?chainId=138"
```

**Response shape:**

- `generatedAt`: ISO timestamp
- `chains`: list of chain IDs included
- `tokens`: `{ [chainId]: TokenReport[] }` — each token has `address`, `symbol`, `name`, `type`, `decimals`, `market` (priceUsd, volume24h, volume7d, volume30d, marketCapUsd, liquidityUsd), `pools` (poolAddress, dex, tvl, volume24h), `fromDb`
- `pools`: `{ [chainId]: LiquidityPool[] }`
- `summary`: `totalLiquidityUsdByChain`, `totalVolume24hUsdByChain`, `tokenCountByChain`, `poolCountByChain`

Use this for dashboards, internal analytics, and as the source of truth for “all reportable data.”

## 2. CoinGecko Format — `GET /api/v1/report/coingecko`

Returns tokens in a structure aligned with CoinGecko’s API and listing expectations: contract address, symbol, name, decimals, optional market_data (current_price, total_volume, market_cap, liquidity_usd), and liquidity_pools (pool_address, dex_id, tvl_usd, volume_24h_usd).

**Example:**

```bash
curl "http://localhost:3000/api/v1/report/coingecko?chainId=138"
```

**Use for:**

- Preparing CoinGecko listing submissions (contract address, symbol, name, decimals, platform).
- Feeding an internal or external job that syncs to CoinGecko (e.g. after they support custom chains).
- One-shot exports for manual submission.

**Note:** CoinGecko may not list ChainID 138 or 651940 until they add the platform. The response still provides a single, consistent format for all our tokens and liquidity.

## 3. CoinMarketCap Format — `GET /api/v1/report/cmc`

Returns tokens with contract address, symbol, name, decimals, volume_24h, market_cap, liquidity_usd, and `pairs` (pair_address, dex_id, base, quote, liquidity_usd, volume_24h_usd).

**Example:**

```bash
curl "http://localhost:3000/api/v1/report/cmc?chainId=138"
```

**Use for:**

- CMC DEX/listing submission or sync when the chain is supported.
- Internal reporting that mirrors CMC’s expected fields.

## 4. Token List — `GET /api/v1/report/token-list`

Flat list of all canonical tokens (per chain or all supported chains): `chainId`, `address`, `symbol`, `name`, `decimals`, `type` (base, w, asset, debt).

**Example:**

```bash
curl "http://localhost:3000/api/v1/report/token-list"
curl "http://localhost:3000/api/v1/report/token-list?chainId=651940"
```

**Use for:**

- DEX/UIs that need a single token list.
- Indexer or cron jobs that ensure every canonical token is registered in the DB.

## 5. Canonical Spec — `GET /api/v1/report/canonical`

Raw canonical token definitions (no DB merge): symbol, name, type, decimals, currencyCode, addresses by chainId. No market or pool data.

**Use for:** Tooling and config that need the authoritative list of tokens and their chains/addresses.

## Canonical Token Set and Addresses

The report uses the **canonical token list** in `src/config/canonical-tokens.ts`. It includes:

- **Base (GRU-M1):** cUSDC, cUSDT, cAUSDT, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT, plus env-gated ALL Mainnet gold landings `cAXAUC` / `cAXAUT`
- **Public transport mirrors (cW*):** cWUSDC, cWUSDT, cWUSDW, live cWAUSDT mirrors on BSC, Polygon, Avalanche, and Celo, plus env-gated ALL Mainnet gold wrappers `cWAXAUC` / `cWAXAUT`
- **W-tokens (ISO-4217):** USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW
- **Asset (ac*):** acUSDC, acUSDT, acEURC, acGBPC, acAUDC, acJPYC, acCHFC, acCADC, acXAUC
- **Debt (vdc* / sdc*):** vdcUSDC, sdcUSDC, vdcEURC, sdcEURC, vdcGBPC, sdcGBPC, vdcAUDC, sdcAUDC, vdcJPYC, sdcJPYC, vdcCHFC, sdcCHFC, vdcCADC, sdcCADC, vdcXAUC, sdcXAUC

Addresses per chain can be:

1. Set via env: `CUSDC_ADDRESS_138`, `CUSDT_ADDRESS_138`, etc.
2. Filled by the indexer when tokens are discovered on-chain.
3. Updated in the canonical config after deployment.

Only tokens with a non-empty address for the requested chain appear in `/report/coingecko`, `/report/cmc`, and in the per-chain sections of `/report/all` and `/report/token-list`.

For the live **ALL Mainnet AUSDT -> cWAUSDT -> cAUSDT** corridor, that means:

- `cWAUSDT` appears on BSC, Polygon, Avalanche, and Celo
- `cAUSDT` appears on Chain 138 via the live deployed address

For the planned **ALL Mainnet gold** corridor, the report remains intentionally env-gated until the destination contracts are live:

- `cAXAUC` / `cAXAUT` only appear on chain `651940` when `CAXAUC_ADDRESS_651940` / `CAXAUT_ADDRESS_651940` are set
- `cWAXAUC` / `cWAXAUT` only appear on chain `651940` when `CWAXAUC_ADDRESS_651940` / `CWAXAUT_ADDRESS_651940` are set
- generic `cXAUC` / `cXAUT` do **not** appear on `651940`; those remain canonical Chain 138 symbols

## ERC-20 and DEX Compatibility

All canonical tokens are designed to be **ERC-20 compliant** and usable in DEX liquidity pools (see `smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md`). Base and asset tokens are fully transferable; debt tokens can be deployed with optional transferability. The report API does not enforce on-chain checks; it reports whatever is in the canonical list and DB (addresses, market data, pools).

## 6. Cross-Chain Report — `GET /api/v1/report/cross-chain`

Returns cross-chain liquidity pools, bridge volume by lane, and atomic swap volume for Chain 138 and ALL Mainnet (651940). Covers CCIP (WETH9/WETH10), Alltra (138↔651940), Trustless (Lockbox), and Universal CCIP Bridge.

**Example:**

```bash
curl "http://localhost:3000/api/v1/report/cross-chain?chainId=138"
```

**Response shape:**

- `crossChainPools`: Array of `{ type, sourceChainId, destChainId, destChainName, bridgeAddress, tokenSymbol, bridgeType, isActive }`
- `volumeByLane`: Array of `{ sourceChainId, destChainId, destChainName, bridgeType, tokenSymbol, volume24hWei, volume7dWei, volume30dWei, txCount24h, txCount7d, txCount30d }`
- `atomicSwapVolume24h`: Total atomic swap volume (swap-then-bridge) in last 24h
- `bridgeVolume24hTotal`: Total bridge volume in last 24h
- `events`: Raw cross-chain events (limited to 500)

**Use for:** CMC/CoinGecko submission alongside single-chain reports. Include as `crossChain` attachment or reference URL when platforms support custom chain data.

**Note:** `/report/coingecko` and `/report/cmc` now include a `crossChain` field when cross-chain data is available.

## CMC / CoinGecko Listing Checklist

1. **Deploy and index:** Ensure tokens are deployed and the indexer has run so DB has addresses and (if applicable) market/pool data.
2. **Set addresses:** Configure canonical addresses via env or config so `/report/coingecko` and `/report/cmc` include all desired tokens.
3. **Export:** Use `GET /api/v1/report/coingecko` and `GET /api/v1/report/cmc` to obtain the payload for submission or sync.
4. **Submit:** Use each platform’s official process (e.g. CoinGecko “Submit coin”, CMC DEX/listing forms) and attach or map the exported data as required.
5. **Ongoing:** Re-export periodically or run a scheduled job that pushes liquidity/volume to CMC/CoinGecko if they provide an API for custom chains.

## Related

- **GRU M1 listing prep (dry-runs, dominance simulation, peg stress-tests):** `../../../../docs/gru-m1/README.md`
- **Token scope (base, W, asset, debt):** `smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md`
- **CoinGecko submission (cUSDC/cUSDT):** `docs/04-configuration/coingecko/COINGECKO_SUBMISSION_GUIDE.md`
- **Token Aggregation API:** `README.md` and `GET /api/v1/tokens`, `GET /api/v1/tokens/:address`, `GET /api/v1/pools/:poolAddress`