Connecting

The RPC client opens a WebSocket to a node. While it’s connected, every RPC method is callable and notifications stream in. You can point it at a node URL you control, or hand it a Resolver and let it find a public one.

All three SDKs wrap the same wRPC client from rusty-kaspa, so the options below mean the same thing everywhere — only the spelling changes.

Connect via the Resolver

The default for most applications. No URL, no node of your own:

use kaspa_wrpc_client::{
    prelude::{NetworkId, NetworkType},
    KaspaRpcClient, Resolver, WrpcEncoding,
};

let client = KaspaRpcClient::new(
    WrpcEncoding::Borsh,
    None,                                       // no url
    Some(Resolver::default()),
    Some(NetworkId::new(NetworkType::Mainnet)),
    None,
)?;

client.connect(None).await?;

const { RpcClient, Resolver } = kaspa;

const rpc = new RpcClient({
	resolver: new Resolver(),
	networkId: 'mainnet'
});

await rpc.connect();

from kaspa import Resolver, RpcClient

client = RpcClient(resolver=Resolver(), network_id="mainnet")
await client.connect()

For security-critical applications, connect to your own node instead. A public node can lie to you about balances and chain state. See Run a Node.

Connect to a known node

Pass a URL and skip the resolver. The node must have wRPC enabled — start it with --rpclisten-borsh:

let client = KaspaRpcClient::new(
    WrpcEncoding::Borsh,
    Some("ws://127.0.0.1:17110"),
    None,                                       // no resolver
    Some(NetworkId::new(NetworkType::Mainnet)),
    None,
)?;

client.connect(None).await?;

const rpc = new RpcClient({
	url: 'ws://127.0.0.1:17110',
	encoding: kaspa.Encoding.Borsh,
	networkId: 'mainnet'
});

await rpc.connect();

from kaspa import RpcClient

client = RpcClient(
    url="ws://127.0.0.1:17110",
    network_id="mainnet",
    encoding="borsh",
)
await client.connect()

URL schemes are ws:// (plaintext) and wss:// (TLS). Default wRPC ports are 17110 (borsh) and 18110 (json) on mainnet — see Network Parameters.

Connection options

connect() takes a few behavioural overrides:

use std::time::Duration;
use kaspa_wrpc_client::client::{ConnectOptions, ConnectStrategy};

client
    .connect(Some(ConnectOptions {
        block_async_connect: true,
        connect_timeout: Some(Duration::from_millis(5_000)),
        strategy: ConnectStrategy::Fallback,
        ..Default::default()
    }))
    .await?;

await rpc.connect({
	blockAsyncConnect: true,
	strategy: 'fallback',
	timeoutDuration: 5000,
	retryInterval: 1000
});

await client.connect(
    block_async_connect=True,
    strategy="fallback",
    timeout_duration=5_000,
    retry_interval=1_000,
)

• block_async_connect — true (the default) makes connect() await until the socket is open. Set it false to return immediately and let the connection complete in the background; poll the connected flag or listen for the connect event to know when it’s ready.
• strategy — retry (the default) loops until a connection succeeds, pausing between attempts; fallback gives up on the first failure. Applies to both URL-based and resolver-driven clients.
• connect_timeout / timeoutDuration — a per-attempt ceiling in milliseconds, not an overall wall-clock budget. Under retry there is no overall ceiling.
• retry_interval — delay between attempts, in milliseconds.

There’s also a per-attempt URL override, which lets you retarget a long-lived client without rebuilding it.

Inspecting the live client

println!("{}", client.is_connected());
println!("{:?}", client.url());       // resolved or supplied node URL
println!("{:?}", client.encoding());
println!("{:?}", client.node_descriptor());

console.log(rpc.isConnected);
console.log(rpc.url);
console.log(rpc.encoding);
console.log(rpc.nodeId); // resolver-supplied node UID

print(client.is_connected)
print(client.url)          # resolved or supplied node URL, or None
print(client.encoding)     # "borsh" or "json"
print(client.node_id)      # resolver-supplied node UID; None for direct URLs
print(client.resolver)     # the Resolver instance, or None

Borsh vs JSON encoding

Borsh — the default — is a compact binary format the node uses natively. Use JSON only to inspect raw frames in a tool that doesn’t speak Borsh, or when targeting a node that hasn’t enabled the Borsh listener.

The two listeners are separate: a node started with only --rpclisten-borsh will refuse a JSON client, and the ports differ.

Reconnects

If the WebSocket drops mid-session, the client reconnects on its own. Calls made during the gap fail; calls made after a successful reconnect work normally.

To stop reconnect attempts, disconnect explicitly — or use the fallback strategy, which gives up after one failed reconnect instead of looping. To observe disruptions, register a listener for the client’s connect and disconnect events — the same event channel node notifications arrive on.

Where to next

• Resolver — how public node discovery actually works.
• RPC Calls — run methods against mainnet directly from the page.
• Transactions — the first thing most people do with a connection.