# User Wallets

Создавайте индивидуальные USDT-кошельки для пользователей вашей платформы.

## Сценарий использования

Идеально для обменников и бирж:

- Каждый пользователь получает уникальный адрес
- Депозиты автоматически отслеживаются по `externalId`
- AML-проверки выполняются автоматически
- Средства пересылаются на общий кошелёк компании


## Создание кошелька


```bash
curl -X POST 'https://b2b.lumowallet.io/user-wallets' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "user-12345"
  }'
```

Ответ:


```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "660e8400-e29b-41d4-a716-446655440001",
  "externalId": "user-12345",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "isBlocked": false,
  "blockReason": null,
  "lastUsdtBalance": 0,
  "lastTrxBalance": 0,
  "createdAt": "2026-03-10T12:00:00Z"
}
```

### Идемпотентность

Повторный запрос с тем же `externalId` вернёт существующий кошелёк:


```bash
# Первый вызов — создаёт кошелёк
# Повторный вызов — возвращает тот же кошелёк
```

## Получение депозитов

Пользователь отправляет USDT TRC-20 на адрес `address`. Вы получаете webhook:


```json
{
  "event": "deposit.completed",
  "depositId": "770e8400-e29b-41d4-a716-446655440002",
  "externalId": "user-12345",
  "txHash": "abc123...",
  "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "amount": 50.00,
  "status": "completed",
  "createdAt": "2026-03-10T12:05:00Z"
}
```

## Список кошельков


```bash
curl -X GET 'https://b2b.lumowallet.io/user-wallets?limit=50' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Фильтрация по `externalId`:


```bash
curl -X GET 'https://b2b.lumowallet.io/user-wallets?externalId=user-12345' \
  -H 'X-API-Key: YOUR_API_KEY'
```

## История депозитов пользователей


```bash
curl -X GET 'https://b2b.lumowallet.io/user-wallets/deposits?externalId=user-12345' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Ответ:


```json
{
  "deposits": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "companyId": "660e8400-e29b-41d4-a716-446655440001",
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "user-12345",
      "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "txHash": "abc123...",
      "amount": 50.00,
      "status": "completed",
      "createdAt": "2026-03-10T12:05:00Z"
    }
  ],
  "total": 1
}
```

## Блокировка кошелька

При подозрительной активности заблокируйте кошелёк:


```bash
curl -X POST 'https://b2b.lumowallet.io/user-wallets/{walletId}/block' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Suspicious activity detected"
  }'
```

После блокировки:

- Депозиты на этот адрес не обрабатываются
- `isBlocked: true` в ответе
- `blockReason` содержит причину


### Список заблокированных


```bash
curl -X GET 'https://b2b.lumowallet.io/user-wallets/blocked' \
  -H 'X-API-Key: YOUR_API_KEY'
```

## Замена кошелька

Создайте новый кошелёк для пользователя, заблокировав старый:


```bash
curl -X POST 'https://b2b.lumowallet.io/user-wallets/{walletId}/replace' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "User requested new address"
  }'
```

Ответ — новый кошелёк с тем же `externalId`:


```json
{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "externalId": "user-12345",
  "address": "TNewAddress...",
  "isBlocked": false,
  ...
}
```

Старый кошелёк автоматически блокируется.

## AML и пересылка

Все депозиты пользователей проходят:

1. **AML-проверку** — анализ адреса отправителя
2. **Зачисление** — при успешной проверке
3. **Пересылку** — средства отправляются на treasury компании


При `aml_failed` — средства заблокированы, свяжитесь с поддержкой.

## Рекомендации

1. **Уникальный externalId** — используйте ID пользователя из вашей системы
2. **Сохраняйте walletId** — для быстрого поиска и операций
3. **Обрабатывайте webhooks** — не полагайтесь на polling
4. **Блокируйте при подозрениях** — лучше заблокировать, чем потерять средства