RPC

The RPC interface lets a wallet or another program ask a node for balances, inspect account history and submit signed actions. It uses HTTP requests with JSON bodies. Send JSON to / on the RPC listener, which defaults to http://127.0.0.1:7077. This is not JSON-RPC 2.0: requests use action, not method, and have no request ID.

Make a request

curl http://127.0.0.1:7077/ \
  -H 'Content-Type: application/json' \
  -d '{"action":"account_balance","account":"YOUR_ACCOUNT_ADDRESS"}'

Replace YOUR_ACCOUNT_ADDRESS with a valid BURST address. A successful response has a result object. For example, an account with five BRN and two TRST returns:

{
  "result": {
    "brn_balance": "5000000000000000000",
    "trst_balance": "2000000000000000000"
  }
}

An action failure returns an error string instead. Check both the HTTP status and the response body. Authentication, request-size and capacity failures can reject a request before its action runs.

Amounts are decimal strings in raw units. One BRN or TRST is 10^18 raw. Use integers such as JavaScript BigInt; converting a balance to Number can lose precision. Timestamps are Unix seconds.

Read account state

Action	Input	Use
account_info	account	Head, balances, verification state, representative and confirmation height.
account_balance	account	Current BRN calculation and recorded TRST balance.
brn_components	account	Eligibility periods, spending, stakes and rate history for a local BRN calculation.
trst_portfolio	account	TRST totals classified by state, including pending outgoing value.
account_history	account, optional count, cursor	Page through account blocks.
account_pending	account, optional hash, threshold, count, cursor	Payments and return credits available to receive.
account_representative	account	The account's selected representative.
verification_status	account	Current verification state and related verification information.

account_history.history[].amount is the block's TRST balance, not the amount sent by that block. Similarly, block_info.brn_balance is cumulative BRN committed by burns and stakes, not the spendable allowance returned by account_balance.brn_balance. The names are retained in the wire format; applications must distinguish them.

For spendable TRST selection, use the portfolio and origin APIs. A balance total alone does not tell you which holdings can fund a payment.

Page through results

List actions that use PaginationParams default to 100 entries and clamp count to 1–1000. Pass the returned cursor unchanged to the same action with the same filters. Stop when it is absent. A final cursor can lead to an empty page. governance_proposals has a stricter limit: use count of 100 or less; the committed-state reader rejects larger pages.

History runs from older to newer account heights. The cursors do not hold a snapshot across requests. If the head changes while history is being read, the request can fail and should be retried. Missing local block bodies are fetched; unavailable history returns an error rather than an incomplete successful page.

{"action":"account_history","account":"YOUR_ACCOUNT_ADDRESS","count":25}

account_pending also accepts one source hash. That form returns at most one entry and no cursor. Its threshold is an inclusive minimum amount in raw units. A pending entry includes return_credit; an expiry return credit acknowledges value already returned, rather than delivering it again.

Submit a signed block

Create and sign the block locally with burst-wallet-core, then submit it using process. Keep private keys out of RPC requests.

The block field is a string containing the serialized block JSON, or hex-encoded bincode bytes. It is not a nested JSON object. If signed-block.json contains the exact serialized block produced by your signer:

python3 - <<'PY' > process-request.json
import json
from pathlib import Path
block = Path('signed-block.json').read_text()
print(json.dumps({'action': 'process', 'block': block}))
PY
curl http://127.0.0.1:7077/ \
  -H 'Content-Type: application/json' \
  --data-binary @process-request.json

Wrapping the original text this way preserves large integers inside the signed block. Do not parse and re-serialize it through JavaScript Number.

The result includes hash, accepted and sometimes detail. accepted: true means the node accepted or queued the block; it does not mean consensus has confirmed it. Query block_info and inspect confirmed:

{"action":"block_info","hash":"YOUR_BLOCK_HASH"}

Use include_signed_block: true when you need the full signed block. The returned signed_block is also a JSON string. blocks_info accepts a hashes array and returns individual block results or errors.

If a submission times out, retain its signed bytes and hash. Query its outcome before preparing a replacement. See pending actions.

Work and protocol state

Action	Use
params_hash	Signing compatibility, payment epoch, block version and work threshold.
protocol_params	Current parameter values; amounts remain decimal strings.
work_generate	Generate work for a predecessor hash or an account-bound opening root.
telemetry	Network, counts, uptime and signing-clock status.
peers, peers_detailed	Peer connections.
representatives, representatives_online	Representative information.
bootstrap_status	Bootstrap phase and creator-authority information.
checkpoint_sync_status	Checkpoint synchronization state.

work_generate accepts hash, optional difficulty, and optional block_type. Use the wallet's work preparation methods to choose the correct root and threshold. The returned multiplier is a threshold ratio, not an estimate of computation time.

The node does not populate representatives_online yet. An empty response does not mean that all representatives are offline.

Governance, verification and provenance

These queries support the corresponding application screens:

Area	Actions
Governance	governance_proposals, governance_proposal_info, consti
Verification	verification_activity, verifier_assignments, appeal_review
Delegation	delegation_info, delegation_keys
TRST history	trst_origins, trace_origin, merger_graph_stats
Recovery	confirmed_account_slot, payment_exclusion

Use the typed requests in burst-rpc-messages for their fields. Some depend on experimental features or specific checkpoint state; a listed RPC action is not a promise that its operation is enabled on Live.

Compatibility and test actions

send, burn and receive reject unsigned requests and direct callers to process. They are not server-side wallet APIs. wallet_create generates an address and public key but discards the private key; it cannot create a usable wallet. Create wallet keys locally instead. wallet_info aliases account_info, and node_info aliases telemetry.

The faucet and private-key-taking helpers are for disposable Dev/Test fixtures. They require the faucet option and are rejected on Live. This includes wallet_create_full, burn_simple, send_simple, receive_simple, change_rep_simple and the simple governance/verifier helpers. Do not build a wallet integration around sending private keys to these endpoints. The test helper governance_propose_eviction ignores its reason field and submits no content.

genesis_endorse is a separate bootstrap administration action. It requires Authorization: Bearer <token> and is subject to the creator's bootstrap window. The response's verified field reports the target state after endorsement confirmation; a confirmed endorsement alone need not verify the target. Similarly, verifier helpers return the requested opted_in state, not confirmation. See RPC access controls.

Batches and limits

A request body can be an array of up to 32 action objects. Each action consumes rate-limit capacity. Batches are not an atomic ledger transaction. For listener, work-generation and WebSocket limits, see RPC and networking.

Source: HTTP routing and response envelopes, request and response types, handlers.