Yield API Platform

A working reference implementation of a complete developer API platform — every layer a developer-facing business needs, built end to end: OAuth 2.0, webhooks, rate limiting, SDKs, request logging, and a developer dashboard.

What this is: a demonstrative build, not a commercial product. The domain is DeFi yield (a unified REST API wrapping Morpho and Aave), but the point is the platform craft around it — the same architecture I ran at Square scale: API design and versioning, AuthN/Z with short-lived tokens, Svix-powered event delivery, per-endpoint rate limits, sandbox semantics, and self-serve developer onboarding. No real funds move.

Live sandbox: the API gateway runs at flow-platform-production.up.railway.app (/health, /v1/*) with Stripe-style structured errors.

Overview

The platform provides a single REST API that wraps multiple DeFi protocols (Morpho and Aave), enabling developers to integrate yield without managing protocol-specific integrations, smart contracts, or compliance requirements.

Key Features:

• Unified API - Single interface for multiple DeFi protocols
• OAuth 2.0 Authentication - Short-lived access tokens with automatic refresh
• Real-time Webhooks - Svix-powered event delivery with retries
• Rate Limiting - Configurable per-endpoint limits
• Real-time Rates - Current APY from Morpho and Aave
• Developer Dashboard - Application, API key, and webhook management
• Request Logging - 7-day API request/response logging

Quick Start

Prerequisites

• JDK 17+
• PostgreSQL 12+
• Git

Local Development

# Clone repository
git clone https://github.com/mikewards/flow-platform.git
cd flow-platform

# Set up database
createdb flow_api

# Configure environment
cd flow-api
cp .env.example .env
# Edit .env with your database credentials

# Start backend
./gradlew run

# Start frontend (in another terminal)
cd frontend && npx wrangler dev

Visit http://localhost:8787 for the frontend and http://localhost:8080 for the API.

For detailed setup instructions, see Development Setup

Project Structure

flow-platform/
├── flow-api/              # Kotlin backend (Ktor)
│   ├── src/main/kotlin/   # Source code
│   │   └── com/ground/
│   │       ├── api/routes/     # API endpoints
│   │       ├── dto/            # Data transfer objects
│   │       ├── middleware/     # Auth, rate limiting, logging
│   │       ├── model/          # Database models
│   │       ├── service/        # Business logic
│   │       └── integration/    # Morpho/Aave clients
│   └── build.gradle.kts   # Build configuration
├── frontend/              # Frontend application
│   ├── pages/            # HTML pages
│   ├── styles/           # CSS files
│   ├── scripts/          # JavaScript files
│   │   └── token-manager.js  # OAuth token management
│   ├── sdk-demos/        # SDK demo pages
│   ├── worker.js         # Cloudflare Worker entry point
│   └── wrangler.jsonc    # Cloudflare Worker config
├── docs/                  # Documentation
│   ├── deployment/        # Deployment guides
│   ├── development/       # Development setup
│   ├── api/              # API documentation
│   └── architecture/      # System architecture
└── scripts/               # Build and deployment scripts

Technology Stack

Backend:

• Kotlin 1.9.20
• Ktor 2.3.5
• PostgreSQL
• Exposed (SQL framework)
• Web3j (Ethereum integration)
• Svix (Webhooks)

Frontend:

• Vanilla HTML/CSS/JavaScript
• Cloudflare Workers (hosting)
• TokenManager.js (OAuth 2.0 token refresh)

Infrastructure:

• Railway.app (backend hosting)
• Cloudflare Workers (frontend hosting)
• PostgreSQL (database)

Documentation

All documentation is organized in the docs/ directory:

• Development Setup - Local development guide
• API Specification - Complete API reference
• OpenAPI 3.1 spec - Machine-readable endpoint contract (served at /openapi.yaml)
• llms.txt - Docs index for coding agents (served at /llms.txt)
• Deployment Guide - Production deployment
• Architecture Overview - System design
• Environment Variables - Configuration reference

API Examples

Create Account

curl -X POST http://localhost:8080/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer",
    "password": "secure_password",
    "email": "dev@example.com"
  }'

Authenticate (Returns Access + Refresh Tokens)

curl -X POST http://localhost:8080/v1/auth/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer",
    "password": "secure_password"
  }'

# Response includes:
# - access_token (15 min)
# - refresh_token (30 days)

Refresh Token

curl -X POST http://localhost:8080/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "ground_refresh_..."
  }'

Get Yield Rates

curl -X GET http://localhost:8080/v1/yield/rates \
  -H "Authorization: Bearer YOUR_API_KEY"

See API Specification for complete API reference

Deployment

Railway (Backend)

1. Push code to GitHub
2. Connect repository to Railway
3. Add PostgreSQL database
4. Set environment variables (see below)
5. Deploy!

See Railway Deployment Guide for detailed instructions

Cloudflare Workers (Frontend)

cd frontend
npx wrangler deploy

See Cloudflare Deployment Guide for detailed instructions

Environment Variables

Required variables:

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - JWT signing secret (min 32 chars)
• MASTER_ENCRYPTION_KEY - Wallet encryption key (32 bytes hex)
• ENVIRONMENT - development, sandbox, or production
• SVIX_API_KEY - Svix webhook service API key

See Environment Variables Reference for complete list

Testing

# Run tests
cd flow-api
./gradlew test

# Build
./gradlew build

Contributing

This is a private project. For questions or contributions:

1. Check the documentation
2. Review API documentation
3. See development setup

License

MIT License

---

Built for developers who want to integrate DeFi yield into their applications.