한국어
English
Українська
简体中文

한국어

English
Українська
简体中文

REST API ​

체인은 두 개의 HTTP 서비스로 제공됩니다:

서비스기본값용도
Gateway (Node.js)http://localhost:3000dApp과 웹 앱이 호출하는 대상입니다. 노드를 프록시하고 WebSocket, AI 도구, 캐싱을 더합니다
노드 RPC (Rust)http://localhost:9933신뢰할 수 있는 원본입니다. 일부 운영자용 엔드포인트는 여기에만 있습니다

대부분의 경로는 양쪽이 같습니다. 아래 표에는 한쪽에만 있는 엔드포인트가 표시되어 있습니다. 예제에서는 $GATEWAY와 $NODE_RPC를 사용합니다 — 시작하기를 참고하십시오.

규칙 ​

금액 ​

  • 온체인 금액은 uNRO 단위의 정수입니다(1 NRO = 1 000 000 uNRO).
  • 응답에는 각 금액 옆에 형식화된 *_human 문자열(balance_human, value_human, stake_human, …)이 추가됩니다. 이 값을 표시하고, 클라이언트에서 변환하지 마십시오.
  • 요청 본문에서는 엔드포인트가 달리 명시하지 않는 한 금액을 uNRO 단위의 JSON 숫자로 보내십시오.

서명 작업 ​

상태를 변경하는 모든 엔드포인트에는 서명이 필요합니다. 두 종류가 있습니다:

종류서명되는 메시지nonce
트랜잭션 (POST /api/v1/transactions)`nc-tx-v2from
작업 (그 밖의 모든 것)`nc-tx-v2actor

target은 작업을 나타내는 예약된 시스템 주소이며, 표의 서명 대상 열에 나와 있습니다. 모든 요청에는 signature(hex), public_key(hex ML-DSA-65), nonce가 포함됩니다. 지갑 → 서명 작업을 참고하십시오.

CHAIN_ENV=mainnet(기본값)에서는 서명이 없거나 유효하지 않으면 401로 거부됩니다. CHAIN_ENV=testnet에서는 노드가 대신 경고를 기록합니다 — 로컬 개발 전용입니다.

대부분의 작업은 합의에서 적용됩니다: 응답에는 "status": "pending"과 tx_hash가 반환되며, 해당 트랜잭션이 블록에 포함되면 효과가 보입니다.

페이로드 서명 ​

위의 서명은 행위자, 대상, 값을 명시하지만 작업의 나머지 부분 — 수신자, 세션 키의 범위, 투표 — 은 포함하지 않습니다. mainnet에서는 모든 작업이 그 작업이 다루는 모든 것에 대한 페이로드 서명도 함께 가지므로, 블록 제안자도 중계 노드도 이를 변경할 수 없습니다:

  • 작업(스테이크, 신뢰 목록, 투표, NFT 전송, 세션 키, 볼트, 등록…): 엔드포인트는 작업을 대기열에 넣지 않습니다. 대신 { "needs_payload_signature": true, "op", "sign_payload", "prepared" }로 응답합니다. 같은 키로 sign_payload(nc-op-v1|…, 노드가 생성)에 서명하고 { …prepared, "payload_signature": "<hex>" }를 POST /api/v1/markers/submit으로 보내면 작업이 대기열에 들어갑니다.
  • 자산 및 거래소 작업: 요청(사람이 읽는 금액)을 route, from, nonce와 함께 POST /api/v1/dex/prepare로 보내면 canonical 메시지, 원시 payload, 사람이 읽을 수 있는 summary가 반환됩니다. canonical에 서명하고 같은 요청을 payload_signature와 함께 해당 엔드포인트로 보내십시오.

캐비닛과 거래소는 두 가지를 모두 대신 처리하며, 서명하기 전에 작업 내용을 보여 줍니다.

오류 ​

오류는 JSON {"error": "<message>"} 형식이며, 때로는 hint나 추가 필드가 포함됩니다. 사용되는 HTTP 코드:

코드의미
200성공 — 단, 일부 오래된 엔드포인트는 200과 함께 {"error": …}를 반환하기도 하므로 항상 error를 확인하십시오
400잘못된 요청, 검증 실패, Sentinel 거부
401서명이 없거나 유효하지 않음, 키가 주소에 바인딩되지 않음
403이 모드에서 금지됨(mainnet의 faucet, mainnet에서 합의 없는 쓰기 호출), VMGuardian이 배포를 거부함
404찾을 수 없음
409이미 사용 중인 이름
429요청 한도 초과
502 / 503Gateway가 노드에 연결할 수 없음

페이지네이션 ​

목록 엔드포인트는 limit과 offset(일부는 page도)을 받습니다. 각 엔드포인트는 limit의 상한(보통 100 또는 200)을 둡니다.

요청 한도와 CORS ​

