Bridge API

Bridge API

The WebSocket bridge connects the browser to the TON blockchain via a local tonutils-bridge process. It exposes a JSON-RPC 2.0 interface over WebSocket, organized into namespaces.

Connection

• Address: ws://127.0.0.1:<wsPort> (default 8081, configurable in Settings > Network)
• Reconnect delay: 2 seconds on disconnect
• RPC timeout: 60 seconds per request
• Request IDs are rewritten internally (UUID) and restored in responses

Push notifications (messages with method but no id) are forwarded only to tabs that have made at least one subscribe.* call.

Namespaces

Required (always enabled)

Namespace	Description
lite	Blockchain queries: accounts, transactions, blocks, send messages
wallet	Wallet seqno and public key queries
subscribe	Real-time account state and transaction subscriptions
dns	TON DNS domain resolution

Optional (disabled by default)

Enable via Settings > Bridge > Namespaces.

Namespace	Description
jetton	Jetton token data and wallet addresses
nft	NFT item and collection data
sbt	Soul-bound token queries
payment	Payment channel state queries
network	Network status and connectivity info
adnl	Peer-to-peer ADNL connections
overlay	Overlay network participation
dht	Distributed hash table lookups
subscribe_trace	Deep transaction trace subscriptions

A namespace is disabled only when enabled is explicitly set to false. If absent from configuration, it defaults to enabled.

Extended Configuration

Some namespaces support additional options:

lite: send_wait_timeout, watch_timeout

subscribe: max_subscriptions, max_multi_accounts, max_config_params

subscribe_trace: max_depth, default_depth, max_msg_timeout, default_msg_timeout, max_resolvers

adnl: max_peers, query_max_timeout, ssrf_protection

overlay: max_overlays, query_max_timeout

dht: tunnel_timeout, allow_write

Permission System

Every JSON-RPC method requires a permission check before it reaches the bridge.

Scopes

Scope	Description	Namespaces
blockchain	Read blockchain data	lite, subscribe, dns, jetton, nft, wallet, sbt, payment, network
p2p	Connect to the TON P2P network	adnl, overlay, dht (read methods)
write	Broadcast data to the network	Specific methods only (see below)

Write-scope methods

These methods require write permission regardless of their namespace:

• lite.sendMessage, lite.sendMessageWait, lite.sendAndWatch
• dht.storeAddress, dht.storeOverlayNodes
• adnl.sendMessage, adnl.setQueryHandler, adnl.answer
• overlay.sendMessage, overlay.setQueryHandler, overlay.answer

Methods not matching any known namespace return JSON-RPC error -32601 (Unknown method).

Decisions

Decision	Meaning	Persisted to disk
granted	Permanently allowed (user clicked "Always Allow")	Yes
denied	Permanently blocked	Yes
session	Allowed until the last tab for that domain closes	No

Request Flow

1. methodToScope(method) determines the required scope. Unknown methods return error -32601.
2. Existing permission is checked for the domain + scope pair:
   • denied: return error -32003 immediately
   • granted or session: forward to bridge
   • unknown: check default policy
3. If default policy is deny: return error -32003 without prompting
4. If default policy is ask: show permission prompt

Permission Prompt

A centered overlay dialog (400 x 240 px) with:

• Title: "Bridge Permission: <domain>"
• Description of what the scope allows
• Three buttons: Deny, Allow (session-only), Always Allow (permanent)
• Dismissing the dialog is treated as Deny

Concurrent requests for the same domain + scope share a single prompt. The second request waits for the first prompt to resolve.

Session Grant Revocation

When a tab closes:

1. The tab is removed from active tracking
2. If no other tab shares the same domain, all session grants for that domain are revoked
3. Permanent grants (granted, denied) are unaffected

Default Policy

Configurable in Settings > Bridge > Default Policy:

• ask (default): show permission prompt for unknown requests
• deny: reject all unknown requests silently