External API Integrations

This document describes all external third-party APIs integrated into the GitiNext platform.

🌐 Integration Overview

The system integrates with 7 major external APIs:

Service Purpose Environment Documentation
Exonyx Blockchain operations Production Details
Paystar payment gateway Production Details
FinnoTech banking API Production Details
PS Voucher Gaming vouchers Production Details
HOT Voucher Hot wallet vouchers Production Details
UTOPIA UUSD cryptocurrency vouchers Production Details
CoinGecko/CMC Crypto price data Production Details

1. Exonyx Blockchain API

Overview

Exonyx provides blockchain wallet operations for TRX, USDT, BNB.

Base URL

Production: https://api.exonyxco.com/api/v1/reseller

Authentication

Header: apiKey: YOUR_API_KEY

Key Endpoints

Create Wallet

POST /wallet/create
Content-Type: application/json

{
  "network": "TRC-20",
  "currency": "USDT"
}

Response: {
  "address": "TK4AiQNMzH4WMUVg...",
  "publicKey": "...",
  "success": true
}

Get Balance

GET /wallet/balance?address=TK4Ai...&network=TRC-20&currency=USDT

Response: {
  "balance": "1000.500000",
  "currency": "USDT",
  "network": "TRC-20"
}

Send Transaction

POST /transaction/send
Content-Type: application/json

{
  "from": "TK4Ai...",
  "to": "TR7NH...",
  "amount": "100.50",
  "network": "TRC-20",
  "currency": "USDT",
  "privateKey": "..."
}

Response: {
  "txHash": "0xabc...",
  "success": true
}

Webhook

POST https://your-domain.com/webhooks/blockchain
Content-Type: application/json

{
  "type": "deposit",
  "address": "TK4Ai...",
  "amount": "100.50",
  "txHash": "0xabc...",
  "confirmations": 19,
  "network": "TRC-20",
  "currency": "USDT"
}

Rate Limits

  • 100 requests/minute
  • Burst: 150 requests

Error Handling

// Implement retry with backoff
client := &ExonyxClient{
    BaseURL: "https://api.exonyxco.com/api/v1/reseller",
    APIKey: os.Getenv("EXONYX_API_KEY"),
    HTTPClient: &http.Client{
        Timeout: 30 * time.Second,
    },
    CircuitBreaker: NewCircuitBreaker(),
}

Node.js Reference

Location: gitibot-back-main/services/blockchainService.js
Methods: createWallet(), getBalance(), sendTransaction()

2. Paystar Payment Gateway

Overview

Paystar handles Toman deposits and withdrawals via cards and IBAN.

Base URL

Production: https://core.paystar.ir/api/pardakht/

Authentication

Header: Authorization: Bearer YOUR_API_KEY
Header: X-Paystar-Secret: YOUR_SECRET_KEY

Key Endpoints

Create Payment (Deposit)

POST /payment
Content-Type: application/json

{
  "amount": 1000000,  // In Rial (100,000 Toman)
  "orderId": "unique-order-id",
  "callbackUrl": "https://your-domain.com/callback/paystar",
  "description": "Deposit to wallet"
}

Response: {
  "status": 1,
  "token": "payment-token",
  "url": "https://core.paystar.ir/payment/redirect/..."
}

Verify Payment

POST /verify
Content-Type: application/json

{
  "ref_num": "123456",
  "amount": 1000000
}

Response: {
  "status": 1,
  "card_number": "6037-99**-****-1234",
  "transaction_id": "...",
  "tracking_code": "..."
}

Create Payout (Withdrawal)

POST /payout
Content-Type: application/json

{
  "amount": 500000,
  "dest_card": "6037991234567890",
  "description": "Withdrawal from wallet"
}

Response: {
  "status": 1,
  "tracking_code": "...",
  "id": "payout-id"
}

Webhook

POST https://your-domain.com/callback/paystar
Content-Type: application/x-www-form-urlencoded

ref_num=123456&status=1&amount=1000000&card_number=6037...&tracking_code=...

Rate Limits

  • 50 requests/minute
  • Burst: 100 requests

