User Wallets

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

• Каждый пользователь получает свой адрес, привязанный к вашему externalId.
• Входящий депозит проходит AML-проверку.
• После проверки средства пересылаются в сети на ваш адрес depositForwardAddress. На баланс компании в Lumo они не зачисляются.
• Вы получаете вебхук и зачисляете сумму пользователю у себя.

Пользователь ──USDT──▶ адрес пользователя ──AML──▶ пересылка ──▶ depositForwardAddress
                                                       │
                                     комиссия с баланса компании в Lumo

1. Задайте адрес для пересылки — TRON-адрес, куда будут приходить средства (право settings.write):

   curl -X PATCH 'https://b2b.lumowallet.io/auth/company/profile' \
     -H 'X-API-Key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"depositForwardAddress": "TQ2x4bW8ZGq3NkL2bUQvX8sJ7d1cQh1xYz"}'

   Сделайте это до создания первого кошелька: пока адрес не задан, депозиты пересылаются на казначейский адрес Lumo, а не вам. Новый адрес применяется при следующем запросе к /user-wallets.

2. Пополните баланс компании в Lumo — с него списывается комиссия за обработку депозитов, см. Комиссия.

3. Настройте вебхуки.

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"
  }'

Ответ (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "externalId": "user-12345",
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "isBlocked": false,
  "blockReason": null,
  "lastUsdtBalance": 0,
  "lastTrxBalance": 0,
  "createdAt": "2026-03-10T12:00:00.000Z"
}

Нужно право balance.withdraw. companyId — внутренний идентификатор компании в сервисе кошельков, он не совпадает с id из профиля компании.

Повторный запрос с тем же externalId вернёт существующий незаблокированный кошелёк. Если все кошельки пользователя заблокированы, создастся новый адрес.

Пользователь отправляет USDT TRC-20 на address. После AML-проверки и пересылки на depositForwardAddress приходит вебхук:

{
  "event": "deposit.completed",
  "depositId": "770e8400-e29b-41d4-a716-446655440002",
  "externalId": "user-12345",
  "txHash": "c4d2e8...19fa",
  "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "amount": 50,
  "status": "completed",
  "amlCheckId": null,
  "amlResult": null,
  "sweepTxHash": "d9a0b1...77e3",
  "error": null,
  "blockTimestamp": null,
  "createdAt": "2026-03-10T12:05:00.000Z",
  "updatedAt": "2026-03-10T12:05:00.000Z"
}

sweepTxHash — транзакция пересылки на ваш адрес. Событие отправляется сразу после отправки этой транзакции в сеть, не дожидаясь её подтверждения.

По кошелькам пользователей приходят только три события:

deposit.failed не всегда окончательный: при некоторых ошибках пересылка повторяется, и позже по тому же depositId может прийти deposit.completed.

deposit.created, deposit.fee_charged и deposit.aml_pending по кошелькам пользователей не приходят. Поля событий — в разделе Webhooks.

Депозиты меньше минимальной суммы для компании не обрабатываются и событий не порождают — минимальную сумму уточните у менеджера.

Перед пересылкой каждого депозита, прошедшего AML-проверку, с баланса компании в Lumo списывается фиксированная комиссия за обработку — в истории баланса это company_deposit_fee_charge с referenceId депозита. Размер комиссии уточните у менеджера.

Если на балансе не хватает средств на комиссию, пересылка откладывается и повторяется через 5 минут, 1 час и 4 часа. Если баланс так и не пополнили, депозит завершается deposit.failed с ошибкой Insufficient company balance for processing fee, а средства остаются на адресе пользователя — для их пересылки напишите в поддержку.

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

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

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

Ответ — { "wallets": [...], "total": 42 }, новые сначала. Параметры: externalId, limit, offset. Нужно право balance.read.

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

Ответ:

{
  "deposits": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "companyId": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "walletId": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "user-12345",
      "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "txHash": "c4d2e8...19fa",
      "fromAddress": "TXyz4b8XqQ1wR9mJ2vL5kN7pC3dF6gH8jK",
      "amount": 50,
      "status": "completed",
      "amlCheckId": "4d7e2a1c-...",
      "amlRiskIndicator": "12",
      "sweepTxHash": "d9a0b1...77e3",
      "error": null,
      "blockTimestamp": "2026-03-10T12:04:30.000Z",
      "createdAt": "2026-03-10T12:04:41.000Z"
    }
  ],
  "total": 1
}

Параметры: externalId, status, limit, offset. Нужно право balance.read.

Статусы депозита пользователя:

Статусы здесь не совпадают со статусами в вебхуках: в событиях status — только completed, aml_failed или failed.

Если депозит не прошёл AML-проверку:

• кошелёк блокируется: isBlocked: true, в blockReason — показатель риска;
• приходит deposit.aml_failed;
• средства остаются на адресе пользователя — забрать их можно выводом.

Чтобы пользователь мог пополнять снова, выдайте ему новый адрес — повторным POST /user-wallets с тем же externalId или через замену.

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

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.

Депозиты на заблокированный адрес не обрабатываются: событий по ним нет, средства остаются на адресе. Забрать их можно выводом.

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

Параметры и формат ответа — как у списка кошельков.

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

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:

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

Старый кошелёк блокируется, reason попадает в его blockReason. Тело необязательно.

С заблокированного кошелька можно вывести весь остаток на указанный адрес (право balance.withdraw):

curl -X POST 'https://b2b.lumowallet.io/user-wallets/{walletId}/withdraw' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"toAddress": "TRefundAddrX4bW8ZGq3NkL2bUQvX8sJ7d"}'

{
  "success": true,
  "requestId": "3e1d9b7a-5c2f-4a8e-b6d0-9f4c2a1e7b3d",
  "status": "pending"
}

Выводится весь остаток USDT. Для незаблокированного кошелька вывод недоступен — придёт 404. В ответе также могут быть message и txHash.

Статус вывода (право balance.read):

curl 'https://b2b.lumowallet.io/user-wallets/withdrawals/status/{requestId}' \
  -H 'X-API-Key: YOUR_API_KEY'

{
  "requestId": "3e1d9b7a-5c2f-4a8e-b6d0-9f4c2a1e7b3d",
  "status": "completed",
  "txHash": "e5f6a7...90bc",
  "amount": "48.5"
}

status: pending, processing, completed или failed. При ошибке — поле error.

1. Уникальный externalId — используйте ID пользователя из вашей системы.
2. Сохраняйте walletId — для блокировки, замены и вывода.
3. Зачисляйте по deposit.completed и дедуплицируйте по depositId.
4. Следите за балансом в Lumo — без него не списать комиссию, и депозиты не будут пересылаться.
5. Блокируйте при подозрениях — лучше заблокировать, чем потерять средства.