Обзор API
Базовые URL, способы аутентификации, формат ошибок и лимиты для всех API Kaz Smart Chain.
Базовые URL#
Все REST-эндпоинты доступны под общим API-хостом:
text
https://kazsmartchain.org/apiЭндпоинты портала разработчика также доступны через субдомен https://dev.kazsmartchain.org/api. Глобального префикса версии нет.
Аутентификация#
| Схема | Заголовок | Где применяется |
|---|---|---|
| JWT разработчика | Authorization: Bearer <token> | Управление аккаунтом: деплой, ключи, faucet, аналитика |
| API-ключ | x-api-key: ksc_… | Contract Gateway: query / invoke |
| Публичный | — | Explorer, компиляция, challenge, балансы |
Два разных секрета
JWT разработчика выдаётся при входе по ЭЦП и живёт 12 часов. API-ключ (
ksc_…) предназначен для машинного доступа к контрактам и не истекает, пока не отозван.Выбор сети#
Эндпоинты, зависящие от сети, принимают параметр network со значениями testnet (по умолчанию в портале) или mainnet. В Explorer это query-параметр ?network=.
Формат ошибок#
Ошибки возвращаются стандартными кодами HTTP с JSON-телом NestJS:
json
{
"statusCode": 401,
"message": "Подпись ЭЦП не прошла криптографическую проверку.",
"error": "Unauthorized"
}| Код | Значение |
|---|---|
| 400 | Некорректный запрос (валидация, faucet вне testnet) |
| 401 | Не авторизован (нет/невалиден токен или ключ) |
| 403 | Доступ запрещён (чужой ресурс, недостаточный скоуп) |
| 404 | Не найдено |
| 429 | Превышен лимит (faucet / rate limit) |
| 503 | Сервис временно недоступен (например, верификатор ЭЦП) |
Rate limit#
- Глобально: 600 запросов в минуту с одного IP.
- Faucet: до 5 начислений в сутки на разработчика.
OpenAPI#
- Интерактивный Swagger UI со всеми эндпоинтами и кнопкой «Authorize» — kazsmartchain.org/api/docs.
- Спецификация JSON (OpenAPI 3.0) — kazsmartchain.org/api/docs-json. Импортируйте в Postman или сгенерируйте клиент.
- Per-contract OpenAPI — персональная спека для каждого контракта:
GET /api/devportal/contracts/:id/openapi.json.