smom-dbis-138/services/token-aggregation/docs/CMC_COINGECKO_REPORTING.md

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:

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:

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:

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:

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, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT
• 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.

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:

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