fiatconnect-go

A Go implementation of the FiatConnect API specification, providing a standardized interface for cash-in/cash-out (CICO) operations between fiat and cryptocurrency.

This is a port of the TypeScript fiatconnect-api to Go, using the Gin web framework.

Features

• SIWE Authentication: Sign-In with Ethereum (SIWE) for secure, wallet-based authentication
• Session Management: Secure session handling with cookie-based storage
• FiatConnect Compliance: Full implementation of the FiatConnect v1.0.0 specification
• Modular Architecture: Clean separation of concerns with middleware, routes, and types
• Error Handling: Comprehensive error types matching the FiatConnect specification
• Docker Support: Ready-to-deploy Docker configuration

Architecture

The implementation follows a clean architecture pattern:

fiatconnect-go/
├── cmd/
│   └── server/          # Application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── errors/          # Error types and handling
│   ├── middleware/      # HTTP middleware (auth, sessions, errors)
│   ├── routes/          # Route handlers
│   │   ├── auth.go      # Authentication endpoints
│   │   ├── accounts.go  # Fiat account management
│   │   ├── kyc.go       # KYC endpoints
│   │   ├── quote.go     # Quote endpoints
│   │   └── transfer.go  # Transfer endpoints
│   └── types/           # Type definitions
└── go.mod

API Endpoints

Authentication (/v1/auth)

• POST /login - Authenticate with SIWE message and signature
• DELETE /logout - Clear session
• GET /clock - Get server time

Quotes (/v1/quote)

• POST /in - Get quote for cash-in (fiat → crypto)
• POST /out - Get quote for cash-out (crypto → fiat)

Accounts (/v1/accounts)

Requires authentication

• POST / - Add fiat account
• GET / - List fiat accounts
• DELETE /:fiatAccountId - Delete fiat account

KYC (/v1/kyc)

Requires authentication

• POST /:kycSchema - Submit KYC data
• GET /:kycSchema/status - Get KYC status
• DELETE /:kycSchema - Delete KYC data

Transfers (/v1/transfer)

Requires authentication

• POST /in - Initiate cash-in transfer
• POST /out - Initiate cash-out transfer
• GET /:transferId/status - Get transfer status

Prerequisites

• Go 1.21 or higher
• (Optional) Docker and Docker Compose

Installation

# Clone the repository
git clone <repository-url>
cd fiatconnect-go

# Install dependencies
make install

Configuration

Create a .env file in the project root (or copy from .env.example):

# Server Configuration
PORT=3000
HOST=localhost

# Session Configuration
SESSION_SECRET=your-secret-key-here

# SIWE Configuration
SIWE_REQUIRED=false
SIWE_DOMAIN=localhost:3000
SIWE_MAX_EXPIRATION_HOURS=4

# Provider Configuration
PROVIDER_ID=your-provider-id

Configuration Options

Variable	Description	Default
PORT	Server port	3000
HOST	Server host	localhost
SESSION_SECRET	Secret key for session encryption	Required
SIWE_REQUIRED	Require SIWE authentication for all endpoints	false
SIWE_DOMAIN	Expected domain in SIWE messages	localhost:3000
SIWE_MAX_EXPIRATION_HOURS	Maximum allowed SIWE message expiration	4
PROVIDER_ID	Your provider identifier	Required

Running the Application

Development

# Run with auto-reload
make dev

# Or run directly
make run

Production

# Build the binary
make build

# Run the binary
./bin/fiatconnect-server

Docker

# Build and run with Docker Compose
docker-compose up -d

# Or build Docker image
docker build -t fiatconnect-go .
docker run -p 3000:3000 --env-file .env fiatconnect-go

Development

Building

make build

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

Code Quality

# Format code
make fmt

# Run go vet
make vet

# Run linter (requires golangci-lint)
make lint

Implementation Status

✅ Completed

• Project structure and configuration
• Error types and handling
• Session management
• SIWE authentication middleware
• All route handlers with placeholders
• Docker support

🚧 TODO (Implementation Required)

The following business logic needs to be implemented in the route handlers:

Authentication

• Nonce validation and storage (prevent replay attacks)
• Domain and URI validation

Quotes

• Quote calculation logic (exchange rates, fees)
• Quote storage and expiration
• Quote validation

Accounts

• Fiat account schema validation
• Account storage and retrieval
• Account ownership verification

KYC

• KYC schema validation
• KYC data storage
• KYC verification process integration
• KYC status tracking

Transfers

• Transfer creation and storage
• Quote validation for transfers
• Crypto address generation (for cash-out)
• Transfer status updates
• Blockchain integration

Technology Stack

• Framework: Gin - Fast HTTP web framework
• Sessions: gorilla/sessions - Session management
• SIWE: spruceid/siwe-go - Sign-In with Ethereum
• Validation: validator/v10 - Struct validation
• Environment: godotenv - Environment variable loading

Comparison with TypeScript Implementation

Feature	TypeScript	Go
Framework	Express.js	Gin
Validation	Zod	validator/v10 + manual
Sessions	express-session	gorilla/sessions
SIWE	siwe	siwe-go
Type Safety	TypeScript	Go types
Performance	Node.js runtime	Native Go binary

API Specification

This implementation follows the FiatConnect Specification v1.0.0.

For detailed API documentation, request/response schemas, and integration guides, please refer to:

• FiatConnect API Specification
• OpenAPI/Swagger Spec

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Related Projects

• fiatconnect-ts - TypeScript implementation
• FiatConnect Specification - Official specification
• FiatConnect Types - TypeScript type definitions