Documentation

Getting Started

QuasarFlow API provides a simple REST interface to the Stellar network, eliminating the need to learn complex blockchain protocols. Build blockchain-powered applications using familiar HTTP requests.

Key Benefits

• Simple REST API - No blockchain SDK learning curve
• Enterprise Security - JWT authentication, rate limiting, and comprehensive security headers
• Secure by default - AES-256-GCM encryption for private keys
• External Wallet Support - Verify ownership of existing Stellar wallets using SEP-10 standards
• Production ready - Built with enterprise-grade architecture and security
• Well documented - Clear API specifications and examples

Quick Start

Docker (Recommended)

1# Clone and setup
2git clone https://github.com/QuasarAPI/quasarflow-api.git
3cd quasarflow-api
4
5# Setup environment
6cp .env.example .env
7nano .env  # customize settings
8
9# Start all services
10docker-compose up -d
11
12# View logs
13docker-compose logs -f quasarflow-api

Manual Setup

1# Prerequisites: Go 1.21+, PostgreSQL 12+
2git clone https://github.com/QuasarAPI/quasarflow-api.git
3cd quasarflow-api
4go mod download
5
6# Setup database
7createdb quasarflow
8./scripts/db-manage.sh migrate-up
9
10# Configure and run
11cp .env.example .env
12go run ./cmd/api/main.go

Quick Example

1# 1. Login and get token
2TOKEN=$(curl -s -X POST https://quasarflow.dev/api/auth/login \
3  -H "Content-Type: application/json" \
4  -d '{"username": "admin", "password": "admin123"}' | jq -r '.data.token')
5
6# 2. Create a wallet
7WALLET_ID=$(curl -s -X POST https://quasarflow.dev/api/v1/wallets \
8  -H "Content-Type: application/json" \
9  -H "Authorization: Bearer $TOKEN" \
10  -d '{"network": "testnet"}' | jq -r '.data.id')
11
12# 3. Fund wallet (development only)
13curl -X POST https://quasarflow.dev/api/v1/wallets/$WALLET_ID/fund \
14  -H "Authorization: Bearer $TOKEN"
15
16# 4. Check balance
17curl https://quasarflow.dev/api/v1/wallets/$WALLET_ID/balance \
18  -H "Authorization: Bearer $TOKEN"

Authentication

QuasarFlow API uses JWT (JSON Web Tokens) for authentication. All protected endpoints require a valid JWT token in the Authorization header.

Authentication Flow

1. Login with credentials → Receive JWT token
2. Include token in Authorization: Bearer <token> header
3. Access protected endpoints with valid token

Login Example

1curl -X POST https://quasarflow.dev/api/auth/login \
2  -H "Content-Type: application/json" \
3  -d '{
4    "username": "admin",
5    "password": "admin123"
6  }'
7
8# Response
9{
10  "success": true,
11  "data": {
12    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
13    "expires_at": "2024-01-01T12:00:00Z"
14  }
15}

Wallet Management

QuasarFlow handles all the complexity of blockchain wallet management, including key generation, encryption, and secure storage.

Create Wallet

1curl -X POST https://quasarflow.dev/api/v1/wallets \
2  -H "Authorization: Bearer YOUR_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "network": "testnet"
6  }'
7
8# Response
9{
10  "success": true,
11  "data": {
12    "id": "wallet_123",
13    "public_key": "GABC123...",
14    "network": "testnet",
15    "created_at": "2024-01-01T12:00:00Z"
16  }
17}

Check Balance

1curl https://quasarflow.dev/api/v1/wallets/wallet_123/balance \
2  -H "Authorization: Bearer YOUR_TOKEN"
3
4# Response
5{
6  "success": true,
7  "data": {
8    "balances": [
9      {
10        "asset": "XLM",
11        "amount": "1000.0000000"
12      }
13    ]
14  }
15}

Send Payment

curl -X POST https://quasarflow.dev/api/v1/wallets/wallet_123/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "GDEF456...",
    "amount": "10.5",
    "asset": "XLM",
    "memo": "Payment for services"
  }'

