Aether-Swap Backend 🚀

Fastify off-chain indexing API for the Aether-Swap DEX — tracks 24h trading volume and pool reserves on Stellar Testnet/Mainnet.

Organization: Aether-Swap · Author: Alhaji-naira

---

Overview

The Aether-Swap Backend is a TypeScript/Fastify microservice that:

1. Indexes on-chain events from Soroban contract transactions via the Stellar Horizon API
2. Tracks 24-hour rolling volume per liquidity pool
3. Exposes pool reserve data in real time for the DEX frontend
4. Streams swap history with pagination support
5. Auto-refreshes every 30 seconds via background polling

---

Project Structure

Aether-Swap-Backend/
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    └── index.ts          # Server entrypoint, routes, Horizon indexer

---

API Reference

All endpoints return application/json. Base URL: http://localhost:3001

Interactive docs available at: http://localhost:3001/docs (Swagger UI)

Health

Method	Path	Description
GET	/health	Service health check

Response:

{ "status": "ok", "timestamp": "2026-01-01T00:00:00.000Z" }

---

Pools

GET /api/v1/pools

List all tracked liquidity pools.

{
  "pools": [
    {
      "poolId": "CAETHER000000DEMO",
      "tokenA": "XLM",
      "tokenB": "USDC",
      "reserveA": "1000000000",
      "reserveB": "1000000000",
      "volume24h": "50000000",
      "txCount24h": 42,
      "lastUpdated": "2026-01-01T00:00:00.000Z"
    }
  ],
  "count": 1
}

GET /api/v1/pools/:poolId

Fetch and refresh a single pool.

GET /api/v1/pools/:poolId/volume

24-hour volume for a specific pool.

{
  "poolId": "CAETHER000000DEMO",
  "volume24h": "50000000",
  "txCount24h": 42,
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

GET /api/v1/pools/:poolId/reserves

Current token reserves.

{
  "poolId": "CAETHER000000DEMO",
  "tokenA": "XLM",
  "reserveA": "1000000000",
  "tokenB": "USDC",
  "reserveB": "1000000000"
}

POST /api/v1/pools

Register a new pool for indexing.

Request body:

{
  "poolId": "CA...",
  "tokenA": "XLM",
  "tokenB": "USDC"
}

---

Swaps

GET /api/v1/swaps?limit=25&offset=0

Paginated swap history.

{
  "swaps": [
    {
      "txHash": "abc123...",
      "ledger": 12345,
      "timestamp": "2026-01-01T00:00:00Z",
      "tokenIn": "XLM",
      "amountIn": "10000000",
      "tokenOut": "USDC",
      "amountOut": "9970000",
      "trader": "GABC..."
    }
  ],
  "total": 100,
  "limit": 25,
  "offset": 0
}

---

Local Setup

Prerequisites

• Node.js ≥ 20.0.0
• npm ≥ 10

1. Install dependencies

cd Aether-Swap-Backend
npm install

2. Configure environment

cp .env.example .env

Edit .env:

PORT=3001
HOST=0.0.0.0
HORIZON_URL=https://horizon-testnet.stellar.org
AMM_POOL_CONTRACT_ID=CAETHER000000DEMO
TOKEN_A_ASSET=XLM
TOKEN_B_ASSET=USDC
CORS_ORIGIN=http://localhost:3000

3. Start development server

npm run dev

4. Build for production

npm run build
npm start

---

Architecture Decisions

Decision	Rationale
Fastify	2× faster than Express; built-in schema validation
In-memory store	Simple for scaffolding; swap for PostgreSQL + Redis in prod
Horizon polling	Reliable fallback; upgrade to Soroban RPC event streaming
30s refresh cycle	Balances freshness vs. Horizon rate limits
Swagger UI	Self-documenting API for frontend and integration teams

---

Production Recommendations

• Replace Map<> store with PostgreSQL (via Prisma or Drizzle ORM)
• Add Redis caching for volume aggregations
• Use Soroban RPC getEvents for real-time event streaming instead of polling
• Add authentication middleware for the POST /api/v1/pools endpoint
• Deploy behind nginx with TLS termination

---

License

MIT © Aether-Swap