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

# Token Aggregation Service — REST API Reference

Base path: `/api/v1`. Used for discovery of tokens, liquidity pools, prices, volume, and OHLCV by dApps and MetaMask Snap integrations. Supports Chain 138 (DeFi Oracle Meta Mainnet) and Chain 651940 (ALL Mainnet).

## Chains

### GET /api/v1/chains

Returns supported chains.

**Response:** `{ chains: [{ chainId, name, explorerUrl }] }`

---

## Networks and config (Snap)

### GET /api/v1/networks

Full EIP-3085 chain params for `wallet_addEthereumChain` (Chain 138, Ethereum Mainnet 1, ALL Mainnet 651940). Includes RPC URLs, block explorer URLs, native currency, and oracles per chain. Used by the MetaMask Snap to serve dynamic network and oracle data. If **NETWORKS_JSON_URL** is set (e.g. GitHub raw URL), the service fetches that URL and returns `{ version, networks }`; otherwise uses built-in networks.

**Response:** `{ version: string, networks: NetworkEntry[] }`  
Each `NetworkEntry` has: `chainId` (hex), `chainIdDecimal`, `chainName`, `rpcUrls`, `nativeCurrency`, `blockExplorerUrls`, `iconUrls` (chain-specific logos; optional), `oracles: [{ name, address, decimals? }]`. Chain 138 and ALL Mainnet include explorer favicons; Ethereum includes standard ETH logo.

### GET /api/v1/config

Oracles (and config) per chain. Used by the Snap for USD price feeds (e.g. ETH/USD).

**Query:** `chainId` (optional) — if provided, returns config for that chain only.

**Response (no query):** `{ version: string, chains: [{ chainId, oracles: [{ name, address }] }] }`  
**Response (chainId=138):** `{ version, chainId: 138, oracles: [{ name, address }] }`

---

## Token list (report)

**GET /api/v1/report/token-list** returns a Uniswap-style token list with **logoURI** per token and a list-level **logoURI**. Each token has: `chainId`, `address`, `symbol`, `name`, `decimals`, `type`, `logoURI`. Use for MetaMask token list URL or Snap `get_token_list`. Optional query `?chainId=138` filters by chain. If **TOKEN_LIST_JSON_URL** is set (e.g. GitHub raw URL), the service fetches that JSON and returns it (with optional chainId filter); otherwise uses the built-in canonical token list.

---

## Quote

### GET /api/v1/quote

Returns an estimated swap output amount (constant-product from first available pool for the token pair).

**Query:**

| Param    | Type   | Required | Description                                      |
|----------|--------|----------|--------------------------------------------------|
| chainId  | number | yes      | 138 or 651940                                   |
| tokenIn  | string | yes      | Token address (in)                              |
| tokenOut | string | yes      | Token address (out)                             |
| amountIn | string | yes      | Raw amount in token's smallest unit (integer)   |

**Response:** `{ amountOut: string | null, error?: string, poolAddress?: string | null, dexType?: string }`  
If no pool is found, `amountOut` is `null` and `error` describes. Used by the MetaMask Snap for swap quotes.

---

## Bridge routes

### GET /api/v1/bridge/routes

Returns CCIP bridge routes for WETH9 and WETH10 (Chain 138 and Ethereum Mainnet). Used by the MetaMask Snap and dApps for bridge discovery. If **BRIDGE_LIST_JSON_URL** is set (e.g. GitHub raw URL), the service fetches that JSON and returns `{ routes, chain138Bridges }`; otherwise uses built-in routes.

**Response:** `{ routes, chain138Bridges, tokenMappingApi? }`  
- `routes`: `{ weth9: Record<string, string>, weth10: Record<string, string> }` — destination chain name → bridge address.  
- `chain138Bridges`: `{ weth9: string, weth10: string }` — Chain 138 bridge addresses.  
- `tokenMappingApi`: When the service runs from the monorepo, `{ basePath, pairs, resolve, note }` — use the same host and these paths for **cross-chain token address resolution** (138↔651940, 651940↔other chains). Bridge UIs should call `GET /api/v1/token-mapping?fromChain=&toChain=` or `GET /api/v1/token-mapping/resolve?fromChain=&toChain=&address=` when resolving token addresses on destination chains.

---

## Token mapping (multichain)

When run from the monorepo (with `config/token-mapping-multichain.json` available):

