Admin gRPC API

Административный gRPC-сервис предоставляет инструменты для управления платформой: работы с аккаунтами пользователей, ручных финансовых операций, мониторинга блокчейн-активности, управления алертами и горячими кошельками.

Сервис доступен только во внутренней сети. Прямой доступ из интернета закрыт.

Всего определено 11 sub-сервисов.

---

Общие типы

// Пагинация для list-запросов
message PageRequest {
  int32 limit  = 1;
  int32 offset = 2;
}

message PageResponse {
  int32 total = 1;
}

// Универсальный тип для денежных сумм
message Amount {
  string value = 1; // decimal-строка, например "0.00123456"
  string asset = 2; // код актива, например "BTC"
}

---

1. PingService

Используется для проверки доступности сервиса.

service PingService {
  rpc Ping(PingRequest) returns (PingResponse);
}

message PingRequest {}

message PingResponse {
  string status = 1; // "ok"
}

---

2. AccountsService

Управление аккаунтами пользователей: просмотр балансов, изменение тарифа и статуса.

service AccountsService {
  rpc GetBalances(GetBalancesRequest) returns (GetBalancesResponse);
  rpc GetAccountDetails(GetAccountDetailsRequest) returns (GetAccountDetailsResponse);
  rpc SetTier(SetTierRequest) returns (SetTierResponse);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc ChangeAccountStatus(ChangeAccountStatusRequest) returns (ChangeAccountStatusResponse);
}

// --- GetBalances ---
message GetBalancesRequest {
  string account_id = 1;
}

message GetBalancesResponse {
  repeated Balance balances = 1;
}

message Balance {
  string asset             = 1;
  string available         = 2; // decimal
  string locked            = 3; // decimal
  string balance_account_id = 4;
  string balance_account_type = 5; // "funding" | "trading"
}

// --- GetAccountDetails ---
message GetAccountDetailsRequest {
  string account_id = 1;
}

message GetAccountDetailsResponse {
  string   id                 = 1;
  string   email              = 2;
  string   status             = 3; // "active" | "restricted" | "blocked"
  string   tier_id            = 4;
  string   tier_name          = 5;
  string   master_account_id  = 6; // пусто, если не субаккаунт
  string   created_at         = 7; // ISO 8601
}

// --- SetTier ---
message SetTierRequest {
  string account_id = 1;
  string tier_id    = 2;
}

message SetTierResponse {
  bool success = 1;
}

// --- ListOrders ---
message ListOrdersRequest {
  string      account_id = 1;
  string      ticker     = 2; // опционально
  string      status     = 3; // опционально
  PageRequest page       = 4;
}

message ListOrdersResponse {
  repeated AdminOrder orders = 1;
  PageResponse        page   = 2;
}

message AdminOrder {
  string id                  = 1;
  string ticker              = 2;
  string side                = 3; // "buy" | "sell"
  string type                = 4; // "limit" | "market"
  string price               = 5;
  string qty                 = 6;
  string filled_qty          = 7;
  string status              = 8;
  string created_at          = 9;
}

// --- ChangeAccountStatus ---
message ChangeAccountStatusRequest {
  string account_id = 1;
  string status     = 2; // "active" | "restricted" | "blocked"
  string reason     = 3;
}

message ChangeAccountStatusResponse {
  bool success = 1;
}

---

3. BlockchainService

Блокчейн-операции: депозитные адреса, инициирование выводов, просмотр истории.

service BlockchainService {
  rpc GetDepositAddress(GetDepositAddressRequest) returns (GetDepositAddressResponse);
  rpc WithdrawToBlockchain(WithdrawToBlockchainRequest) returns (WithdrawToBlockchainResponse);
  rpc GetWithdrawRequestStatus(GetWithdrawRequestStatusRequest) returns (GetWithdrawRequestStatusResponse);
  rpc ListTopUps(ListTopUpsRequest) returns (ListTopUpsResponse);
  rpc ListAllTopUps(ListAllTopUpsRequest) returns (ListAllTopUpsResponse);
  rpc ListWithdrawals(ListWithdrawalsRequest) returns (ListWithdrawalsResponse);
}

// --- GetDepositAddress ---
message GetDepositAddressRequest {
  string account_id  = 1;
  string blockchain  = 2; // "btc" | "eth" | "tron"
  string asset       = 3;
}

message GetDepositAddressResponse {
  string address = 1;
}

