VAGACHAIN

API REFERENCE

System

GET/health

Node health and runtime summary

Responses

Status	Description	Schema
`200`	Health summary	object

GET/state

Full runtime snapshot

Responses

Status	Description	Schema
`200`	Runtime snapshot	object

GET/state/indexer-snapshot

Binary snapshot contract for the indexer

Responses

Status	Description	Schema
`200`	Binary-encoded snapshot	binary
`500`	Snapshot encoding error	object

GET/ws

WebSocket notifications endpoint

Upgrades to a WebSocket connection. The server sends an initial welcome message containing a runtime snapshot and then streams node notifications. Sending the text message `ping` returns `{"type":"pong"}`.

Responses

Status	Description	Schema
`101`	WebSocket upgrade	—

Events

GET/events

List runtime event log records

Parameters

Name	In	Type	Required	Description
`from_seq`	query	integer	no	—
`limit`	query	integer	no	—
`event_type`	query	string	no	—

Responses

Status	Description	Schema
`200`	Event list	object

REST

GET/api/agent/{agent_id}

Get agent summary

Parameters

Name	In	Type	Required	Description
`agent_id`	path	string	yes	VAGA agent address, usually `vaga...` or legacy `0x...`

Responses

Status	Description	Schema
`200`	Agent summary	object
`400`	Invalid request	object
`404`	Resource not found	object

GET/api/balance/{agent_id}

Get balance summary for one agent

Parameters

Name	In	Type	Required	Description
`agent_id`	path	string	yes	VAGA agent address, usually `vaga...` or legacy `0x...`

Responses

Status	Description	Schema
`200`	Balance breakdown	object
`400`	Invalid request	object
`404`	Resource not found	object

GET/api/sla/{sla_id}

Get SLA summary

Parameters

Name	In	Type	Required	Description
`sla_id`	path	integer	yes	—

Responses

Status	Description	Schema
`200`	SLA summary	object
`404`	Resource not found	object

GET/api/dispute/{dispute_id}

Get dispute summary

Parameters

Name	In	Type	Required	Description
`dispute_id`	path	integer	yes	—

Responses

Status	Description	Schema
`200`	Dispute summary	object
`404`	Resource not found	object

GET/api/transfers

List treasury transfer events

Parameters

Name	In	Type	Required	Description
`from_agent`	query	string	no	Optional sender filter
`to_agent`	query	string	no	Optional recipient filter
`limit`	query	integer	no	—

Responses

Status	Description	Schema
`200`	Transfer list	object
`400`	Invalid request	object

Explorer

GET/api/explorer

Explorer overview

Parameters

Name	In	Type	Required	Description
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—

Responses

Status	Description	Schema
`200`	Explorer overview with aggregated sections	object

GET/api/explorer/transactions

List explorer transactions

Parameters

Name	In	Type	Required	Description
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—
`agent_id`	query	string	no	—
`tx_type`	query	string	no	—

Responses

Status	Description	Schema
`200`	Transaction list	object
`400`	Invalid request	object

GET/api/explorer/transactions/{tx_id}

Get one explorer transaction

Parameters

Name	In	Type	Required	Description
`tx_id`	path	string	yes	—

Responses

Status	Description	Schema
`200`	Transaction detail	object
`404`	Resource not found	object

GET/api/explorer/wallets

List explorer wallets

Parameters

Name	In	Type	Required	Description
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Wallet list	object

GET/api/explorer/wallets/{agent_id}

Get one explorer wallet detail view

Parameters

Name	In	Type	Required	Description
`agent_id`	path	string	yes	VAGA agent address, usually `vaga...` or legacy `0x...`
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Wallet detail view	object
`400`	Invalid request	object
`404`	Resource not found	object

GET/api/explorer/blocks

List explorer blocks

Parameters

Name	In	Type	Required	Description
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Block list	object

GET/api/explorer/blocks/{block_number}

Get one explorer block detail view

Parameters

Name	In	Type	Required	Description
`block_number`	path	integer	yes	—
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Block detail view	object
`404`	Resource not found	object

GET/api/explorer/validators

List explorer validators

Parameters

Name	In	Type	Required	Description
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Validator list	object

GET/api/explorer/validators/{validator_id}

Get one explorer validator detail view

Parameters

Name	In	Type	Required	Description
`validator_id`	path	string	yes	32-byte hex public key
`page`	query	integer	no	—
`page_size`	query	integer	no	—
`limit`	query	integer	no	—
`q`	query	string	no	—

Responses

Status	Description	Schema
`200`	Validator detail view	object
`400`	Invalid request	object
`404`	Resource not found	object

JSON-RPC

POST/rpc

JSON-RPC 2.0 endpoint

Generic JSON-RPC 2.0 entrypoint for VAGAChain write and read methods. See docs/api-reference.md for grouped method lists.

