Gateway REST API

Overview

The Gateway is the single HTTP entry point for clients (Telegram Mini App, Admin Panel, TWA). It exposes REST endpoints and proxies to internal services (Wallet, Account, Market, Payment, Withdrawal, etc.).

Base URL (production): https://api.nextgiti.cloud

Authentication

Most endpoints require authentication via Telegram or JWT:

Mini App / TWA: X-Telegram-Id header (and optionally init data validation).
Admin: Bearer JWT or session cookie.

flowchart LR
  A[Client] -->|X-Telegram-Id / Bearer| B[Gateway]
  B --> C{Auth Middleware}
  C -->|Valid| D[Route to Service]
  C -->|Invalid| E[401 Unauthorized]

Key Endpoints

Area	Path prefix	Description
Auth	`/api/v1/auth/telegram/*`	Telegram login, verify, callback
Identity	`/api/v1/identity/*`	Level ¹⁄₂ verification, status
Card	`/api/v1/card/*`	Card verification, list, deposit info
Wallet	`/api/v1/wallet/*`	Balances, assets, addresses
Fiat	`/api/v1/fiat/deposit/*`	IRT deposit info
Withdrawal	`/api/v1/withdrawal/*`	Crypto/IRT withdrawal
Swap	`/api/v1/swap/*`	Swap balances, quote
Market	`/api/v1/market/*`	Prices, tickers (proxied)
Notifications	`/api/v1/notifications/*`	List, preferences

OpenAPI (Swagger)

Interactive API documentation is available at:

Swagger UI: https://api.nextgiti.cloud/swagger/
Gateway API JSON: https://api.nextgiti.cloud/static/gateway-api.json

Use the Swagger UI to explore request/response schemas and try calls.

Health

Liveness: GET /healthz — returns 200 when the gateway is up.
Readiness: Same endpoint; consider separate /ready if dependencies are checked.

Flow: Request to Internal Service

sequenceDiagram
  participant C as Client
  participant G as Gateway
  participant S as Internal Service

  C->>G: GET /api/v1/wallet/balance (X-Telegram-Id)
  G->>G: Auth middleware
  G->>S: gRPC or HTTP to wallet:7080
  S->>G: Balance response
  G->>C: JSON 200