# Response
{
  "success": true,
  "data": {
    "transaction_hash": "abc123...",
    "status": "pending"
  }
}

External Wallet Support

QuasarFlow API supports users with existing Stellar wallets through ownership verification. Users can prove they own a wallet without registering with the platform.

Supported Verification Methods

• 🔐 Message Signing (SEP-10) - Cryptographically sign a challenge
• 📝 Transaction Proof - Use recent signed transactions as proof
• 📊 Account Activity - Verify based on account existence and activity

Verify Existing Wallet

# 1. Generate challenge for wallet
CHALLENGE=$(curl -s https://quasarflow.dev/api/v1/accounts/GABC123.../challenge | jq -r '.challenge')

# 2. Sign challenge with private key (client-side)
# This requires a Stellar SDK implementation in your application
SIGNATURE="base64_encoded_signature"

# 3. Verify ownership
curl -X POST https://quasarflow.dev/api/v1/accounts/GABC123.../verify-ownership \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "'$SIGNATURE'",
    "message": "'$CHALLENGE'"
  }'

# 4. Alternative: Verify via recent transaction
curl -X POST https://quasarflow.dev/api/v1/accounts/GABC123.../verify-transaction \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_hash": "transaction_hash_here"
  }'

Configuration

Environment Setup

# Copy and customize environment file
cp .env.example .env
nano .env  # Edit with your settings

Key Variables

Network Modes

• Local: Docker Stellar network + Friendbot for testing
• Testnet: Stellar testnet for staging
• Mainnet: Production Stellar network

Architecture

QuasarFlow API follows Clean Architecture principles for maintainability and testability.

┌─────────────────────────────────────────┐
│             HTTP Layer                  │
│    (REST API, Middleware, Routing)     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           Use Case Layer                │
│      (Business Logic & Rules)          │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│           Domain Layer                  │
│     (Entities & Interfaces)            │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│        Infrastructure Layer             │
│  (Database, Stellar Client, Crypto)    │
└─────────────────────────────────────────┘

Architecture Benefits

• Testability - Easy to unit test business logic
• Flexibility - Simple to swap implementations
• Maintainability - Clear separation of concerns

Project Structure

quasarflow-api/
├── .cursor/rules/              # Cursor IDE rules
├── cmd/api/                    # Application entry point
├── docs/                       # API documentation
├── internal/                   # Private application code
│   ├── config/                 # Configuration management
│   ├── domain/                 # Business entities & interfaces
│   ├── infrastructure/         # Database, Stellar, Crypto
│   ├── interface/http/         # REST API, Handlers, Middleware
│   └── usecase/               # Business logic
├── migrations/                 # Database schema migrations
├── pkg/                       # Shared utilities
├── scripts/                   # Build and deployment scripts
├── .dockerignore              # Docker ignore file
├── .env.example               # Environment variables template
├── .gitignore                 # Git ignore file
├── Dockerfile                 # Docker container definition
├── LICENSE                    # MIT License
├── README.md                  # Project documentation
├── api                        # API specification
├── docker-compose.yml         # Docker services configuration
├── go.mod                     # Go module definition
└── go.sum                     # Go module checksums

Technology Stack

• Go 1.21+ - High-performance backend language (72.2% of codebase)
• PostgreSQL - Reliable data persistence
• Stellar Network - Fast, low-cost blockchain
• Docker - Containerization and deployment
• Shell Scripts - Build and deployment automation (26.9% of codebase)
• Clean Architecture - Maintainable, testable codebase

Repository Statistics

Current Features

• ✅ Wallet creation and management
• ✅ Secure private key storage (AES-256-GCM)
• ✅ Payment transactions (XLM and custom assets)
• ✅ Multi-network support (local, testnet, mainnet)
• ✅ JWT Authentication & Enterprise Security
• ✅ Docker development environment

Roadmap

• Multi-signature wallet support
• Webhook notification system
• Database user management
• Advanced role-based permissions
• Support for additional blockchains
• Advanced transaction types (escrow, atomic swaps)
• Analytics and reporting dashboard
• SDKs for popular languages