SR API configuration

ℹ️

SR API configuration

Part of SR best practices — this page is the deep-dive walkthrough for the API configuration practice.

📘

Prerequisites

• Super Representatives
• Becoming a Super Representative

TRON full nodes expose HTTP and gRPC APIs by default, which is exactly what monitoring tools, wallets, and read-heavy clients need. A Super Representative has different priorities: the node's job is producing blocks reliably, and any CPU or event-loop time spent serving API calls is time not spent on consensus. TRON gives you three configuration levers to trim the API surface to whatever an SR actually needs — who can reach it, which methods are served, and how fast traffic comes in. None of these are required to run an SR; they are tuning options for operators who want to give the consensus path more headroom.

Network reach

By default an SR has no operational reason to expose its API publicly — block production and peer gossip happen entirely between nodes over the P2P channel.

If you do need external access — for internal monitoring, or because the same node also doubles as a public RPC endpoint — enforce reach at the network gateway. Firewall rules or an Nginx reverse proxy with an IP allowlist of trusted hosts is the usual setup.

Endpoint selection

TRON lets you turn off specific HTTP and gRPC methods that the SR doesn't need to serve. Common candidates are /wallet/listnodes and /wallet/getnodeinfo — an SR typically has no reason to publish its peer list or node metadata. Disabling them removes the call paths and a small amount of routing overhead.

Configure with disabledApi in config.conf :

node {
  # Method names to block. Case-insensitive.
  # Use the method name only, not the URL path.
  disabledApi = [
    "listnodes",
    "getnodeinfo"
  ]
}

The block applies to both HTTP and gRPC handlers serving these methods. Add or remove entries to match your deployment — there is no canonical "must disable" list.

Traffic caps

Rate limits keep API traffic — including legitimate traffic from a noisy client — from competing with the consensus thread for CPU and event-loop capacity. They are most useful when the SR also serves external clients.

gRPC and JSON-RPC differ in what they can rate-limit:

Configure both in config.conf:

rate.limiter = {

  # gRPC: per-method limits
  rpc = [
    {
      component = "protocol.Wallet/ListWitnesses",
      strategy = "QpsRateLimiterAdapter",
      paramString = "qps=200"
    }
  ]

  # HTTP / JSON-RPC: global JSON-RPC + selective HTTP method limits
  http = [
    {
      component = "JsonRpcServlet",
      strategy = "QpsRateLimiterAdapter",
      paramString = "qps=200"
    },
    {
      component = "GetTransactionInfoByIdServlet",
      strategy = "QpsRateLimiterAdapter",
      paramString = "qps=50"
    }
  ]
}

Handling requests that exceed a rate limit

rate.limiter.apiNonBlocking controls how HTTP and gRPC requests are handled after they exceed a configured rate limit. It defaults to false, which waits for rate-limit capacity; when set to true, the node rejects an over-limit request immediately.

Choosing QPS values. Tune to your hardware and workload:

• 100–500 QPS for an SR node's overall public ingress.
• 50–100 QPS for read-heavy endpoints like getTransactionInfoById and getBlockByNum.
• Up to 1000 QPS for cheap reads such as ListWitnesses and getNowBlock.

Start conservative; raise limits if legitimate clients are hitting the cap.

📘

Note

gRPC component naming. Component names must include the service prefix (for example protocol.Wallet/ListWitnesses).

API request and response limits

The following settings limit the size of an individual request, response, or result set independently of the QPS limits above:

Before changing a default, account for reverse-proxy limits, legitimate client request sizes, and available node memory.

Related resources

• SR node configuration — Witness permission delegation and localwitness setup.
• SR best practices — Availability, monitoring, and upgrade hygiene.
• Becoming a Super Representative — Application and registration flow.
• Consensus and DPoS — Block production schedule and the cost of a missed slot.