# Адреса для приёма платежей

## Постоянный адрес пользователя

`POST /v1/addresses` выдаёт пользователю мерчанта постоянный адрес. Маршрут доступен только мерчантам в режиме `per_user`. Мерчанты в режиме `per_invoice` получают адрес вместе с инвойсом — см. [инвойсы](https://stons.io/docs/invoices.md).

### Запрос

| Поле | Тип | Обязательно | Описание |
| --- | --- | --- | --- |
| `external_user_id` | string | да | Идентификатор пользователя на стороне мерчанта: 1–200 видимых ASCII-символов без пробелов |
| `network` | string | да | Сеть. Сейчас принимается только `tron` |

### Ответ `200`

| Поле | Тип | Описание |
| --- | --- | --- |
| `address` | string | Адрес в сети TRON в формате base58 |
| `network` | string | `tron` |
| `assets` | string[] | Активы, которые сейчас можно предлагать пользователю для оплаты на этот адрес. Актив, приём которого оператор временно выключил или который выключен в настройках проекта, в список не входит |

Повторный запрос для того же `external_user_id` и той же сети возвращает тот же адрес. Одновременные запросы для одного пользователя тоже получают один адрес.

### Ошибки

| HTTP | `error.code` | Когда |
| --- | --- | --- |
| 400 | `validation_failed` | Поле отсутствует, лишнее или неверного формата |
| 401 | `unauthorized` | Нет ключа API или он неверный |
| 403 | `merchant_disabled` | Мерчант отключён |
| 403 | `merchant_not_approved` | Проект ещё не прошёл проверку или отклонён: постоянный адрес — это способ оплаты, и до одобрения он не выдаётся |
| 409 | `address_mode_mismatch` | Мерчант работает в режиме `per_invoice` |
| 429 | `rate_limited` | Превышен лимит запросов |
| 503 | `addresses_exhausted` | Индексы деривации закончились. Практически недостижимо: их 2^31 |

### Пример

```sh
curl -s -X POST https://api.stons.io/v1/addresses \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_user_id": "user_42", "network": "tron"}'
```

```json
{"address":"TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH","network":"tron","assets":["USDT_TRON"]}
```

Адрес в примере условный: у каждой установки свои адреса, выведенные из её собственного ключа.

## Откуда берутся адреса

Каждый адрес выводится из мастер-ключа сервиса по стандарту BIP44. Для TRON это путь `m/44'/195'/0'/0/{index}`, для EVM-сетей — путь `m/44'/60'/0'/0/{index}`. Индексы выдаются строго по порядку и никогда не используются повторно, даже если адрес так и не получил платежа. Поэтому два пользователя не могут получить один адрес.

Сервер API знает только публичную часть мастер-ключа. Он умеет выводить адреса, но не может потратить средства с них.

Один и тот же EVM-адрес действует во всех поддерживаемых EVM-сетях. Показывайте пользователю не только адрес, но и сеть, в которой ждёте платёж.

## Режимы

Режим задаёт оператор при подключении мерчанта. Почему режимов два — в ADR-0005.

| Режим | Адрес | Когда подходит |
| --- | --- | --- |
| `per_user` | Постоянный адрес пользователя мерчанта | Пополнение баланса: пользователь может платить на один адрес сколько угодно раз |
| `per_invoice` | Новый адрес под каждый инвойс. Адрес однозначно определяет инвойс | Оплата конкретного заказа |

Платёж никогда не сопоставляется с заказом по «уникальной сумме» с копейками: такая схема даёт коллизии и в режиме `per_user` не нужна.

## Что приходит на адрес

- Адрес остаётся под наблюдением всегда, в том числе после истечения инвойса. Поздний платёж не теряется: он фиксируется, и мерчант получает об этом событие.
- Зачисляются активы, которые сервис принимает к оплате. Список `assets` — те из них, что можно предлагать пользователю сейчас: актив, приём которого оператор временно выключил, из списка пропадает, но перевод в нём, пришедший на адрес, зачисляется как обычно. Другой известный сервису актив фиксируется, но не зачисляется мерчанту и инвойс не закрывает. Такие средства разбираются вручную.
- Неизвестные токены игнорируются полностью: среди них бывают контракты-ловушки, и любое взаимодействие с ними опасно.

## Показ адреса

Показывайте адрес целиком, без сокращений вида «первые и последние символы через многоточие». Злоумышленники рассылают переводы с адресов, у которых совпадают первые и последние символы, в расчёте на то, что человек сверит только их (address poisoning).