​

API Service

​

Purpose and Responsibilities

• Unified API Gateway: Aggregates data from CoW Protocol APIs, blockchain nodes, and external services
• Token Information: Provides token prices, balances, and metadata
• Trading Data: Exposes yield pool information, market slippage, and trade simulations
• Affiliate Program: Manages affiliate program data and exports
• Hooks Integration: Provides access to hooks data from Dune Analytics
• Proxy Services: Proxies requests to TWAP and other backend services
• Caching Layer: Implements Redis-based caching for performance optimization

​

How to Run

​

Development

# Start dependencies (Redis, Database)
yarn compose:up

# Start the API service in development mode
yarn start

# The API will be available at http://localhost:3001

​

Production

# Build the application
yarn build api

# Start the production server
VERSION=1.0.0 node dist/apps/api/main.js

​

Docker

# Build the Docker image
yarn docker-build api

# Run the container
docker run -p 3001:1500 \
  -e COW_API_BASE_URL=https://api.cow.fi \
  -e REDIS_HOST=redis \
  api

​

Key Configuration Options

​

Server Configuration

​

External Services

​

Data Providers

​

Database Configuration

# CoW Analytics Database (Read-only)
COW_ANALYTICS_DATABASE_NAME=cow_analytics
COW_ANALYTICS_DATABASE_HOST=localhost
COW_ANALYTICS_DATABASE_PORT=5432
COW_ANALYTICS_DATABASE_USERNAME=analytics_user
COW_ANALYTICS_DATABASE_PASSWORD=password

​

Main Endpoints

​

Health & Information

• GET /about - API version and build information
  • Returns: { name, version, gitCommitHash }

​

Token Endpoints

• GET /:chainId/tokens/:tokenAddress/usdPrice - Get USD price for a token
  • Example: GET /1/tokens/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2/usdPrice
  • Returns: { price: number }
• GET /:chainId/tokens/:tokenAddress/topHolders - Get top token holders

​

Account & Balance Endpoints

• GET /:chainId/accounts/:userAddress/balances - Get token balances for an account
• GET /:chainId/accounts/:userAddress/balances/sse - Server-sent events for real-time balance updates
• GET /:chainId/address/:address/balances - Get balances for any address

​

Market & Trading Endpoints

• GET /:chainId/markets/:baseToken-:quoteToken/slippageTolerance - Get recommended slippage tolerance
• POST /:chainId/simulation/simulateBundle - Simulate transaction bundles with Tenderly

​

Yield Endpoints

• GET /:chainId/yield - Get pool information and average APR data

​

Hooks & Analytics

• GET /hooks - Get hooks data from Dune Analytics
  • Query params: blockchain, period, limit, offset

​

Notifications

• GET /accounts/:account/notifications - Get push notifications for an account

​

TWAP Proxy

• ALL /twap/* - Proxies requests to the TWAP service

​

Dependencies

​

Required Services

• Redis - Optional but recommended for caching. The API will work without Redis but with reduced performance. Configuration: REDIS_HOST, REDIS_PORT, REDIS_USER, REDIS_PASSWORD
• CoW Analytics Database - PostgreSQL database for analytics data (read-only access). Configuration: COW_ANALYTICS_DATABASE_* variables
• Blockchain RPC Nodes - HTTP or WebSocket endpoints for supported chains (Ethereum, Gnosis, etc.). Configuration: RPC_URL_1, RPC_URL_100, etc.

​

External APIs

• CoW Protocol API - Order book and trading data
• Socket.tech - Cross-chain bridge data
• CoinGecko - Token price feeds
• Tenderly - Transaction simulation
• Moralis/Ethplorer - Token metadata and holder information

​

Architecture Details

​

Plugin System

• env.ts - Environment variable validation
• cors.ts - CORS configuration
• redis.ts - Redis connection and caching
• orm-analytics.ts - Analytics database ORM
• orm-repositories.ts - Main database ORM
• swagger.ts - OpenAPI/Swagger documentation
• bffAuth.ts - Authentication middleware
• bffCache.ts - Response caching

​

Route Organization

routes/
├── about.ts              # Health/version endpoint
├── hooks.ts              # Dune Analytics hooks
├── __chainId/            # Chain-specific routes
│   ├── tokens/           # Token endpoints
│   ├── accounts/         # Account/balance endpoints
│   ├── markets/          # Market data endpoints
│   └── yield/            # Yield pool endpoints
├── accounts/             # Cross-chain account endpoints
├── affiliate/            # Affiliate program endpoints
└── twap/                 # TWAP service proxy

​

Background Jobs

• Affiliate Program Export Poller - Periodically exports affiliate program data

​

Nx Commands

# Development server
nx start api

# Build for production
nx build api

# Run tests
nx test api

# Lint
nx lint api

# Docker build
nx docker-build api

​

Swagger Documentation

• Swagger UI: http://localhost:3001/documentation

​

Related Services

• TWAP Service - Time-weighted average price orders
• Notification Producer - Push notification generation
• Telegram Bot - Telegram notification delivery