| Endpoint | Description |
|----------|-------------|
| `GET /api/v1/token-mapping?fromChain=138&toChain=651940` | Token mapping for a chain pair (tokens, addressMapFromTo, addressMapToFrom). |
| `GET /api/v1/token-mapping/pairs` | All defined chain pairs. |
| `GET /api/v1/token-mapping/resolve?fromChain=&toChain=&address=` | Resolve token address on target chain. |

Use these for bridge UIs and cross-chain address resolution. See token-aggregation README § Token mapping.

---

## Tokens

### GET /api/v1/tokens

List tokens for a chain with optional market data.

**Query:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| chainId | number | yes | 138 or 651940 |
| limit | number | no | Default 50 |
| offset | number | no | Default 0 |
| includeDodoPool | boolean | no | Include DODO pool flag per token |

**Response:** `{ tokens: Token[], pagination: { limit, offset, count } }`  
Each token may include `market` (price, volume, TVL) and `hasDodoPool` / `pmmPool` when requested.

### GET /api/v1/tokens/:address

Token detail by chain and address. Includes market data, pools, and external enrichment (CoinGecko, CMC, DexScreener).

**Query:** `chainId` (required) — 138 or 651940.

**Response:** `{ token: { ...token, onChain, market, external: { coingecko, cmc, dexscreener }, pools[], hasDodoPool, pmmPool } }`

### GET /api/v1/tokens/:address/pools

Liquidity pools for a token.

**Query:** `chainId` (required).

**Response:** `{ pools: [{ address, dex, token0, token1, reserves, tvl, volume24h, feeTier }] }`

### GET /api/v1/tokens/:address/ohlcv

OHLCV (candlestick) data for charts.

**Query:**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| chainId | number | yes | 138 or 651940 |
| interval | string | no | One of: 5m, 15m, 1h, 4h, 24h. Default 1h |
| from | ISO date | no | Start time (default: 7 days ago) |
| to | ISO date | no | End time (default: now) |
| poolAddress | string | no | Specific pool for price source |

**Response:** `{ chainId, tokenAddress, interval, data: OHLCV[] }`

### GET /api/v1/tokens/:address/signals

Trending/signals (e.g. CoinGecko trending rank) for a token.

**Query:** `chainId` (required).

**Response:** `{ chainId, tokenAddress, signals: { trendingRank } }`

---

## Pools

### GET /api/v1/pools/:poolAddress

Single pool by chain and pool address.

**Query:** `chainId` (required).

**Response:** `{ pool: { address, dex, token0, token1, reserves, tvl, volume24h, feeTier } }`

---

## Search

### GET /api/v1/search

Search tokens by symbol or name.

**Query:** `chainId` (required), `q` (required) — search string.

**Response:** `{ query, chainId, results: Token[] }`

---

## Pricing and market data

- **Per-token price/volume:** Use `GET /api/v1/tokens/:address`; the `market` and `external` fields provide prices and volume (from indexer and CoinGecko/CMC/DexScreener).
- **Liquidity (TVL):** Use `GET /api/v1/tokens/:address/pools` or `GET /api/v1/pools/:poolAddress`; each pool includes `tvl` and `volume24h`.
- **OHLCV:** Use `GET /api/v1/tokens/:address/ohlcv` for time-series price data.

---

## Health

### GET /health

Returns service and database health. Response: `{ status: 'healthy'|'unhealthy', timestamp, services: { database } }`.

---

## Caching and rate limiting

- Endpoints use short-lived cache (e.g. 1–5 minutes). Use `Cache-Control` headers from responses.
- `/api/v1` is rate-limited; see server configuration for limits.

---

## Use for discovery (no CMC/CoinGecko submission)

This API is the primary source for **token discovery**, **liquidity pool discovery**, and **pricing/market data** for Chain 138 and ALL Mainnet. dApps and a custom MetaMask Snap can consume it for:

- Token list and metadata
- Liquidity pools and TVL
- Prices and volume
- OHLCV for charts

Combine with the **explorer-hosted token list** (`https://explorer.d-bis.org/api/config/token-list`) for MetaMask token list URL discovery. For dynamic Snap integration, use **GET /api/v1/networks** and **GET /api/v1/config** (see "Networks and config (Snap)" above); the Snap can return the token list URL as `{apiBaseUrl}/api/v1/report/token-list` for MetaMask Settings.