Skip to content
SineraDocs

Self-host the Explorer

Run your own copy of ATP Explorer with Node.js 22 and pnpm, configure it with environment variables, and set load limits.

You can run your own copy of ATP Explorer. It is a Next.js application that reads the ATP deployment over JSON-RPC. It has no wallet, holds no key, and submits no transactions.

Implementation candidate

If you only want to read ATP state, use the hosted copy at explorer.sinera.io. See Get started.

Requirements

  • Node.js 22
  • pnpm

Run it

pnpm install
pnpm dev            # http://localhost:3000

By default the Explorer reads the BSC Testnet deployment over RPC. To run on example records without a network, set the ledger source to sample:

ATP_LEDGER=sample pnpm dev

Pages then carry a Sample data badge. See Networks and data sources.

Configure it

Copy .env.example to .env.local and adjust the values.

VariablePurposeDefault
ATP_LEDGERchain reads the network. sample uses example records.chain
ATP_BSC_TESTNET_RPC_URLJSON-RPC endpoint for BSC Testnet, used on the server only.A public endpoint
ATP_LOOKUP_UNITS_PER_MINUTELoad units each client may spend per minute.60
ATP_LOOKUP_BURST_UNITSThe burst allowance for load units.40
ATP_LOOKUP_MAX_IN_FLIGHTUpstream reads allowed at once.6
ATP_TRUSTED_PROXY_HOPSHow many reverse proxies you run in front of the application.0
ATP_LOOKUP_REQUESTS_PER_MINUTEFull page loads per client per minute for /tx/*, /lookup and /verify.60
ATP_LOG_RPC1 logs the method of every upstream request, to count what a page costs.Unset
NODE_USE_ENV_PROXY, NODE_EXTRA_CA_CERTSNeeded only when the server reaches the internet through an HTTPS proxy.Unset

Choose an RPC endpoint without a key in its host name

The host name of the RPC endpoint is displayed on the pages. Use an endpoint that does not carry a key in its host name. A key in the path or query is never shown.

If the RPC cannot be read, the ledger pages say so. Example records are never shown in place of real ones.

Rate limits

Pages that read the chain for a value the visitor chose are limited per server process. These are /tx/*, /lookup and /verify.

  • The unit budget limits how much each client may read per minute. A transaction read costs 2 units, and a verification costs 4.
  • The in-flight cap limits upstream reads at once.
  • The page-load limit counts full page loads only. Client navigations and prefetches are not counted. Over the limit, the Explorer answers with status 429.

Running behind a proxy

Set ATP_TRUSTED_PROXY_HOPS when you run behind a load balancer, a CDN or an ingress. With a value N above 0, the client address is the entry N places from the right end of X-Forwarded-For, the one your outermost proxy appended. A request with fewer entries, or an entry that is not an IP address, counts as having no address.

With 0, the header is ignored, because anyone can write it. A request with no client address gets no budget of its own. Only the shared budget and the cap on reads at once limit it. Without a trusted proxy configured, the application cannot tell clients apart, and one caller can use up the shared budget for everyone.

Built with

Next.js, React, Tailwind CSS, shadcn/ui with ReUI components, viem, and the ATP TypeScript SDK. To read ATP state from code instead, see the developer SDK docs.