createNodeConnection

createNodeConnection opens a raw TCP socket to one node. For most production use, createNodePool is a better choice — it handles failover automatically. Use a direct connection when you're targeting a specific peer or building monitoring tooling.

`createNodeConnection(host, options?)`

import { createNodeConnection, requestCurrentTickInfo } from "@qubic.org/tcp"

const conn = await createNodeConnection("node1.qubic.org")
try {
  const { tick, epoch } = await requestCurrentTickInfo(conn)
  console.log(`Epoch ${epoch}, tick ${tick}`)
} finally {
  conn.close()
}

Parameters

Name	Type	Default	Description
`host`	`string`	—	Node hostname or IP address
`options.port`	`number`	`21841`	TCP port
`options.timeoutMs`	`number`	`10000`	Connection and request timeout in milliseconds

Returns Promise<NodeConnection>

Throws QubicTcpConnectionError — if the connection cannot be established within the timeout.

`conn.request(type, payload?, options?)`

Sends a raw TCP frame and collects all response packets until END_RESPONSE. Handles TRY_AGAIN (server busy) automatically — waits 1 second and resends.

import { MESSAGE_TYPE } from "@qubic.org/tcp"

const packets = await conn.request(MESSAGE_TYPE.REQUEST_CURRENT_TICK_INFO)
// packets: Uint8Array[] — all response payloads

Name	Type	Description
`type`	`number`	Message type constant from `MESSAGE_TYPE`
`payload`	`Uint8Array \| undefined`	Optional request payload
`options.signal`	`AbortSignal \| undefined`	Cancels the request

Returns Promise<Uint8Array[]>

Throws QubicTcpTimeoutError — if the signal fires or the timeout is exceeded.

`conn.close()`

Closes the TCP socket. Always call this when done — open sockets block process exit.

Error types

Class	When thrown
`QubicTcpError`	Base class
`QubicTcpConnectionError`	Could not connect within timeout
`QubicTcpTimeoutError`	Request timed out or AbortSignal fired

createNodeConnection