위치기본값변수
노드 RPC, IP당초당 100 요청NEUROCHAIN_RPC_RATE_LIMIT
Gateway, IP당초당 200 요청GLOBAL_RL_MAX_RPS
Gateway AI 엔드포인트(/contracts/audit, /contracts/generate, …), IP당분당 10 요청AI_RL_MAX_RPM

허용 출처: 두 서비스 모두 CORS_ALLOWED_ORIGINS(기본값 *).

네트워크와 노드 ​

메서드경로비고
GET/healthstatus, height, round, mempool, peers, tps, total_txs, validator_count, bft_quorum, bft_ready
GET/status, /api/v1/status노드 전용. 높이, 검증자, 샤드, 네트워크 이름
GET/api/v1/network/statusGateway 전용. 익스플로러용 네트워크 요약
GET/metricsPrometheus 텍스트 형식 — 노드 실행 참고
GET/api/v1/shards샤드별 높이와 루트
GET/api/v1/state/rootglobal_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/estimatebase_fee, 작업별 가스, total_burned, nft_transfer_fee — 가스와 수수료 참고
GET/api/v1/wasm/versionGateway 전용. 브라우저 WASM 모듈의 버전 매니페스트

블록 ​

메서드경로비고
GET/api/v1/blockslimit(≤ 100, 기본값 20), offset, page. 최신순
GET/api/v1/blocks/latestGateway 전용. { "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—Merkle 포함 증명: leaf_index, proof, tx_root, block_height
POST/api/v1/transactions/:hash/confirmneuro:system.trust보류된 이체를 승인합니다(소유자의 메인 키만 가능) — Sentinel 참고
POST/api/v1/transactions/:hash/cancelneuro:system.trust보류된 이체를 취소합니다
GET/api/v1/held/:address—주소의 보류된 이체
GET/api/v1/cross-shard/queue—샤드 간 중계. status, limit, offset

POST /api/v1/transactions 본문

필드타입필수의미
fromstring예발신자 주소
tostring예수신자, 컨트랙트 또는 neuro:system.deploy
valuenumber예uNRO
noncenumber예다음 계정 nonce
signaturestring예`nc-tx-v2
public_keystring예ML-DSA-65 공개 키, hex
gas_pricenumber아니요가스 단위당 uNRO. 기본 수수료 이상이어야 합니다
datastring아니요JSON 문자열로 된 컨트랙트 호출 또는 배포(hex도 허용) — ABI, 배포 참고

응답: tx_hash, status: "pending", estimated_block. Sentinel이 플래그를 지정하면 sentinel_score와 sentinel_warning이, 정책 계층이 보류하면 held 세부 정보가 추가됩니다.

계정 ​

메서드경로비고
GET/api/v1/accounts/:addressbalance, 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/humanneuro:system.name노드 전용. name, owner, + 서명 필드. 사용자 지정 .human 이름을 등록합니다
GET/api/v1/addresses/human/price—노드 전용. ?name= → 길이에 따른 가격
POST/api/v1/nodes/registerneuro:system.nodename, owner, 선택 사항 node_address(.app / .vault 등록용), + 서명 필드
GET/api/v1/nodes—등록된 노드
GET/api/v1/nodes/:address—노드 레코드 하나
PUT/POST/api/v1/nodes/:address/profileneuro:system.nodedescription, website, commission_bps, p2p_endpoint, rpc_endpoint
POST/api/v1/nodes/:address/unjailneuro:system.nodejail 기간이 지난 후 검증자 집합에 다시 들어갑니다(소유자가 서명)
POST/api/v1/nft/transferNFT 주소nft_address, from(현재 소유자), to, + 서명 필드. 수수료 100 uNRO
GET/api/v1/nft/:address—NFT 레코드와 전송 내역
GET/api/v1/nft/owner/:address—주소가 소유한 NFT
POST/api/v1/agents/registerneuro:system.agentname, owner, + 서명 필드. .agent를 등록합니다
GET/api/v1/agents/:address—에이전트 레코드

스테이킹 ​

메서드경로서명 대상본문 / 비고
POST/api/v1/staking/stakeneuro:system.stakeaddress, amount, + 서명 필드
POST/api/v1/staking/unstakeneuro:system.stakeaddress, + 서명 필드
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/proposeneuro:system.governanceproposer, title, description, kind(text / PARAM_CHANGE), payload, voting_duration, + 서명 필드
POST/api/v1/governance/:id/voteneuro:system.governancevoter, 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 전용. NRC-20 이름, 심볼, decimals, 공급량
POST/api/v1/contracts/:address/call—function, args, dry_run, gas_limit, caller. dry_run: true로 읽기. mainnet에서는 쓰기가 거부됩니다
POST/api/v1/contracts/deployneuro: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/certifyneuro:system.cert보안 인증서 발급(VMGuardian 운영자)
POST/api/v1/contracts/whitelistneuro:system.whitelist노드 전용. bytecode_hash — 신뢰할 수 있는 템플릿 바이트코드
PATCH/api/v1/contracts/:address/scoreneuro: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/registerneuro:system.templatesauthor(.node), name, description, category, bytecode_hex, abi_json, fee_unro, + 서명 필드
POST/api/v1/templates/deprecateneuro:system.templates노드 전용. template_id, author, delete, + 서명 필드

AI와 모델 ​

메서드경로비고
GET/api/v1/ai/statusGateway 전용. 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/logAI 결정 로그. 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/healthGateway 전용. 문서 도우미(ASSISTANT_ENABLED=1이 아니면 꺼져 있음)

Sentinel 신뢰 목록 ​

메서드경로서명 대상본문
POST/api/v1/trust/addneuro:system.trustowner, recipient, + 서명 필드
POST/api/v1/trust/removeneuro:system.trustowner, recipient, + 서명 필드
GET/api/v1/trust/:owner—활성화 높이가 포함된 신뢰 수신자

계정 추상화 ​

메서드경로서명 대상본문
POST/api/v1/session/grantneuro:system.sessionaccount, session_pk, scope, cap, expiry_block, + 서명 필드
POST/api/v1/session/revokeneuro:system.sessionaccount, session_pk, + 서명 필드
GET/api/v1/session/list/:account—계정의 세션 키
POST/api/v1/sponsor/depositneuro:system.sponsoraddress, amount, + 서명 필드
POST/api/v1/sponsor/withdrawneuro:system.sponsoraddress, amount, + 서명 필드
GET/api/v1/sponsor/:address—스폰서 풀 잔액

계정 추상화를 참고하십시오.

신원과 복구 ​

이 작업들은 nc-tx-v2가 아닌 자체 메시지(예: nc-rotate|addr|add|remove|nonce)에 서명합니다. 신원을 참고하십시오.

메서드경로본문
POST/api/v1/identity/rotateowner, add, remove, + 서명 필드
POST/api/v1/identity/recovery/setupowner, guardians, threshold, timelock, + 서명 필드
POST/api/v1/identity/recovery/requesttarget, new_key, + 서명 필드
POST/api/v1/identity/recovery/approvetarget, guardian, + 서명 필드
POST/api/v1/identity/recovery/rejecttarget, guardian, + 서명 필드
POST/api/v1/identity/recovery/withdrawtarget, + 서명 필드
POST/api/v1/identity/recovery/cancelowner, + 서명 필드
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/issuefrom, name, symbol, decimals, initial, max_supply, reissuable, reissue_unlock_height, issue_nonce, + 서명 필드. 수수료 asset_issue_fee
POST/api/v1/assets/transferfrom, to, asset_id, amount, + 서명 필드
GET/api/v1/dex/pools, /api/v1/dex/pools/:id풀
POST/api/v1/dex/poolsfrom, asset_x, asset_y, amount_x, amount_y, + 서명 필드
POST/api/v1/dex/liquidity/addfrom, pool_id, max_a, max_b, + 서명 필드
POST/api/v1/dex/liquidity/removefrom, pool_id, shares, + 서명 필드
GET/api/v1/dex/quote스왑 견적
POST/api/v1/dex/swapfrom, 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 포지션, 활동

| POST | /api/v1/dex/prepare | 위 작업 중 하나의 요청에 route(예: dex/swap), from, nonce를 더한 것 → canonical, payload, summary. 아무것도 대기열에 들어가지 않습니다 |

모든 자산 및 거래소 작업은 neuro:system.assets에 대해 서명하고 합의에서 적용되며, 노드가 준비한 메시지(nc-asset-op-v1|op|from|fields|nonce)에 대한 페이로드 서명을 payload_signature로 포함합니다. 보호되거나 예약된 티커 또는 자산 이름은 거부됩니다.

준비된 작업 ​

메서드경로본문 / 비고
POST/api/v1/markers/submit{ tx, auth_to, auth_value, payload_signature } — 작업 응답의 prepared 부분과 그 sign_payload에 대한 서명입니다. 두 서명을 모두 확인하고 작업을 대기열에 넣습니다

IBC v2 실험적 ​

메서드경로본문 / 비고
POST/api/v1/ibc/channel/openfrom, channel, port, counterparty_chain, allowed_denoms, + 서명 필드
POST/api/v1/ibc/channel/pausefrom, channel, paused, + 서명 필드
POST/api/v1/ibc/transferfrom, channel, dest_chain, receiver, denom, amount, + 서명 필드
POST/api/v1/ibc/recvfrom, packet_id, receiver, denom, amount, + 서명 필드
POST/api/v1/ibc/ackfrom, id, + 서명 필드
POST/api/v1/ibc/redeemfrom, 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와 샤딩을 참고하십시오.

개발자 문서 · nro.world

© 실험적 연구 소프트웨어