// --- WithdrawToBlockchain ---
message WithdrawToBlockchainRequest {
  string account_id  = 1;
  string blockchain  = 2;
  string asset       = 3;
  string amount      = 4; // decimal
  string to_address  = 5;
  string memo        = 6; // опционально (для Tron/EVM токенов с memo)
}

message WithdrawToBlockchainResponse {
  string withdraw_request_id = 1;
}

// --- GetWithdrawRequestStatus ---
message GetWithdrawRequestStatusRequest {
  string withdraw_request_id = 1;
}

message GetWithdrawRequestStatusResponse {
  string status  = 1; // "pending" | "processing" | "broadcast" | "confirmed" | "failed"
  string tx_hash = 2;
}

// --- ListTopUps ---
message ListTopUpsRequest {
  string      account_id = 1;
  PageRequest page       = 2;
}

message ListTopUpsResponse {
  repeated TopUp topups = 1;
  PageResponse   page   = 2;
}

// --- ListAllTopUps ---
message ListAllTopUpsRequest {
  string      blockchain = 1; // опционально
  string      status     = 2; // опционально
  PageRequest page       = 3;
}

message ListAllTopUpsResponse {
  repeated TopUp topups = 1;
  PageResponse   page   = 2;
}

message TopUp {
  string id          = 1;
  string account_id  = 2;
  string blockchain  = 3;
  string asset       = 4;
  string amount      = 5; // decimal
  string tx_hash     = 6;
  string status      = 7;
  string detected_at = 8; // ISO 8601
}

// --- ListWithdrawals ---
message ListWithdrawalsRequest {
  string      account_id = 1; // опционально (все аккаунты, если пусто)
  string      status     = 2; // опционально
  PageRequest page       = 3;
}

message ListWithdrawalsResponse {
  repeated Withdrawal withdrawals = 1;
  PageResponse        page        = 2;
}

message Withdrawal {
  string id         = 1;
  string account_id = 2;
  string blockchain = 3;
  string asset      = 4;
  string amount     = 5;
  string to_address = 6;
  string tx_hash    = 7;
  string status     = 8;
  string created_at = 9;
}

---

4. OperationsService

Ручные финансовые операции: зачисление, списание, переводы — как по аккаунту, так и по конкретному балансовому аккаунту.

service OperationsService {
  rpc ManualTopup(ManualTopupRequest) returns (ManualTopupResponse);
  rpc ManualWithdraw(ManualWithdrawRequest) returns (ManualWithdrawResponse);
  rpc Transfer(TransferRequest) returns (TransferResponse);
  rpc ManualTopupBalanceAccount(ManualTopupBalanceAccountRequest) returns (ManualTopupBalanceAccountResponse);
  rpc ManualWithdrawBalanceAccount(ManualWithdrawBalanceAccountRequest) returns (ManualWithdrawBalanceAccountResponse);
  rpc TransferBalanceAccount(TransferBalanceAccountRequest) returns (TransferBalanceAccountResponse);
}

// --- ManualTopup ---
message ManualTopupRequest {
  string account_id = 1;
  string asset      = 2;
  string amount     = 3; // decimal
  string reason     = 4;
}

message ManualTopupResponse {
  string operation_id = 1;
}

// --- ManualWithdraw ---
message ManualWithdrawRequest {
  string account_id = 1;
  string asset      = 2;
  string amount     = 3;
  string reason     = 4;
}

message ManualWithdrawResponse {
  string operation_id = 1;
}

// --- Transfer (между аккаунтами) ---
message TransferRequest {
  string from_account_id = 1;
  string to_account_id   = 2;
  string asset           = 3;
  string amount          = 4;
  string reason          = 5;
}

message TransferResponse {
  string operation_id = 1;
}

// --- ManualTopupBalanceAccount ---
message ManualTopupBalanceAccountRequest {
  string balance_account_id = 1;
  string asset              = 2;
  string amount             = 3;
  string reason             = 4;
}

message ManualTopupBalanceAccountResponse {
  string operation_id = 1;
}

// --- ManualWithdrawBalanceAccount ---
message ManualWithdrawBalanceAccountRequest {
  string balance_account_id = 1;
  string asset              = 2;
  string amount             = 3;
  string reason             = 4;
}

message ManualWithdrawBalanceAccountResponse {
  string operation_id = 1;
}

// --- TransferBalanceAccount ---
message TransferBalanceAccountRequest {
  string from_balance_account_id = 1;
  string to_balance_account_id   = 2;
  string asset                   = 3;
  string amount                  = 4;
  string reason                  = 5;
}

message TransferBalanceAccountResponse {
  string operation_id = 1;
}