Request Body

Content-Type: application/json · object

system_health request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "system_health",
  "params": {}
}

get_balance request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "get_balance",
  "params": {
    "agent_id": "vaga0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
  }
}

Responses

Status	Description	Schema
`200`	JSON-RPC response	object

Schemas

ErrorBody

Property	Type	Required
`error`	string	yes

Pagination

Property	Type	Required
`page`	integer	no
`page_size`	integer	no
`total`	integer	no
`total_pages`	integer	no
`has_next`	boolean	no
`has_prev`	boolean	no

EventRecord

Property	Type	Required
`seq`	integer	yes
`block_number`	integer	yes
`timestamp_ms`	integer	yes
`event_type`	string	yes
`event`	object	no

EventsResponse

Property	Type	Required
`from_seq`	integer	yes
`next_cursor`	integer	yes
`latest_seq`	integer	yes
`count`	integer	yes
`total_available`	integer	yes
`events`	array<EventRecord>	yes

HealthResponse

Property	Type	Required
`status`	string	yes
`uptime_seconds`	integer	yes
`block_number`	integer	yes
`epoch_index`	integer	yes
`latest_finalized_block`	integer	yes
`latest_finality_certificate_hash`	stringnull	no
`finality_lag_blocks`	integer	yes
`base_fee`	string	no
`external_market_cap_reference`	stringnull	no
`external_market_cap_reported_at`	integernull	no
`persist_pipeline_enabled`	boolean	no
`persist_pipeline_pending`	boolean	no
`persist_pipeline_interval_ms`	integer	no
`rpc_inflight_available`	integer	no
`rpc_per_ip_max_requests`	integer	no
`rpc_per_ip_window_ms`	integer	no
`runtime_event_log_len`	integer	no
`runtime_event_latest_seq`	integer	no

BalanceResponse

Property	Type	Required
`agent_id`	string	yes
`token_symbol`	string	yes
`liquid_balance`	string	yes
`locked_escrow`	string	yes
`locked_collateral`	string	yes
`total_balance`	string	yes

SlaSummary

Property	Type	Required
`sla_id`	integer	yes
`client_agent`	string	yes
`provider_agent`	string	yes
`escrow_amount`	string	yes
`provider_collateral`	string	yes
`deadline`	integer	yes
`status`	string	yes
`risk_class`	integer	yes

DisputeSummary

Property	Type	Required
`dispute_id`	integer	yes
`sla_id`	integer	yes
`challenger_agent`	string	yes
`reason`	string	yes
`opened_at`	integer	yes
`challenge_bond`	string	yes
`jury`	array<string>	yes
`verification_method`	string	yes
`votes_for_challenger`	integer	yes
`votes_for_provider`	integer	yes
`resolved`	boolean	yes
`verdict`	stringnull	no

TransferRecord

Property	Type	Required
`event_index`	integer	yes
`from_agent`	string	yes
`to_agent`	string	yes
`amount`	string	yes
`token_symbol`	string	yes

TransfersResponse

Property	Type	Required
`count`	integer	yes
`transfers`	array<TransferRecord>	yes

PaginatedRowsResponse

Property	Type	Required
`count`	integer	yes
`rows`	array<object>	yes
`filters`	object	no
`pagination`	object	no

JsonRpcRequest

Property	Type	Required
`jsonrpc`	"2.0"	yes
`id`	integer \| string \| object \| array<unknown> \| boolean \| null	yes
`method`	string	yes
`params`	object	no

JsonRpcError

Property	Type	Required
`code`	integer	yes
`message`	string	yes

JsonRpcResponse

Property	Type	Required
`jsonrpc`	"2.0"	yes
`id`	integer \| string \| object \| array<unknown> \| boolean \| null	yes
`result`	object \| array<unknown> \| string \| integer \| number \| boolean \| null	no
`error`	JsonRpcError \| null	no

VAGAChain Node API

System

Node health and runtime summary

Full runtime snapshot

Binary snapshot contract for the indexer

WebSocket notifications endpoint

Events

List runtime event log records

REST

Get agent summary

Get balance summary for one agent

Get SLA summary

Get dispute summary

List treasury transfer events

Explorer

Explorer overview

List explorer transactions

Get one explorer transaction

List explorer wallets

Get one explorer wallet detail view

List explorer blocks

Get one explorer block detail view

List explorer validators

Get one explorer validator detail view

JSON-RPC

JSON-RPC 2.0 endpoint

Schemas

ErrorBody

Pagination

EventRecord

EventsResponse

HealthResponse

BalanceResponse

SlaSummary

DisputeSummary

TransferRecord

TransfersResponse

PaginatedRowsResponse

JsonRpcRequest

JsonRpcError

JsonRpcResponse