Node.js Reference

Location: gitibot-back-main/services/paymentProvider/paystar.js
Methods: createPayment(), verifyPayment(), createPayout()

3. FinnoTech Banking API

Overview

FinnoTech provides direct banking integration (IBAN, card verification).

Base URL

Production: https://apibeta.finnotech.ir/
Or via Proxy: Configured in environment

Authentication

OAuth 2.0 with client credentials
Requires proxy for some endpoints

Key Features

  • IBAN deposit tracking
  • Card verification
  • Bank account inquiry
  • Transaction confirmation

Proxy Support

// FinnoTech may require proxy in production
client := &FinnoTechClient{
    BaseURL: os.Getenv("FINNOTECH_BASE_URL"),
    UseProxy: os.Getenv("USE_FINNOTECH_PROXY") == "true",
    ProxyURL: os.Getenv("FINNOTECH_PROXY_URL"),
}

Node.js Reference

Location: gitibot-back-main/services/finnotechService.js
Location: gitibot-back-main/services/finnotechProxyClient.js

4. PS Voucher API

Overview

Premium Service vouchers for gaming platforms.

Authentication

API Key + Secret Key

Key Operations

  • Buy voucher
  • Sell voucher
  • Check voucher status
  • Get voucher info

Node.js Reference

Location: gitibot-back-main/bot/ps_voucher.js
Methods: buyVoucher(), sellVoucher(), getVoucherInfo()

5. HOT Voucher API

Overview

Hot wallet voucher integration.

Authentication

Security key in headers

Node.js Reference

Location: gitibot-back-main/bot/hot_voucher.js

6. UTOPIA Voucher API

Overview

UUSD cryptocurrency vouchers with human-readable codes (USD-XXXX-XXXX).

Authentication

Token + Card ID

Features

  • Buy UUSD vouchers
  • Sell vouchers
  • Human-readable voucher codes
  • Balance increase tracking

Node.js Reference

Location: gitibot-back-main/bot/utopia_voucher.js
Methods: buyVoucher(), sellVoucher()

7. Price APIs

CoinGecko

Base URL: https://api.coingecko.com/api/v3/
Auth: API Key (optional for free tier)
Rate Limit: 10-50 calls/min

Endpoints:

  • /simple/price - Current prices
  • /coins/markets - Market data
  • /coins/{id}/market_chart - Historical data

CoinMarketCap

Base URL: https://pro-api.coinmarketcap.com/v1/
Auth: X-CMC_PRO_API_KEY header
Rate Limit: Based on plan

Nobitex (Toman Prices)

Base URL: https://api.nobitex.ir/
Auth: None required for public endpoints

Endpoints:

  • /market/stats - Toman prices for market

🛠️ Implementation Pattern

Standard HTTP Client:

type ExternalAPIClient struct {
    BaseURL        string
    APIKey         string
    HTTPClient     *http.Client
    CircuitBreaker *CircuitBreaker
    RateLimiter    *RateLimiter
    Logger         *zap.Logger
}

func (c *ExternalAPIClient) Do(req *http.Request) (*http.Response, error) {
    // Add authentication
    req.Header.Set("apiKey", c.APIKey)

    // Check circuit breaker
    if c.CircuitBreaker.IsOpen() {
        return nil, ErrCircuitOpen
    }

    // Check rate limit
    if !c.RateLimiter.Allow() {
        return nil, ErrRateLimited
    }

    // Execute request with retry
    resp, err := c.retryWithBackoff(req)
    if err != nil {
        c.CircuitBreaker.RecordFailure()
        return nil, err
    }

    c.CircuitBreaker.RecordSuccess()
    return resp, nil
}

📊 Monitoring

Each integration should expose metrics:

external_api_requests_total{service, endpoint, status}
external_api_request_duration_seconds{service, endpoint}
external_api_errors_total{service, endpoint, error_type}
circuit_breaker_state{service}  # open, closed, half-open
rate_limit_exceeded_total{service}

🔗 References

© 2025 GitiNext - Enterprise Crypto Infrastructure | GitHub | Website