TWAP Service
The TWAP service functions as a configuration storage layer for time-weighted average price orders. It manages TWAP order configurations by persisting order configurations and providing endpoints for CRUD operations across multiple blockchain networks.
Core Responsibilities
- Storing TWAP order configurations and Safe transaction data
- Providing query endpoints for wallet-specific orders
- Validating order parameters before persistence
- Reading orderbook data to monitor execution status
- Supporting Mainnet (1), Goerli (5), and Gnosis Chain (100)
How to Run
Development
Production
Docker
Configuration
Environment variables control server and database settings:
Server
TWAP Database
Orderbook Database
API Endpoints
GET /:chainId/:walletAddress/orders
Retrieves all TWAP orders for a specified wallet and chain. Returns an array of order objects containing token addresses, amounts, timing parameters, and wallet information.
POST /:chainId/:walletAddress/orders
Creates a new TWAP order with parameters defining the selling token, buying token, recipient address, part amounts, timing schedule (start time, intervals, number of parts), and Safe transaction hash.
Data Models
Order Entity: Stores TWAP configuration including tokens, amounts, recipient, timing parameters (t0, n, t, span), and app data hash.
Wallet Entity: Represents Safe wallet addresses with one-to-many relationship to orders.
SafeTx Entity: Persists Safe transaction metadata associated with order creation.
Database Architecture
The service requires two PostgreSQL instances:
- Primary database - For order and wallet storage with TypeORM migrations
- Read-only orderbook database - For tracking execution and settlement events
Plugin System
Fastify plugins provide modular functionality:
- Environment Plugin - Validates required configuration variables
- ORM Plugin - Manages TypeORM database connections
- Orderbook Plugin - Establishes read-only orderbook access
- Swagger Plugin - Generates OpenAPI documentation at
/documentation
Execution Model
The TWAP service functions primarily as storage infrastructure. Actual order execution involves:
- CoW Protocol Watchtower - Monitoring and part creation
- Orderbook - Matching and settlement
- Safe infrastructure - Transaction execution
Integration
The main API service can proxy TWAP requests using HTTP forwarding, exposing TWAP functionality through a unified API gateway via the TWAP_BASE_URL configuration.
Development Commands
Last modified on March 4, 2026
