Unigox API Gateway

API Gateway for the Unigox platform - a unified entry point for partner integrations.

Description

This service is an API Gateway that proxies requests to microservices:

• Currencies Service - currency and exchange rate service

• Offers Service - offers and payment methods service

Project Structure

api/
├── internal/
│   ├── handler/      # HTTP handlers and routing
│   ├── models/       # Data models and configuration
│   ├── repository/   # Repositories (placeholder for future use)
│   └── service/      # Business logic and proxy service
├── pkg/
│   └── logger/       # Zap logger
├── docs/             # Swagger/OpenAPI documentation
└── main.go           # Entry point

Configuration

The service uses environment variables. Copy .env.example to .env and configure:

• PORT - server port (default: 8080)

• CURRENCIES_SERVICE_URL - base URL of the currencies service (default: http://localhost:8081)

• OFFERS_SERVICE_URL - base URL of the offers service (default: http://localhost:8084)

• LOG_LEVEL - logging level (debug, info, warn, error, fatal, panic)

• GIN_MODE - Gin mode (debug, release)

Setup Environment Variables

# Copy example environment file
cp .env.example .env

# Edit .env with your configuration
# For production, set actual service URLs:
# CURRENCIES_SERVICE_URL=https://currencies.unigox.com
# OFFERS_SERVICE_URL=https://offers.unigox.com

Maintaining .env.example

Important: When adding new environment variables to internal/models/config.go, you must also update .env.example to keep it in sync. This ensures that:

• New developers can easily set up the project

• All required environment variables are documented

• CI/CD pipelines know what variables are needed

Rule: If you add a new environment variable, update both:

1. internal/models/config.go - to read the variable

2. .env.example - to document the variable with a comment

Running

# Install dependencies
go mod download

# Run the service
go run main.go

API Endpoints

Health Check

• GET /health - service health check

Currencies Service (proxied to currencies service)

• GET /api/v1/rates - get currency exchange rates

• GET /api/v1/rates/history - get exchange rate history

• GET /api/v1/currency/convert - convert currency

• GET /api/v1/currencies - list all fiat currencies

• GET /api/v1/cryptocurrencies - list all cryptocurrencies

• GET /api/v1/bridge-cryptocurrencies - list bridge cryptocurrencies

• GET /api/v1/countries-with-currencies - list countries with currencies

Offers Service (proxied to offers service)

• GET /api/v1/payment-methods - list payment methods

• GET /api/v1/payment-methods/:id - get payment method by ID

• GET /api/v1/payment-methods/by-slug/:slug - get payment method by slug

• GET /api/v1/payment-methods/by-fiat/:fiat_currency_code - payment methods by currency

• GET /api/v1/payment-methods/by-network/:network_slug/fiat/:fiat_currency_code - payment methods by network and currency

• GET /api/v1/payment-methods/types - list payment method types

• GET /api/v1/payment-methods/:id/options - payment method options

• GET /api/v1/payment-methods/all-options - all payment method options

• GET /api/v1/get-currency-and-payment-methods-with-networks - currencies with payment methods and networks

• GET /api/v1/get-currency-and-payment-networks-with-methods - currencies with networks and payment methods

• GET /api/v1/get-supported-pairs - supported trading pairs

• GET /api/v1/get-fiat-currency-countries-with-payment-methods - countries with currencies and payment methods

• GET /api/v1/supported/corridors - live rates + spreads vs Open Exchange Rates for every supported corridor

Swagger/OpenAPI Documentation

OpenAPI specification is located in docs/swagger.yaml.

Local Viewing

To view the documentation locally:

1. Open the docs/index.html file in your browser

2. Or use any OpenAPI viewer to view docs/swagger.yaml

Publishing to GitHub Pages

The documentation is automatically published to GitHub Pages on every commit to the main or master branch.

Documentation URL: https://unigox.github.io/api/

For manual deployment:

1. Make sure GitHub Pages is enabled in repository settings (Settings → Pages)

2. Select source: "GitHub Actions"

3. On the next commit to docs/ or .github/workflows/docs.yml, the documentation will automatically update

Updating Documentation

When changing the API:

1. Update the docs/swagger.yaml file

2. Commit the changes

3. GitHub Actions will automatically deploy the updated documentation

Usage Examples

Get Currency Rates

curl "http://localhost:8080/api/v1/rates?base=USD&quote=BTC,ETH"

Convert Currency

curl "http://localhost:8080/api/v1/currency/convert?from=USD&to=EUR&amount=100"

Get Payment Methods List

curl "http://localhost:8080/api/v1/payment-methods"

Get Payment Methods for USD

curl "http://localhost:8080/api/v1/payment-methods/by-fiat/USD"

Development

The project follows the go-default-layout architecture:

• models - data models

• repository - data access layer

• service - business logic

• handler - HTTP handlers

Logging is performed through zap logger only at the handler level.

E2E Testing

See E2E_TESTING.md for the full end-to-end testing guide covering all Partner API flows across services (user creation, KYC, payment details, offramp, etc.).