---

5. InfoService

Справочная информация: тарифы и сети.

service InfoService {
  rpc ListTiers(ListTiersRequest) returns (ListTiersResponse);
  rpc ListNetworks(ListNetworksRequest) returns (ListNetworksResponse);
}

message ListTiersRequest {}

message ListTiersResponse {
  repeated Tier tiers = 1;
}

message Tier {
  string id     = 1;
  string name   = 2;
  string limits = 3; // JSON-строка с лимитами и комиссиями
}

message ListNetworksRequest {
  string asset = 1; // опционально — фильтр по активу
}

message ListNetworksResponse {
  repeated Network networks = 1;
}

message Network {
  string id               = 1;
  string asset            = 2;
  string network          = 3;
  bool   deposit_enabled  = 4;
  bool   withdraw_enabled = 5;
}

---

6. AlertsService

Создание, получение и обработка системных алертов.

service AlertsService {
  rpc Create(CreateAlertRequest) returns (CreateAlertResponse);
  rpc List(ListAlertsRequest) returns (stream Alert);
  rpc Acknowledge(AcknowledgeAlertRequest) returns (AcknowledgeAlertResponse);
  rpc Resolve(ResolveAlertRequest) returns (ResolveAlertResponse);
}

message CreateAlertRequest {
  string type     = 1; // "aml_hit" | "large_withdrawal" | "system_error" | ...
  string severity = 2; // "info" | "warning" | "critical"
  string payload  = 3; // JSON-строка с деталями
}

message CreateAlertResponse {
  string alert_id = 1;
}

message ListAlertsRequest {
  string status   = 1; // опционально: "open" | "acknowledged" | "resolved"
  string severity = 2; // опционально
}

// List возвращает server-streaming поток алертов
message Alert {
  string id          = 1;
  string type        = 2;
  string severity    = 3;
  string payload     = 4;
  string status      = 5;
  string created_at  = 6;
  string resolved_at = 7;
}

message AcknowledgeAlertRequest {
  string alert_id = 1;
  string comment  = 2;
}

message AcknowledgeAlertResponse {
  bool success = 1;
}

message ResolveAlertRequest {
  string alert_id    = 1;
  string resolution  = 2;
}

message ResolveAlertResponse {
  bool success = 1;
}

---

7. APIKeysService

Управление API-ключами пользователей (создание, просмотр, удаление).

service APIKeysService {
  rpc CreateAPIKey(CreateAPIKeyRequest) returns (CreateAPIKeyResponse);
  rpc ListAPIKeys(ListAPIKeysRequest) returns (ListAPIKeysResponse);
  rpc DeleteAPIKey(DeleteAPIKeyRequest) returns (DeleteAPIKeyResponse);
}

message CreateAPIKeyRequest {
  string   account_id   = 1;
  repeated string permissions = 2; // ["trade", "withdraw", "read"]
  string   label        = 3;
}

message CreateAPIKeyResponse {
  string api_key    = 1; // публичный ключ
  string api_secret = 2; // секрет (показывается только при создании!)
  string id         = 3;
}

message ListAPIKeysRequest {
  string account_id = 1;
}

message ListAPIKeysResponse {
  repeated APIKey keys = 1;
}

message APIKey {
  string          id          = 1;
  string          label       = 2;
  repeated string permissions = 3;
  string          created_at  = 4;
  string          last_used_at = 5;
}

message DeleteAPIKeyRequest {
  string key_id = 1;
}

message DeleteAPIKeyResponse {
  bool success = 1;
}

---

8. HotWalletsService

Управление горячими кошельками биржи: просмотр и переводы между кошельками.

service HotWalletsService {
  rpc ListHotWallets(ListHotWalletsRequest) returns (ListHotWalletsResponse);
  rpc TransferAsset(TransferAssetRequest) returns (TransferAssetResponse);
  rpc GetTransferAssetStatus(GetTransferAssetStatusRequest) returns (GetTransferAssetStatusResponse);
}

message ListHotWalletsRequest {
  string blockchain = 1; // опционально
}

message ListHotWalletsResponse {
  repeated HotWallet wallets = 1;
}

message HotWallet {
  string address    = 1;
  string blockchain = 2;
  string asset      = 3;
  string balance    = 4; // текущий баланс в блокчейне
}

message TransferAssetRequest {
  string from_address = 1;
  string to_address   = 2;
  string blockchain   = 3;
  string asset        = 4;
  string amount       = 5; // decimal
}

