RecoverySwap — API-first (API Server)

This repository is prepared to run the API server located in server/ as a standalone, production-ready service. The top-level focus is the API cache service — see server/README.md for full details (run instructions, Docker, env vars, troubleshooting).

Quick summary

• API server keeps a persisted cache of on-chain liquidity for commonly used tokens and exposes simple HTTP endpoints for retrieval and health checks.
• The service is intentionally lightweight and container-friendly (non-root runtime, healthcheck, persisted cache volume).

Quick start (local)

• From the repository root, install server deps and start the API:

  pnpm --dir server install pnpm --dir server start

• Or from inside the server/ folder:

  cd server pnpm install pnpm start

Docker (recommended for production)

• Build and run with docker-compose (from repository root):

  docker compose up --build -d

• The Compose service maps ./server/data to /app/data inside the container so the cache persists. See server/README.md for volume/permission notes.

Configuration (important env vars)

• PORT — HTTP port (default: 4001)
• RPC_URL — JSON-RPC provider used to read chain data (default: https://api.harmony.one). Use a reliable provider in production.
• VITE_BAND_ADDRESS — Band Oracle contract address for wONE/USD pricing (default: 0x0A87139b65399102f5F9B9B245531CF1A04ec86d)
• TTL_MS — cache TTL in milliseconds (default: 28800000 = 8h)
• MAX_PAIRS — maximum number of pairs to scan per factory (default: 1000)
• ALLOWED_ORIGINS — optional comma-separated list of allowed CORS origins (if unset, CORS is permissive for compatibility)
• NODE_ENV — set to production in the container by default

Data & health

• Cache file path: server/data/liquidity-cache.json.
• Health endpoint: /api/health — returns { ok, updatedAt, ttlMs, processing }.

Notes & operational guidance

• The container runs as a non-root user (node) and includes a HEALTHCHECK that probes /api/health.
• If your host already uses port 4001, stop the conflicting process or bind the container to another host port (e.g. -p 4002:4001 or set HOST_PORT in compose if configured).
• For production, use a robust RPC provider and consider adding monitoring/metrics and a readiness probe that waits for an initial cache.

Legacy & removed components

• This repository previously included frontend and contract artifacts. The repo has been refocused on the API server; frontend and other artifacts are no longer part of the primary code path. See docs/ for architectural notes that remain relevant.

License & support

• MIT — see LICENSE.md.
• For questions or issues, open an issue or PR in this repository. See server/README.md for the API-specific guide and troubleshooting steps.