proxmox/docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md

# Token-Aggregation Report API — Reachability Runbook

**Purpose:** Ensure `GET /api/v1/report/coingecko`, `GET /api/v1/report/cmc`, and `GET /api/v1/report/token-list` are reachable for CoinGecko/CMC submission and Chain 138 Snap.

---

## 1. Verify current state

```bash
# From repo root
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
```

**Expected when working:** Token list and networks return valid JSON with `.tokens` and `.networks`.

**If you see "no .tokens" or "no .networks":** The `/api/v1/` path is likely proxied to Blockscout (or another backend) instead of token-aggregation. Proceed to §2.

---

## 2. Deploy token-aggregation (if not running)

### 2.1 On explorer VM (VMID 5000) or dedicated host

1. **Deploy the service:**
   ```bash
   cd smom-dbis-138/services/token-aggregation
   cp .env.example .env
   # Edit .env: DATABASE_URL, CUSDC_ADDRESS_138, CUSDT_ADDRESS_138 (minimum for report)
   npm install && npm run build
   ```

2. **Run via systemd** (or use `deploy-to-proxmox.sh` / `deploy-to-vmid.sh`):
   ```bash
   # Example systemd unit
   ExecStart=/usr/bin/node /opt/token-aggregation/dist/index.js
   WorkingDirectory=/opt/token-aggregation
   ```

3. **Verify locally:**
   ```bash
   curl -s "http://localhost:3000/api/v1/report/token-list?chainId=138" | jq '.tokens | length'
   curl -s "http://localhost:3000/api/v1/report/coingecko?chainId=138" | jq '.'
   curl -s "http://localhost:3000/api/v1/networks" | jq '.networks | length'
   curl -s "http://localhost:3000/api/v1/bridge/preflight" | jq '.gruTransport.summary'
   ```

### 2.2 Minimum env for report API

| Var | Purpose |
|-----|---------|
| `CUSDC_ADDRESS_138` | cUSDC on Chain 138 |
| `CUSDT_ADDRESS_138` | cUSDT on Chain 138 |
| `CHAIN_138_RPC_URL` or `RPC_URL_138` | RPC for indexing |
| `DATABASE_URL` | PostgreSQL (required for full service) |

**Note:** The report endpoints may work with minimal config; full indexing requires DB and RPC.

---

## 3. Proxy /api/v1/ to token-aggregation (explorer.d-bis.org)

If token-aggregation runs on the **explorer VM** (e.g. port 3000):

```bash
# SSH to explorer VM (VMID 5000), then:
TOKEN_AGG_PORT=3000 CONFIG_FILE=/etc/nginx/sites-available/blockscout \
  bash /path/to/explorer-monorepo/scripts/apply-nginx-token-aggregation-proxy.sh
```

This inserts `location /api/v1/` proxying to `http://127.0.0.1:3000/api/v1/`. **Important:** The token-aggregation `location` must be defined **before** any Blockscout API `location` that might also match `/api/v1/`, so token-aggregation takes precedence.

### 3.1 If token-aggregation runs elsewhere

- **Option A:** Run token-aggregation on the explorer host (same machine as nginx) and proxy to `127.0.0.1:3000`.
- **Option B:** Run on a different host; proxy to that host, e.g. `proxy_pass http://192.168.11.XXX:3000/api/v1/;`
- **Option C:** Use a separate domain (e.g. `api.d-bis.org`) for the token-aggregation API and set `GATSBY_SNAP_API_BASE_URL` to that URL when building the Snap site.

---

## 4. Re-verify

```bash
bash scripts/verify/check-token-aggregation-chain138-api.sh
# or: BASE_URL=https://explorer.d-bis.org bash scripts/verify/check-token-aggregation-chain138-api.sh
```

Expect `200` on tokens, pools, quote, networks, **`/api/v1/bridge/routes`**, **`/api/v1/bridge/status`**, and **`/api/v1/bridge/preflight`**. If `bridge/routes` or `bridge/preflight` is `404` or `{"error":"Not found"}`, the explorer host is still running an older token-aggregation build: redeploy the service from `smom-dbis-138/services/token-aggregation` and reload nginx.

```bash
# Reachability only
ALLOW_BLOCKED=1 bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org

# Strict operator preflight: fails if any GRU pair is still blocked
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org
```

```bash
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
```

All checks should pass. Then:

```bash
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
```

Use these files for CoinGecko/CMC submission per [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md).

---

## 5. Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| `curl .../api/v1/report/token-list` returns Blockscout-style JSON (`message`, `result`, `status`) | `/api/v1/` proxied to Blockscout, not token-aggregation | Ensure token-aggregation `location` is first; reload nginx |
| Connection refused to 127.0.0.1:3000 | Token-aggregation not running | Start service; check `systemctl status token-aggregation` |
| Empty `tokens` array | Indexer / DB | **Chain 138:** `CHAIN_138_DODO_PMM_INTEGRATION` defaults to canonical DODOPMMIntegration if unset. Set `DATABASE_URL`, run migrations, ensure RPC to 138. Also set `CUSDT_ADDRESS_138` / `CUSDC_ADDRESS_138` (see `smom-dbis-138/services/token-aggregation/.env.example`). |
| 502 Bad Gateway | Token-aggregation crashed or wrong port | Check logs; verify `TOKEN_AGG_PORT` matches service |
| `/api/v1/bridge/preflight` shows blocked pairs | Missing runtime env refs for GRU Transport | Run `bash scripts/verify/check-gru-transport-preflight.sh` and clear the reported `runtimeMissingRequirements` / `eligibilityBlockers` |

---

## 6. Quick commands summary

```bash
# 1. Verify (from repo root)
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org

# 1b. GRU Transport operator preflight
bash scripts/verify/check-gru-transport-preflight.sh https://explorer.d-bis.org

# 2. Export for submission (after API is reachable)
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
```

---

## 7. Related docs

- [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md) — Price feed checklist
- [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) — Export and submit
- [smom-dbis-138/services/token-aggregation/README.md](../../../smom-dbis-138/services/token-aggregation/README.md) — Service setup