POST /api/v1/score — submitRun, поля запроса/ответа, тарификация, коды ошибок, идемпотентность.

Score API — публичный контракт

Единая точка входа: submitRun → execute → return result. Доступ только по API-ключу, анализы тарифицируются кредитами по сети.

Аутентификация

Все запросы требуют заголовок X-API-Key: wx_... (API-ключ тенанта). Ключ хранится на платформе только как argon2-хэш, глобальный индекс даёт O(1) lookup, доступность по ключу — до 300 rps.

POST /api/v1/score

curl -X POST https://score.example.com/api/v1/score \
  -H "X-API-Key: wx_live_…" \
  -H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00c04fc964ff" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "network": "tron",
    "context": "gambling_deposit",
    "options": {"timeout_ms": 5000}
  }'

Поля запроса

Поле	Тип	Обязательность	Описание
`address`	string	да	Адрес кошелька (формат валидируется по сети)
`network`	string	да	Сеть: `ethereum`, `bnb`, `tron`, `bitcoin`
`context`	string	нет	Контекст анализа (например `gambling_deposit`) — влияет на интерпретацию правил
`options`	object	нет	Опции прогона: `timeout_ms` и др.

Ответ (успех)

{
  "request_id": "b3c1…",
  "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "network": "tron",
  "score": 72,
  "risk_level": "medium",
  "confidence": 0.86,
  "flags": ["counterparty_concentration"],
  "features": { "graph.pagerank": 0.333, "graph.fan_out_top1_share": 1.0 },
  "credits_spent": 3,
  "cached": false
}

Поле	Описание
`request_id`	UUID прогона — трассировка в ledger кредитов и аудите
`score`	Итоговый балл 0–100 (scorecard, детерминирован)
`risk_level`	Уровень риска: `low` / `medium` / `high`
`confidence`	Уверенность результата 0–1 (снижается при неполных данных — см. Скоринг-модель)
`flags`	Человекочитаемый список сработавших правил (объяснимость)
`features`	Вектор рассчитанных признаков, включая `graph.*`
`credits_spent`	Фактически списанные кредиты за этот прогон
`cached`	`true`, если результат вернут по идемпотентному ключу без повторного списания

Тарификация по сетям

Сеть	Кредитов за скоринг
Ethereum	1
BNB Chain	1
TRON	3
Bitcoin	3

Механика: hold при постановке → settle при успехе → refund при ошибке (см. Биллинг). Запрос без достаточного баланса отклоняется до начала работы.

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

Заголовок Idempotency-Key гарантирует, что повторная отправка того же запроса (ретрай, дубль из очереди) возвращает тот же результат без повторного списания кредитов:

одинаковый Idempotency-Key + одинаковый payload → тот же request_id, cached: true, списания нет;
одинаковый ключ с другим payload → ошибка 422 (IDEMPOTENCY_CONFLICT).

Возврат кэша при идемпотентном ключе — бесплатен (0 кредитов): кредиты снимаются только за реальный новый анализ.

Коды ошибок

HTTP	Код	Причина
400	`INVALID_REQUEST`	Невалидный формат адреса или payload
401	`UNAUTHORIZED`	Нет/неверен `X-API-Key`
403	`FORBIDDEN`	Ключ отозван / tenant заблокирован
404	`TENANT_NOT_FOUND`	Тенант/программа не найдены
422	`IDEMPOTENCY_CONFLICT`	Ключ идемпотентности переиспользован с другим payload
429	`RATE_LIMITED`	Превышен rate limit тенанта
500	`INTERNAL_ERROR`	Внутренняя ошибка
503	`PROVIDER_UNAVAILABLE`	Недоступен внешний провайдер данных (TronGrid и т.п.)

Маппинг биллинга на ошибки: INSUFFICIENT_CREDITS — запрос отклонён до начала работы (баланс не зарезервирован); ошибка исполнения после hold → полный refund, клиент не платит за неуспешный скоринг.

Score API

On this page