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

# 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. Repo check: scripts/verify/check-public-report-api.sh tries apex /api/v1/ first, then /token-aggregation/api/v1/, and uses whichever returns a .networks array.

---

2. Deploy token-aggregation (if not running)

2.1 On explorer VM (VMID 5000) or dedicated host

1. Deploy the service:

   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):

   # Example systemd unit
   ExecStart=/usr/bin/node /opt/token-aggregation/dist/index.js
   WorkingDirectory=/opt/token-aggregation
   

3. Verify locally:

   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):

# 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 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.

# 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 metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org

All checks should pass. Then:

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.

---

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

# 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 checklist
• CMC_COINGECKO_SUBMISSION_RUNBOOK — Export and submit
• smom-dbis-138/services/token-aggregation/README.md — Service setup