Balance & Transactions Endpoints

Аудитория: разработчики, frontend-инженеры Последнее обновление: 2025-11-17 Краткое содержание: Детальная документация Balance и Transaction endpoints — получение баланса USDC, история транзакций, детали операций. Полные примеры интеграции для financial dashboards.

---

Обзор Endpoints

Метод	Endpoint	Описание	Auth требуется
GET	/api/user/balance	Получить текущий баланс USDC	✅ Да
GET	/api/user/transactions	Список истории транзакций	✅ Да
GET	/api/user/transactions/:id	Получить детали транзакции	✅ Да

---

GET /api/user/balance

Получить текущий баланс USDC аутентифицированного пользователя (available + invested).

Запрос

GET /api/user/balance
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Заголовки:

Заголовок	Значение	Обязательно	Описание
Authorization	Bearer <token>	✅ Да	User JWT токен

Query параметры: Нет

Ответ

Успех (200 OK):

{
  "success": true,
  "data": {
    "total": "5000.00",
    "available": "2500.00",
    "invested": "2500.00",
    "currency": "USDC",
    "breakdown": {
      "deposits": "5000.00",
      "withdrawals": "0.00",
      "earnings": "150.50",
      "fees": "10.00"
    },
    "investments": [
      {
        "strategyId": "balanced-10",
        "amount": "1500.00",
        "currentValue": "1575.25",
        "apy": 10.0
      },
      {
        "strategyId": "conservative-5",
        "amount": "1000.00",
        "currentValue": "1025.00",
        "apy": 5.0
      }
    ],
    "updatedAt": "2025-10-03T12:34:56Z"
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
data.total	string	Общий баланс (available + invested), формат SafeDecimal
data.available	string	Доступный баланс для новых инвестиций/выводов
data.invested	string	Общая сумма инвестированная в стратегии
data.currency	string	Валюта (всегда "USDC")
data.breakdown.deposits	string	Всего депозитов за всё время
data.breakdown.withdrawals	string	Всего выводов за всё время
data.breakdown.earnings	string	Всего заработано на инвестициях
data.breakdown.fees	string	Всего заплачено комиссий платформы/gas
data.investments	array	Разбивка по активным стратегиям
data.updatedAt	string	Timestamp последнего обновления баланса

Логика расчёта:

total = available + invested
available = deposits - withdrawals - invested + earnings - fees
invested = sum(all active investments)

Ошибки:

Код статуса	Код ошибки	Описание
401	TOKEN_EXPIRED	JWT токен истёк
401	TOKEN_INVALID	Некорректная JWT подпись
404	USER_NOT_FOUND	Аккаунт пользователя не существует
503	BLOCKCHAIN_ERROR	Не удалось получить on-chain баланс

Пример cURL

TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET https://app.saga.surf/api/user/balance \
  -H "Authorization: Bearer $TOKEN"

Пример TypeScript

import { SagaClient } from '@saga/sdk';

const client = new SagaClient({
  baseUrl: 'https://app.saga.surf',
  jwt: localStorage.getItem('saga_auth_token')
});

const balanceData = await client.user.getBalance();

console.log('Общий баланс:', balanceData.total, 'USDC');
console.log('Доступно:', balanceData.available, 'USDC');
console.log('Инвестировано:', balanceData.invested, 'USDC');

balanceData.investments.forEach(inv => {
  console.log(`${inv.strategyId}: $${inv.amount} → $${inv.currentValue} (${inv.apy}% APY)`);
});

---

📜 GET /api/user/transactions

Получить постраничную историю транзакций для аутентифицированного пользователя.

Запрос

GET /api/user/transactions?page=1&limit=20&type=deposit&sortBy=createdAt&orderBy=desc
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Заголовки:

Заголовок	Значение	Обязательно	Описание
Authorization	Bearer <token>	✅ Да	User JWT токен

Query параметры:

Параметр	Тип	Обязательно	Описание	По умолчанию
page	number	❌ Нет	Номер страницы (с 1)	1
limit	number	❌ Нет	Элементов на странице (макс: 100)	20
type	string	❌ Нет	Фильтр по типу: deposit, withdrawal, investment, earning	Все типы
status	string	❌ Нет	Фильтр по статусу: pending, completed, failed	Все статусы
sortBy	string	❌ Нет	Поле сортировки: createdAt, amount	createdAt
orderBy	string	❌ Нет	Порядок сортировки: asc, desc	desc
startDate	string	❌ Нет	Фильтр от даты (ISO 8601)	-
endDate	string	❌ Нет	Фильтр до даты (ISO 8601)	-

Ответ

Успех (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "txn_abc123",
      "type": "deposit",
      "amount": "1000.00",
      "currency": "USDC",
      "status": "completed",
      "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "to": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
      "blockchainTxHash": "0xabcdef123456...",
      "blockNumber": 1234567,
      "gasUsed": "21000",
      "gasFee": "0.005",
      "createdAt": "2025-10-03T10:00:00Z",
      "completedAt": "2025-10-03T10:01:30Z",
      "metadata": {
        "description": "USDC deposit via MetaMask"
      }
    },
    {
      "id": "txn_def456",
      "type": "investment",
      "amount": "500.00",
      "currency": "USDC",
      "status": "completed",
      "strategyId": "balanced-10",
      "strategyName": "Balanced 10% APY",
      "createdAt": "2025-10-03T11:00:00Z",
      "completedAt": "2025-10-03T11:02:15Z",
      "metadata": {
        "description": "Investment in Balanced strategy (10% APY)"
      }
    },
    {
      "id": "txn_ghi789",
      "type": "earning",
      "amount": "5.50",
      "currency": "USDC",
      "status": "completed",
      "strategyId": "balanced-10",
      "createdAt": "2025-10-03T12:00:00Z",
      "completedAt": "2025-10-03T12:00:05Z",
      "metadata": {
        "description": "Daily yield from Balanced strategy",
        "period": "2025-10-02 to 2025-10-03"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 87,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Типы транзакций:

Тип	Описание	Знак суммы
deposit	Депозит USDC на платформу	+ (кредит)
withdrawal	Вывод USDC с платформы	- (дебет)
investment	Выделение капитала в стратегию	- (дебет available)
divestment	Возврат капитала из стратегии	+ (кредит available)
earning	Заработанная доходность	+ (кредит)
fee	Комиссия платформы или gas	- (дебет)

Статусы транзакций:

Статус	Описание	Финальный?
pending	Транзакция отправлена, ожидает подтверждения	❌ Нет
processing	On-chain транзакция подтверждается	❌ Нет
completed	Успешно завершена	✅ Да
failed	Транзакция провалилась или reverted	✅ Да
cancelled	Отменена пользователем до обработки	✅ Да

Поля ответа:

Поле	Тип	Описание
data[].id	string	Уникальный ID транзакции
data[].type	string	Тип транзакции (см. таблицу выше)
data[].amount	string	Сумма транзакции (SafeDecimal)
data[].status	string	Текущий статус
data[].blockchainTxHash	string	On-chain transaction hash (если применимо)
data[].createdAt	string	Timestamp создания транзакции
data[].completedAt	string	Timestamp завершения (если completed)
pagination	object	Метаданные пагинации

Ошибки:

Код статуса	Код ошибки	Описание
400	INVALID_DATE_RANGE	startDate > endDate
400	INVALID_PAGINATION	page < 1 или limit > 100
401	TOKEN_EXPIRED	JWT токен истёк

Пример cURL

TOKEN="eyJhbGciOiJIUzI1NiIs..."

# Получить последние депозиты
curl -X GET "https://app.saga.surf/api/user/transactions?type=deposit&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Получить транзакции в диапазоне дат
curl -X GET "https://app.saga.surf/api/user/transactions?startDate=2025-10-01T00:00:00Z&endDate=2025-10-03T23:59:59Z" \
  -H "Authorization: Bearer $TOKEN"

Пример TypeScript

// Получить последние транзакции
const response = await fetch('/api/user/transactions?page=1&limit=20&sortBy=createdAt&orderBy=desc', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const { data: transactions, pagination } = await response.json();

console.log(`Показано ${transactions.length} из ${pagination.total} транзакций`);

transactions.forEach(txn => {
  const sign = ['deposit', 'earning', 'divestment'].includes(txn.type) ? '+' : '-';
  console.log(`${txn.createdAt}: ${sign}$${txn.amount} (${txn.type}) - ${txn.status}`);
});

// Обработка пагинации
if (pagination.hasNext) {
  console.log('Загрузить ещё транзакций:', `/api/user/transactions?page=${pagination.page + 1}`);
}

---

GET /api/user/transactions/:id

Получить детальную информацию о конкретной транзакции.

Запрос

GET /api/user/transactions/txn_abc123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Заголовки:

Заголовок	Значение	Обязательно	Описание
Authorization	Bearer <token>	✅ Да	User JWT токен

Path параметры:

Параметр	Тип	Обязательно	Описание
id	string	✅ Да	Transaction ID (например, txn_abc123)

Ответ

Успех (200 OK) - Deposit транзакция:

{
  "success": true,
  "data": {
    "id": "txn_abc123",
    "type": "deposit",
    "amount": "1000.00",
    "currency": "USDC",
    "status": "completed",
    "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "to": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
    "blockchainTxHash": "0xabcdef123456789...",
    "blockNumber": 1234567,
    "confirmations": 15,
    "gasUsed": "21000",
    "gasFee": "0.005 ETH",
    "createdAt": "2025-10-03T10:00:00Z",
    "submittedAt": "2025-10-03T10:00:05Z",
    "completedAt": "2025-10-03T10:01:30Z",
    "metadata": {
      "description": "USDC deposit via MetaMask",
      "userWalletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "contractAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
      "method": "transfer"
    },
    "timeline": [
      {
        "status": "pending",
        "timestamp": "2025-10-03T10:00:00Z",
        "description": "Transaction initiated"
      },
      {
        "status": "submitted",
        "timestamp": "2025-10-03T10:00:05Z",
        "description": "Submitted to blockchain"
      },
      {
        "status": "processing",
        "timestamp": "2025-10-03T10:00:30Z",
        "description": "Awaiting confirmations (0/12)"
      },
      {
        "status": "completed",
        "timestamp": "2025-10-03T10:01:30Z",
        "description": "Confirmed on blockchain (12 confirmations)"
      }
    ]
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Успех (200 OK) - Investment транзакция:

{
  "success": true,
  "data": {
    "id": "txn_def456",
    "type": "investment",
    "amount": "500.00",
    "currency": "USDC",
    "status": "completed",
    "strategyId": "balanced-10",
    "strategyName": "Balanced 10% APY Strategy",
    "strategyDetails": {
      "apy": 10.0,
      "riskLevel": "medium",
      "protocols": ["Pendle", "Curve", "Convex"]
    },
    "createdAt": "2025-10-03T11:00:00Z",
    "completedAt": "2025-10-03T11:02:15Z",
    "metadata": {
      "description": "Investment in Balanced strategy",
      "expectedAnnualReturn": "50.00",
      "lockupPeriod": "none"
    },
    "timeline": [
      {
        "status": "pending",
        "timestamp": "2025-10-03T11:00:00Z",
        "description": "Investment request created"
      },
      {
        "status": "processing",
        "timestamp": "2025-10-03T11:00:30Z",
        "description": "Allocating capital to protocols"
      },
      {
        "status": "completed",
        "timestamp": "2025-10-03T11:02:15Z",
        "description": "Capital successfully allocated"
      }
    ]
  },
  "timestamp": "2025-10-03T12:34:56Z"
}

Поля ответа:

Поле	Тип	Описание
data.id	string	Уникальный идентификатор транзакции
data.type	string	Тип транзакции
data.amount	string	Сумма транзакции (SafeDecimal)
data.status	string	Текущий статус транзакции
data.blockchainTxHash	string	On-chain tx hash (для deposits/withdrawals)
data.confirmations	number	Подтверждения blockchain (для on-chain txns)
data.timeline	array	Детальная история переходов статусов
data.metadata	object	Дополнительные детали транзакции

Ошибки:

Код статуса	Код ошибки	Описание
401	TOKEN_EXPIRED	JWT токен истёк
403	PERMISSION_DENIED	Транзакция принадлежит другому пользователю
404	TRANSACTION_NOT_FOUND	Transaction ID не существует

Пример cURL

TOKEN="eyJhbGciOiJIUzI1NiIs..."
curl -X GET https://app.saga.surf/api/user/transactions/txn_abc123 \
  -H "Authorization: Bearer $TOKEN"

Пример TypeScript

// Получить детали транзакции
const response = await fetch(`/api/user/transactions/${transactionId}`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const { data: transaction } = await response.json();

console.log('Транзакция:', transaction.id);
console.log('Тип:', transaction.type);
console.log('Сумма:', transaction.amount, transaction.currency);
console.log('Статус:', transaction.status);

if (transaction.blockchainTxHash) {
  console.log('Посмотреть в Explorer:', `https://explorer.saga.surf/tx/${transaction.blockchainTxHash}`);
}

// Отобразить timeline
console.log('\nTimeline:');
transaction.timeline.forEach(event => {
  console.log(`  ${event.timestamp}: ${event.status} - ${event.description}`);
});

---

Распространённые сценарии использования

Отображение карточки баланса пользователя

const { data: balance } = await fetch('/api/user/balance', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// Отрисовка карточки баланса
<div className="balance-card">
  <h3>Общий баланс: ${balance.total} USDC</h3>
  <div className="breakdown">
    <span>Доступно: ${balance.available}</span>
    <span>Инвестировано: ${balance.invested}</span>
  </div>
  <div className="earnings">
    Заработано за всё время: +${balance.breakdown.earnings}
  </div>
</div>

Таблица истории транзакций

const { data: transactions, pagination } = await fetch(
  '/api/user/transactions?page=1&limit=20',
  { headers: { 'Authorization': `Bearer ${token}` } }
).then(r => r.json());

// Отрисовка таблицы транзакций
<table>
  <thead>
    <tr>
      <th>Дата</th>
      <th>Тип</th>
      <th>Сумма</th>
      <th>Статус</th>
    </tr>
  </thead>
  <tbody>
    {transactions.map(txn => (
      <tr key={txn.id}>
        <td>{new Date(txn.createdAt).toLocaleDateString()}</td>
        <td>{txn.type}</td>
        <td>${txn.amount} {txn.currency}</td>
        <td><StatusBadge status={txn.status} /></td>
      </tr>
    ))}
  </tbody>
</table>

{/* Пагинация */}
{pagination.hasNext && (
  <button onClick={() => loadPage(pagination.page + 1)}>
    Загрузить ещё
  </button>
)}

Мониторинг транзакций в реальном времени

// Опрос для обновлений статуса транзакции
async function monitorTransaction(txnId: string) {
  const interval = setInterval(async () => {
    const response = await fetch(`/api/user/transactions/${txnId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const { data: txn } = await response.json();

    console.log(`Статус: ${txn.status}`);

    if (['completed', 'failed', 'cancelled'].includes(txn.status)) {
      clearInterval(interval);
      console.log('Транзакция завершена:', txn.status);
    }
  }, 5000); // Проверка каждые 5 секунд
}

// Запуск мониторинга
monitorTransaction('txn_abc123');

---

Связанная документация

Другие User Endpoints:

• Authentication - User auth endpoints
• Investments - Управление инвестициями
• Withdrawals - Операции вывода

Архитектура:

• SafeDecimal System - Обработка финансовой точности
• Blockchain Integration - On-chain transaction flow

---

---

---

📋 Метаданные

Версия: 2.6.268

Обновлено: 2025-10-21

Статус: Published

---