76aa419320
- CCIP/trustless bridge contracts, GRU tokens, DEX/PMM tests, reserve vault. - Token-aggregation service routes, planner, chain config, relay env templates. - Config snapshots and multi-chain deployment markdown updates. - gitignore services/btc-intake/dist/ (tsc output); do not track dist. Run forge build && forge test before deploy (large solc graph). Made-with: Cursor
167 lines
8.8 KiB
Markdown
167 lines
8.8 KiB
Markdown
# 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`
|