kaccy-api

Production REST + GraphQL + WebSocket API layer for the Kaccy Protocol, built on Axum with a full middleware stack covering authentication, observability, real-time streaming, background jobs, and multi-channel notifications.

Features

Core API

• 27 route modules spanning Phases 0–3 (auth through admin)
• RESTful endpoints with versioning middleware
• GraphQL endpoint via async-graphql 7.2
• Batch request processing

Auth & Security

• JWT bearer authentication with refresh tokens
• Argon2 password hashing
• TOTP two-factor authentication
• OAuth2 provider integration
• API key management with per-key analytics
• Session management
• KYC (Know Your Customer) workflow
• IP filtering, request signing, and request validation middleware
• Security headers middleware (HSTS, CSP, etc.)
• Circuit breaker middleware

Real-time

• WebSocket (ws) endpoint for live data feeds
• Server-Sent Events (streaming) for unidirectional push
• Event bus with publisher/subscriber pattern and typed handlers

Observability

• OpenTelemetry tracing via telemetry middleware
• Prometheus metrics via metrics middleware
• Structured request/response logging
• Request-ID propagation
• Profiling middleware
• Audit log trail for sensitive operations

Tooling

• SDK generator for TypeScript, Python, Rust, and Go clients
• Background job queue with scheduler and worker
• Behavior, metrics, and performance analytics subsystem
• Multi-channel notifications: email, SMS, push, in-app
• OpenAPI/Swagger docs endpoint

Architecture

Routes

Auth (/api/auth)

Users (/api/users)

Tokens (/api/tokens)

Trading (/api)

Real-time

Admin (/api/admin)

API Keys (/api/api_keys)

Sessions (/api/sessions)

Notifications (/api)

Developer (/api)

Middleware Stack

The following Tower middleware layers are composed in order:

Installation

Add to your Cargo.toml:

[dependencies]
kaccy-api = "0.2.0"

Quick Start

use kaccy_api::state::AppState;
use kaccy_db::create_pool;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build database pool
    let pool = create_pool(&std::env::var("DATABASE_URL")?).await?;

    // Construct shared application state
    let state = AppState::builder()
        .pool(pool)
        .jwt_secret(std::env::var("JWT_SECRET")?)
        .redis_url(std::env::var("REDIS_URL")?)
        .build()?;

    // Create the full router (all 27 route modules + middleware stack)
    let app = kaccy_api::router::create(state).await?;

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;

    Ok(())
}

Configuration

Testing

The crate has 201 passing tests. 18 integration tests require a live PostgreSQL instance and a running server; they are automatically skipped in CI via #[ignore].

# Run all unit tests (no external services needed)
cargo nextest run -p kaccy-api

# Run integration tests (requires DATABASE_URL and a running server)
cargo nextest run -p kaccy-api -- --include-ignored

Part of the COOLJAPAN ecosystem.