REST API

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

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

Більшість шляхів однакові в обох. У таблицях нижче позначено ендпоінти, що є лише в одному з них. Приклади використовують $GATEWAY і $NODE_RPC — див. Почніть тут.

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

Суми

• Суми в мережі — цілі числа в 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
Операція (усе інше)	`nc-tx-v2	actor

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

З 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 — див. Запуск ноди
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 — див. Газ і комісії
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
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
public_key	string	так	Публічний ключ ML-DSA-65, hex
gas_price	number	ні	uNRO за одиницю газу; має бути ≥ базової комісії
data	string	ні	Виклик контракту чи розгортання рядком JSON (hex теж приймається) — див. ABI, Розгортання

Відповідь: 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
GET	/api/v1/validators	—	Валідатори консенсусу зі stake, trust_score, blocks_proposed, votes_cast, last_active
GET	/api/v1/slashing/history	—	Лише нода. Слешинги. limit

Див. Стейкінг і делегування.

Управління

Метод	Шлях	Підпис для	Тіло / примітки
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	—	Усі параметри зі значенням і описом

Див. Управління.

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

Метод	Шлях	Підпис для	Тіло / примітки
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, + підписані поля

Експериментально

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

Контракти

Метод	Шлях	Підпис для	Тіло / примітки
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	—	Баланс пулу спонсора

Див. Абстракція акаунтів.

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

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

Метод	Шлях	Тіло
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 і застосовуються в консенсусі.

Поки лише тестові мережі

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

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 і шардинг.