# REST API

> Повний довідник REST API NeuroChain — усі ендпоінти ноди й gateway за розділами, з полями запитів, цілями підписаних операцій, параметрами запиту, правилами для сум і помилок та лімітами запитів.

Source: https://docs.nro.world/uk/reference/rest

Мережу відкривають два HTTP-сервіси:

| Сервіс | За замовчуванням | Призначення |
|--------|------------------|-------------|
| **Gateway** (Node.js) | `http://localhost:3000` | Те, до чого звертаються dApp і вебзастосунок. Проксує ноду, додає WebSocket, AI-інструменти й кешування |
| **RPC ноди** (Rust) | `http://localhost:9933` | Джерело істини. Деякі ендпоінти для операторів є лише тут |

Більшість шляхів однакові в обох. У таблицях нижче позначено ендпоінти, що є лише в одному з них. Приклади використовують `$GATEWAY` і `$NODE_RPC` — див. [Почніть тут](/uk/learn/start-here).

## Домовленості

### Суми

- Суми в мережі — **цілі числа в uNRO** (`1 NRO = 1 000 000 uNRO`).
- Відповіді додають поруч з кожною сумою відформатований рядок **`*_human`** (`balance_human`, `value_human`, `stake_human`, …). Показуйте саме їх; не перераховуйте на клієнті.
- У тілі запиту надсилайте суми **числами JSON** в uNRO, якщо ендпоінт не каже інакше.

### Підписані операції

Кожен ендпоінт, що змінює стан, потребує підпису. Їх два види:

| Вид | Підписане повідомлення | `nonce` |
|-----|------------------------|---------|
| **Транзакція** (`POST /api/v1/transactions`) | `nc-tx-v2|from|to|value|nonce` | Nonce акаунта: останній підтверджений + очікувані + 1 |
| **Операція** (усе інше) | `nc-tx-v2|actor|<ціль>|<value>|nonce` | Позначка часу в мілісекундах, строго зростає для кожної адреси |