message TransferAssetResponse {
  string transfer_id = 1;
}

message GetTransferAssetStatusRequest {
  string transfer_id = 1;
}

message GetTransferAssetStatusResponse {
  string status  = 1; // "pending" | "broadcast" | "confirmed" | "failed"
  string tx_hash = 2;
}

---

9. TiersService

Управление тарифными уровнями платформы.

service TiersService {
  rpc CreateTier(CreateTierRequest) returns (CreateTierResponse);
  rpc UpdateTier(UpdateTierRequest) returns (UpdateTierResponse);
  rpc DeleteTier(DeleteTierRequest) returns (DeleteTierResponse);
  rpc GetDefaultTier(GetDefaultTierRequest) returns (GetDefaultTierResponse);
  rpc SetDefaultTier(SetDefaultTierRequest) returns (SetDefaultTierResponse);
}

message CreateTierRequest {
  string name   = 1;
  string limits = 2; // JSON
}

message CreateTierResponse {
  string tier_id = 1;
}

message UpdateTierRequest {
  string tier_id = 1;
  string name    = 2;
  string limits  = 3;
}

message UpdateTierResponse {
  bool success = 1;
}

message DeleteTierRequest {
  string tier_id = 1;
}

message DeleteTierResponse {
  bool success = 1;
}

message GetDefaultTierRequest {}

message GetDefaultTierResponse {
  string tier_id   = 1;
  string tier_name = 2;
}

message SetDefaultTierRequest {
  string tier_id = 1;
}

message SetDefaultTierResponse {
  bool success = 1;
}

---

10. AssetsService

Управление активами (криптовалютами и токенами).

service AssetsService {
  rpc CreateAsset(CreateAssetRequest) returns (CreateAssetResponse);
  rpc UpdateAsset(UpdateAssetRequest) returns (UpdateAssetResponse);
  rpc SetAssetActive(SetAssetActiveRequest) returns (SetAssetActiveResponse);
  rpc AddAssetNetwork(AddAssetNetworkRequest) returns (AddAssetNetworkResponse);
  rpc UpdateAssetNetwork(UpdateAssetNetworkRequest) returns (UpdateAssetNetworkResponse);
}

message CreateAssetRequest {
  string code     = 1;
  string name     = 2;
  int32  decimals = 3;
}

message CreateAssetResponse {
  bool success = 1;
}

message UpdateAssetRequest {
  string code = 1;
  string name = 2;
}

message UpdateAssetResponse {
  bool success = 1;
}

message SetAssetActiveRequest {
  string code   = 1;
  bool   active = 2;
}

message SetAssetActiveResponse {
  bool success = 1;
}

message AddAssetNetworkRequest {
  string asset            = 1;
  string network          = 2;
  bool   deposit_enabled  = 3;
  bool   withdraw_enabled = 4;
}

message AddAssetNetworkResponse {
  string network_id = 1;
}

message UpdateAssetNetworkRequest {
  string network_id       = 1;
  bool   deposit_enabled  = 2;
  bool   withdraw_enabled = 3;
}

message UpdateAssetNetworkResponse {
  bool success = 1;
}

---

11. TickersService

Управление торговыми парами.

service TickersService {
  rpc CreateTicker(CreateTickerRequest) returns (CreateTickerResponse);
  rpc SetTickerActive(SetTickerActiveRequest) returns (SetTickerActiveResponse);
  rpc ListTickers(ListTickersRequest) returns (ListTickersResponse);
}

message CreateTickerRequest {
  string symbol      = 1; // например "BTC-USDT"
  string base_asset  = 2;
  string quote_asset = 3;
}

message CreateTickerResponse {
  bool success = 1;
}

message SetTickerActiveRequest {
  string symbol = 1;
  bool   active = 2;
}

message SetTickerActiveResponse {
  bool success = 1;
}

message ListTickersRequest {
  bool include_inactive = 1;
}

message ListTickersResponse {
  repeated AdminTicker tickers = 1;
}

message AdminTicker {
  string symbol      = 1;
  string base_asset  = 2;
  string quote_asset = 3;
  bool   active      = 4;
}

---

Коды статусов gRPC

Код	Название	Описание
0	OK	Успешно
3	INVALID_ARGUMENT	Неверные параметры запроса
5	NOT_FOUND	Ресурс не найден
6	ALREADY_EXISTS	Ресурс уже существует
7	PERMISSION_DENIED	Недостаточно прав
13	INTERNAL	Внутренняя ошибка сервера
14	UNAVAILABLE	Сервис временно недоступен