Skip to content
Consensus Consensus Consensus Docs

Pay-per-use WebSocket sessions with time and data limits

Consensus gives you WebSocket sessions with limits built in. You ask for a session of a certain length, a certain amount of data, or both; the network opens it, meters it as it runs, and closes it cleanly when the limit is reached. There is no account to create and nothing billed after the fact.

Use it for real-time data feeds, chat and agent sessions, live dashboards, and anything else that needs a long-lived connection with a predictable cost.

How a session works

Section titled “How a session works”
  1. Get a token. Ask for a session with GET /ws, choosing a billing model and limits. When payment is on, this is the step you pay for, once and up front.
  2. Connect. Open the WebSocket at the connect_url you get back, within 60 seconds. The token works once.
  3. Use it. The first message, session_start, confirms your limits. Traffic flows normally after that.
  4. It ends cleanly. When the time or data limit is reached, you receive session_expired and the connection closes. Start a new session to keep going.
ModelLimited byUse when
hybridTime and data, whichever runs out first (default)You want both bounds
timeMinutesTraffic volume is unpredictable
dataMegabytesSessions are long but light

From your code

Section titled “From your code”
import { SocketClient, createPaymentFetch } from '@canister-software/consensus-cli'


const client = SocketClient(await createPaymentFetch())


// 1. Get a token for a 10-minute, 100 MB session
const auth = await client.requestToken({ model: 'hybrid', minutes: 10, megabytes: 100 })


// 2. Connect, and handle messages
const session = await client.connect(auth)
session.on('message', (msg) => console.log('received', msg))
session.send('hello')


// Close when you are done
session.close()

SocketClient reconnects automatically after an unexpected disconnect by requesting a fresh token with the same parameters. See the SDK reference for every option, including spend limits and safe mode.

Choose where it runs

Section titled “Choose where it runs”

Pass nodeRegion (such as east-us), nodeDomain, or nodeExclude (node IDs) to requestToken() to choose which node serves the session. To keep a session on one IP address, pin it to a node; see Static IP for API whitelisting.

From the terminal

Section titled “From the terminal”

Open an interactive session and type messages to send them:

Terminal window
consensus ws connect --model hybrid --minutes 5 --megabytes 50

Or just get a token and connect with your own client:

Terminal window
consensus ws token --model time --minutes 10

If you have leased a node with consensus ip lease, both commands use it.

Next steps

Section titled “Next steps”