*Ціль* — зарезервована системна адреса, що називає операцію; у таблицях вона в колонці **Підпис для**. Кожен запит містить `signature` (hex), `public_key` (hex ML-DSA-65) і `nonce`. Див. [Гаманець → Підписані операції](/uk/learn/wallet#signed-operations).

З `CHAIN_ENV=mainnet` (за замовчуванням) відсутній чи недійсний підпис відхиляється з **401**. З `CHAIN_ENV=testnet` нода лише пише попередження — тільки для локальної розробки.

Більшість операцій **застосовуються в консенсусі**: відповідь містить `"status": "pending"` і `tx_hash`; ефект видно, коли транзакція потрапить у блок.

### Помилки

Помилки — JSON: `{"error": "<повідомлення>"}`, іноді з `hint` чи додатковими полями. HTTP-коди:

| Код | Значення |
|-----|----------|
| 200 | Успіх — але деякі старіші ендпоінти повертають `{"error": …}` теж з 200; завжди перевіряйте `error` |
| 400 | Некоректний запит, не пройдена перевірка, відмова Sentinel |
| 401 | Відсутній чи недійсний підпис, ключ не прив'язаний до адреси |
| 403 | Заборонено в цьому режимі (кран у mainnet, записуючий виклик поза консенсусом у mainnet), розгортання відхилене VMGuardian |
| 404 | Не знайдено |
| 409 | Ім'я вже зайняте |
| 429 | Перевищено ліміт запитів |
| 502 / 503 | Gateway не може дістатися ноди |

### Пагінація

Ендпоінти-списки приймають `limit` і `offset` (деякі також `page`). Кожен ендпоінт обмежує `limit` (зазвичай 100 або 200).

### Ліміти запитів і CORS

| Де | За замовчуванням | Змінна |
|----|------------------|--------|
| RPC ноди, на IP | 100 запитів/с | `NEUROCHAIN_RPC_RATE_LIMIT` |
| Gateway, на IP | 200 запитів/с | `GLOBAL_RL_MAX_RPS` |
| AI-ендпоінти gateway (`/contracts/audit`, `/contracts/generate`, …), на IP | 10 запитів/хв | `AI_RL_MAX_RPM` |

Дозволені джерела: `CORS_ALLOWED_ORIGINS` в обох сервісах (за замовчуванням `*`).

---

## Мережа і нода

| Метод | Шлях | Примітки |
|-------|------|----------|
| GET | `/health` | `status`, `height`, `round`, `mempool`, `peers`, `tps`, `total_txs`, `validator_count`, `bft_quorum`, `bft_ready` |
| GET | `/status`, `/api/v1/status` | Лише нода. Висота, валідатори, шарди, назва мережі |
| GET | `/api/v1/network/status` | Лише gateway. Зведення мережі для експлорера |
| GET | `/metrics` | Текстовий формат Prometheus — див. [Запуск ноди](/uk/operate/node) |
| GET | `/api/v1/shards` | Висоти й корені шардів |
| GET | `/api/v1/state/root` | `global_root`, `shard_roots`, `height`, `root_height`, `n_shards` |
| GET | `/api/v1/state/snapshot` | Лише нода. Повний підписаний знімок стану для запуску ноди |
| GET | `/api/v1/checkpoints` | Підписані контрольні точки. `offset`, `limit` |
| GET | `/peers` | Лише нода. Підключені піри |
| GET | `/api/v1/gas/estimate` | `base_fee`, газ за операцію, `total_burned`, `nft_transfer_fee` — див. [Газ і комісії](/uk/learn/gas) |
| GET | `/api/v1/wasm/version` | Лише gateway. Маніфест версії браузерного WASM-модуля |

## Блоки

| Метод | Шлях | Примітки |
|-------|------|----------|
| GET | `/api/v1/blocks` | `limit` (≤ 100, за замовчуванням 20), `offset`, `page`. Найновіші першими |
| GET | `/api/v1/blocks/latest` | Лише gateway. `{ "block": … }` |
| GET | `/api/v1/blocks/:height` | Один блок: `height`, `hash`, `parent_hash`, `proposer`, `tx_root`, `state_root`, `tx_count`, `gas_used`, `base_fee`, `fees_burned`, `shard`, `round`, `timestamp` |
| GET | `/api/v1/blocks/:height/transactions` | Транзакції блоку |

## Транзакції

| Метод | Шлях | Підпис для | Примітки |
|-------|------|------------|----------|
| POST | `/api/v1/transactions` | сама транзакція | Тіло нижче |
| GET | `/api/v1/transactions` | — | `address`, `hash`, `type` (`staking` — операції стейкінгу), `limit` (≤ 200), `offset`, `page` |
| GET | `/api/v1/transactions/:hash` | — | Одна транзакція зі `status`, `gas`, `fee`, `fee_human`, `value_human` |
| GET | `/api/v1/tx/:hash/proof` | — | Доказ включення Меркла: `leaf_index`, `proof`, `tx_root`, `block_height` |
| POST | `/api/v1/transactions/:hash/confirm` | `neuro:system.trust` | Підтвердити утриманий переказ (лише майстер-ключ власника) — див. [Sentinel](/uk/ai/sentinel) |
| POST | `/api/v1/transactions/:hash/cancel` | `neuro:system.trust` | Скасувати утриманий переказ |
| GET | `/api/v1/held/:address` | — | Утримані перекази адреси |
| GET | `/api/v1/cross-shard/queue` | — | Міжшардові передачі. `status`, `limit`, `offset` |

**Тіло `POST /api/v1/transactions`**

| Поле | Тип | Обов'язкове | Значення |
|------|-----|-------------|----------|
| `from` | string | так | Адреса відправника |
| `to` | string | так | Отримувач, контракт або `neuro:system.deploy` |
| `value` | number | так | uNRO |
| `nonce` | number | так | Наступний nonce акаунта |
| `signature` | string | так | ML-DSA-65 над `nc-tx-v2|from|to|value|nonce`, hex |
| `public_key` | string | так | Публічний ключ ML-DSA-65, hex |
| `gas_price` | number | ні | uNRO за одиницю газу; має бути ≥ базової комісії |
| `data` | string | ні | Виклик контракту чи розгортання рядком JSON (hex теж приймається) — див. [ABI](/uk/build/abi), [Розгортання](/uk/build/deploy) |

Відповідь: `tx_hash`, `status: "pending"`, `estimated_block`; плюс `sentinel_score` і `sentinel_warning`, коли Sentinel позначив транзакцію, або деталі `held`, коли її утримав шар політик.

## Акаунти

| Метод | Шлях | Примітки |
|-------|------|----------|
| GET | `/api/v1/accounts/:address` | `balance`, `balance_human`, `nonce`, … |
| GET | `/api/v1/accounts/:address/transactions` | Історія. `limit`, `offset` |
| GET | `/api/v1/accounts/:address/token-transfers` | Перекази токенів (NRC-20) за участю адреси |
| GET | `/api/v1/accounts/:address/totals` | Лише нода. Суми надісланого й отриманого |
| POST | `/api/v1/faucet` | Лише тестові мережі (`CHAIN_ENV=testnet`). Тіло: `address`, `public_key`, `amount` (uNRO, необов'язково) |
| POST | `/api/v1/wallet/derive-address` | Тіло: `words`. Виводить адресу `.human` з фрази — **надсилає фразу на сервер**. Вимкнено в mainnet; у тестових мережах — лише з `NEUROCHAIN_ALLOW_SERVER_DERIVE=true` |

## Імена і NFT

| Метод | Шлях | Підпис для | Тіло / примітки |
|-------|------|------------|-----------------|
| POST | `/api/v1/addresses/human` | `neuro:system.name` | Лише нода. `name`, `owner`, + підписані поля. Реєструє власне ім'я `.human` |
| GET | `/api/v1/addresses/human/price` | — | Лише нода. `?name=` → ціна за довжиною |
| POST | `/api/v1/nodes/register` | `neuro:system.node` | `name`, `owner`, необов'язково `node_address` (для `.app` / `.vault`), + підписані поля |
| GET | `/api/v1/nodes` | — | Зареєстровані ноди |
| GET | `/api/v1/nodes/:address` | — | Запис однієї ноди |
| PUT/POST | `/api/v1/nodes/:address/profile` | `neuro:system.node` | `description`, `website`, `commission_bps`, `p2p_endpoint`, `rpc_endpoint` |
| POST | `/api/v1/nodes/:address/unjail` | `neuro:system.node` | Повернутися в набір після періоду jail (підписує власник) |
| POST | `/api/v1/nft/transfer` | адреса NFT | `nft_address`, `from` (поточний власник), `to`, + підписані поля. Комісія 100 uNRO |
| GET | `/api/v1/nft/:address` | — | Запис NFT та історія передач |
| GET | `/api/v1/nft/owner/:address` | — | NFT, якими володіє адреса |
| POST | `/api/v1/agents/register` | `neuro:system.agent` | `name`, `owner`, + підписані поля. Реєструє `.agent` |
| GET | `/api/v1/agents/:address` | — | Запис агента |

## Стейкінг

| Метод | Шлях | Підпис для | Тіло / примітки |
|-------|------|------------|-----------------|
| POST | `/api/v1/staking/stake` | `neuro:system.stake` | `address`, `amount`, + підписані поля |
| POST | `/api/v1/staking/unstake` | `neuro:system.stake` | `address`, + підписані поля |
| POST | `/api/v1/staking/delegate` | адреса валідатора | `delegator`, `validator`, `amount`, + підписані поля |
| POST | `/api/v1/staking/undelegate` | адреса валідатора | `delegator`, `validator`, + підписані поля |
| GET | `/api/v1/staking/info/:address` | — | Стейк, блокування, винагороди адреси |
| GET | `/api/v1/staking/validators` | — | Валідатори зі стейком і делегуваннями |
| GET | `/api/v1/staking/delegations/:validator` | — | Делегування валідатору |
| GET | `/api/v1/staking/my-delegations/:address` | — | Делегування, зроблені адресою |
| GET | `/api/v1/staking/rewards/:address` | — | Історія винагород; `source=stake|delegation|commission` |
| GET | `/api/v1/validators` | — | Валідатори консенсусу зі `stake`, `trust_score`, `blocks_proposed`, `votes_cast`, `last_active` |
| GET | `/api/v1/slashing/history` | — | Лише нода. Слешинги. `limit` |

Див. [Стейкінг і делегування](/uk/learn/staking).

## Управління

| Метод | Шлях | Підпис для | Тіло / примітки |
|-------|------|------------|-----------------|
| POST | `/api/v1/governance/propose` | `neuro:system.governance` | `proposer`, `title`, `description`, `kind` (`text` / `PARAM_CHANGE`), `payload`, `voting_duration`, + підписані поля |
| POST | `/api/v1/governance/:id/vote` | `neuro:system.governance` | `voter`, `accept` (bool), + підписані поля |
| GET | `/api/v1/governance/proposals` | — | `status`, `limit` (≤ 100), `offset` |
| GET | `/api/v1/governance/:id` | — | Одна пропозиція з голосами |
| GET | `/api/v1/governance/params` | — | Усі параметри зі значенням і описом |

Див. [Управління](/uk/learn/governance).

## Сховища (мультипідпис)

| Метод | Шлях | Підпис для | Тіло / примітки |
|-------|------|------------|-----------------|
| GET | `/api/v1/vault/:addr/config` | — | `threshold`, `members` |
| GET | `/api/v1/vault/:addr/proposals` | — | Пропозиції виплат |
| GET | `/api/v1/vault/member/:addr` | — | Сховища, до яких належить адреса |
| POST | `/api/v1/vault/:addr/proposals` | адреса сховища | `proposer`, `to`, `amount`, `description`, + підписані поля |
| POST | `/api/v1/vault/:addr/proposals/:id/sign` | адреса сховища | `signer`, + підписані поля. Виплата відбувається, коли підписів досягнуто поріг |
| POST | `/api/v1/vault/:addr/members` | адреса сховища | `member`, `requester`, + підписані поля |
| POST | `/api/v1/vault/:addr/threshold` | адреса сховища | `threshold`, `requester`, + підписані поля |

::: warning Експериментально
Операції сховищ зараз застосовує нода, що отримала запит, а не консенсус. Доки це не перенесено в консенсус, працюйте зі сховищем через одну ноду.
:::

## Контракти

| Метод | Шлях | Підпис для | Тіло / примітки |
|-------|------|------------|-----------------|
| GET | `/api/v1/contracts` | — | `owner`, `limit`, `offset` |
| GET | `/api/v1/contracts/:address` | — | Метадані, `security_score`, власник, хеш коду |
| GET | `/api/v1/contracts/:address/token-info` | — | Лише gateway. Назва, символ, decimals, пропозиція NRC-20 |
| POST | `/api/v1/contracts/:address/call` | — | `function`, `args`, `dry_run`, `gas_limit`, `caller`. Читання з `dry_run: true`; записи в mainnet відхиляються |
| POST | `/api/v1/contracts/deploy` | `neuro:system.deploy` | Лише нода. `owner`, `bytecode_hex` або `base64_wasm`, `name`, `description`, `template`, + підписані поля |
| POST | `/api/v1/contracts/analyze` | — | Лише нода. `bytecode_hex` → `risk_score`, `security_score`, `ml_score`, `model`, `violations` |
| POST | `/api/v1/contracts/attest` | — | `bytecode_hex` → аналіз, підписаний ML-DSA-65: `score`, `bytecode_hash`, `timestamp`, `signature`, `pubkey` |
| POST | `/api/v1/contracts/audit` | — | Лише gateway. `bytecode_hex` → аналіз ноди (вихідний код не приймається) |
| POST | `/api/v1/contracts/reaudit` | — | Лише gateway. `address` → повторний аналіз розгорнутого контракту |
| POST | `/api/v1/contracts/generate` | — | Лише gateway. Генерація шаблону контракту (SmartForge) |
| POST | `/api/v1/contracts/certify` | `neuro:system.cert` | Видати сертифікат безпеки (оператор VMGuardian) |
| POST | `/api/v1/contracts/whitelist` | `neuro:system.whitelist` | Лише нода. `bytecode_hash` — довірений байткод шаблону |
| PATCH | `/api/v1/contracts/:address/score` | `neuro:system.score` | Лише нода. `security_score` |
| GET | `/api/v1/certificates` | — | `owner`, `limit`, `offset` |
| GET | `/api/v1/certificates/:id` | — | Один сертифікат |
| GET | `/api/v1/certificates/contract/:address` | — | Сертифікат контракту |
| GET | `/api/v1/templates` | — | Зареєстровані шаблони контрактів |
| GET | `/api/v1/templates/:id` | — | Один шаблон з ABI |
| POST | `/api/v1/templates/register` | `neuro:system.templates` | `author` (`.node`), `name`, `description`, `category`, `bytecode_hex`, `abi_json`, `fee_unro`, + підписані поля |
| POST | `/api/v1/templates/deprecate` | `neuro:system.templates` | Лише нода. `template_id`, `author`, `delete`, + підписані поля |

## AI і моделі

| Метод | Шлях | Примітки |
|-------|------|----------|
| GET | `/api/v1/ai/status` | Лише gateway. Стан AI-моделей |
| POST | `/api/v1/sentinel/score` | Оцінити форму транзакції: `value`, `gas_price`, `nonce`, `last_nonce`, `balance`, `tx_count_last_10`, `recipient_tx_count`, `is_self_transfer` → `score`, `anomalous`, `category` |
| GET | `/api/v1/oracle/log` | Журнал рішень AI. `model`, `kind`, `subject`, `limit`, `offset` |
| GET | `/api/v1/oracle/log/:id` | Одне рішення |
| GET | `/api/v1/models/registry` | Реєстр моделей у мережі. `limit`, `offset` |
| GET | `/api/v1/models/registry/:id` | Одна версія моделі |
| POST | `/api/v1/models/register` | Лише валідатори; підпис для `neuro:models.registry`. `from`, `name`, `version`, `weights_hash`, `architecture`, `params_count`, `accuracy`, + підписані поля |
| GET | `/api/v1/ai/export/{blocks,txs,validators,oracle}` | Експорт даних для навчання (JSON Lines) |
| POST | `/api/v1/assistant/ask`, GET `/api/v1/assistant/health` | Лише gateway. Помічник з документації (вимкнений, якщо не `ASSISTANT_ENABLED=1`) |

## Список довіри Sentinel

| Метод | Шлях | Підпис для | Тіло |
|-------|------|------------|------|
| POST | `/api/v1/trust/add` | `neuro:system.trust` | `owner`, `recipient`, + підписані поля |
| POST | `/api/v1/trust/remove` | `neuro:system.trust` | `owner`, `recipient`, + підписані поля |
| GET | `/api/v1/trust/:owner` | — | Довірені отримувачі з висотою активації |

## Абстракція акаунтів

| Метод | Шлях | Підпис для | Тіло |
|-------|------|------------|------|
| POST | `/api/v1/session/grant` | `neuro:system.session` | `account`, `session_pk`, `scope`, `cap`, `expiry_block`, + підписані поля |
| POST | `/api/v1/session/revoke` | `neuro:system.session` | `account`, `session_pk`, + підписані поля |
| GET | `/api/v1/session/list/:account` | — | Сесійні ключі акаунта |
| POST | `/api/v1/sponsor/deposit` | `neuro:system.sponsor` | `address`, `amount`, + підписані поля |
| POST | `/api/v1/sponsor/withdraw` | `neuro:system.sponsor` | `address`, `amount`, + підписані поля |
| GET | `/api/v1/sponsor/:address` | — | Баланс пулу спонсора |

Див. [Абстракція акаунтів](/uk/ai/account-abstraction).

## Ідентичність і відновлення

Ці операції підписують власні повідомлення (наприклад, `nc-rotate|addr|add|remove|nonce`), а не `nc-tx-v2`; див. [Ідентичність](/uk/ai/identity).

| Метод | Шлях | Тіло |
|-------|------|------|
| POST | `/api/v1/identity/rotate` | `owner`, `add`, `remove`, + підписані поля |
| POST | `/api/v1/identity/recovery/setup` | `owner`, `guardians`, `threshold`, `timelock`, + підписані поля |
| POST | `/api/v1/identity/recovery/request` | `target`, `new_key`, + підписані поля |
| POST | `/api/v1/identity/recovery/approve` | `target`, `guardian`, + підписані поля |
| POST | `/api/v1/identity/recovery/reject` | `target`, `guardian`, + підписані поля |
| POST | `/api/v1/identity/recovery/withdraw` | `target`, + підписані поля |
| POST | `/api/v1/identity/recovery/cancel` | `owner`, + підписані поля |
| GET | `/api/v1/identity/:addr` | Ключі й версія |
| GET | `/api/v1/identity/recovery/:addr` | Налаштування відновлення і відкритий запит, якщо є |
| GET | `/api/v1/identity/guardian-of/:addr` | Ідентичності, які охороняє ця адреса |

## Нативні активи й обмін

| Метод | Шлях | Тіло / примітки |
|-------|------|-----------------|
| GET | `/api/v1/assets` | Випущені активи |
| GET | `/api/v1/assets/:id` | Один актив |
| GET | `/api/v1/assets/check-symbol` | `?symbol=` — чи тікер вільний і коректний |
| GET | `/api/v1/assets/balances/:addr` | Баланси активів |
| POST | `/api/v1/assets/issue` | `from`, `name`, `symbol`, `decimals`, `initial`, `max_supply`, `reissuable`, `reissue_unlock_height`, `issue_nonce`, + підписані поля. Комісія `asset_issue_fee` |
| POST | `/api/v1/assets/transfer` | `from`, `to`, `asset_id`, `amount`, + підписані поля |
| GET | `/api/v1/dex/pools`, `/api/v1/dex/pools/:id` | Пули |
| POST | `/api/v1/dex/pools` | `from`, `asset_x`, `asset_y`, `amount_x`, `amount_y`, + підписані поля |
| POST | `/api/v1/dex/liquidity/add` | `from`, `pool_id`, `max_a`, `max_b`, + підписані поля |
| POST | `/api/v1/dex/liquidity/remove` | `from`, `pool_id`, `shares`, + підписані поля |
| GET | `/api/v1/dex/quote` | Котирування обміну |
| POST | `/api/v1/dex/swap` | `from`, `pool_id`, `asset_in`, `amount_in`, `min_out`, `deadline_height`, + підписані поля. Виконується пакетом під час коміту наступного блоку |
| GET | `/api/v1/dex/window` | Поточне вікно пакета |
| POST | `/api/v1/dex/deposit`, `/api/v1/dex/withdraw` | Переміщення коштів між основним балансом і балансом обміну |
| GET | `/api/v1/dex/balances/:addr`, `/dex/positions/:addr`, `/dex/activity/:addr`, `/dex/transactions` | Баланси обміну, позиції LP, активність |

Усі операції з активами й обміном підписуються для `neuro:system.assets` і застосовуються в консенсусі.

::: warning Поки лише тестові мережі
У консенсусі ці операції також вимагають другого підпису над точним вмістом (`_psig`, повідомлення `nc-asset-op-v1|op|from|fields|nonce`), коли нода працює з `CHAIN_ENV=mainnet`. REST-ендпоінти цей підпис поки не приймають, тож у mainnet кожна операція з активами й обміном відхиляється; з `CHAIN_ENV=testnet` вони застосовуються без перевірки вмісту.
:::

## IBC v2 <Badge type="warning" text="експериментально" /> {#ibc-v2}

| Метод | Шлях | Тіло / примітки |
|-------|------|-----------------|
| POST | `/api/v1/ibc/channel/open` | `from`, `channel`, `port`, `counterparty_chain`, `allowed_denoms`, + підписані поля |
| POST | `/api/v1/ibc/channel/pause` | `from`, `channel`, `paused`, + підписані поля |
| POST | `/api/v1/ibc/transfer` | `from`, `channel`, `dest_chain`, `receiver`, `denom`, `amount`, + підписані поля |
| POST | `/api/v1/ibc/recv` | `from`, `packet_id`, `receiver`, `denom`, `amount`, + підписані поля |
| POST | `/api/v1/ibc/ack` | `from`, `id`, + підписані поля |
| POST | `/api/v1/ibc/redeem` | `from`, `channel`, `dest_chain`, `receiver`, `denom`, `amount`, + підписані поля |
| POST | `/api/v1/ibc/client/update`, `/api/v1/ibc/attest` | Оновлення легкого клієнта й атестація (релеєр) |
| GET | `/api/v1/ibc/channels`, `/ibc/packets`, `/ibc/denoms`, `/ibc/client/:chainId`, `/ibc/header/latest`, `/ibc/voucher/:addr`, `/ibc/pq/test-vector` | Стан і тестові вектори |

Усі операції IBC v2 підписуються для `neuro:system.ibc`; `recv`, `ack`, операції з каналами й клієнтом доступні лише ключам операторів IBC. Див. [IBC v2 і шардинг](/uk/operate/ibc).