{"id":48176,"library":"ic-websocket-js","title":"IC WebSocket JS SDK","description":"A JavaScript/TypeScript SDK for WebSocket communication on the Internet Computer (IC) blockchain. Version 0.5.0, actively developed. Enables real-time, bidirectional messaging between dapps and canisters via IC WebSocket gateways. Differentiates from standard WebSocket by integrating with IC authentication and agent-based calls. Requires @dfinity/agent, @dfinity/candid, @dfinity/identity-secp256k1, and @dfinity/principal as peer dependencies. Ships TypeScript types.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/omnia-network/ic-websocket-sdk-js","tags":["javascript","Internet Computer","Rust","JavaScript","Canister","WebSocket","typescript"],"install":[{"cmd":"npm install ic-websocket-js","lang":"bash","label":"npm"},{"cmd":"yarn add ic-websocket-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add ic-websocket-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for interacting with the Internet Computer agent and making authenticated calls.","package":"@dfinity/agent","optional":false},{"reason":"Required for Candid serialization/deserialization of messages.","package":"@dfinity/candid","optional":false},{"reason":"Provides identity and signing for WebSocket connections.","package":"@dfinity/identity-secp256k1","optional":false},{"reason":"Used for handling Principal identifiers.","package":"@dfinity/principal","optional":false}],"imports":[{"note":"Default export is not available; use named import.","wrong":"import icWebSocket from 'ic-websocket-js'","symbol":"IcWebSocket","correct":"import { IcWebSocket } from 'ic-websocket-js'"},{"note":"Type import; also available as a type definition.","wrong":"import { IcWebSocketEvent } from 'ic-websocket-js'","symbol":"IcWebSocketEvent","correct":"import { IcWebSocketEvent } from 'ic-websocket-js'"},{"note":"Utility function for creating WebSocket connections from canister context.","wrong":"","symbol":"createCanisterWebSocket","correct":"import { createCanisterWebSocket } from 'ic-websocket-js'"}],"quickstart":{"code":"import { IcWebSocket } from 'ic-websocket-js';\nimport { HttpAgent } from '@dfinity/agent';\nimport { Secp256k1KeyIdentity } from '@dfinity/identity-secp256k1';\nimport { Principal } from '@dfinity/principal';\n\nconst identity = Secp256k1KeyIdentity.generate();\nconst agent = await HttpAgent.create({ identity });\nconst canisterId = Principal.fromText('rrkah-fqaaa-aaaaa-aaaaa-c'); // example\n\nconst ws = new IcWebSocket({\n  canisterId,\n  agent,\n  gatewayUrl: 'wss://gateway.example.com/ws'\n});\n\nws.addEventListener('open', () => {\n  console.log('connected');\n  ws.send(JSON.stringify({ msg: 'hello' }));\n});\n\nws.addEventListener('message', (event) => {\n  console.log('received:', event.data);\n});\n\nws.addEventListener('close', () => {\n  console.log('disconnected');\n});\n\nws.connect();","lang":"typescript","description":"Creates an IC WebSocket connection using a generated identity and agent, listens for events, and sends a message."},"warnings":[{"fix":"Install @dfinity/agent, @dfinity/candid, @dfinity/identity-secp256k1, @dfinity/principal as peers.","message":"requires peer dependencies to be installed separately","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Ensure gatewayUrl is correct and the gateway is running.","message":"gatewayUrl must be a WebSocket URL (wss://) pointing to an IC WebSocket Gateway","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Use the new object-based configuration: { canisterId, agent, gatewayUrl }. Previous versions may have used positional arguments.","message":"IcWebSocket constructor parameters changed in v0.5.0","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Add event listeners before calling connect() to avoid missing events.","message":"The method connect() must be called explicitly after adding event listeners","severity":"deprecated","affected_versions":">=0.5.0"}],"env_vars":null,"search_vec":"'0.5.0':18 'activ':19 'agent':46 'agent-bas':45 'authent':43 'base':47 'bidirect':25 'blockchain':16 'call':48 'canist':30,66 'communic':10 'comput':14,63 'dapp':28 'depend':57 'develop':20 'dfinity/agent':50 'dfinity/candid':51 'dfinity/identity-secp256k1':52 'dfinity/principal':54 'differenti':35 'enabl':21 'gateway':34 'ic':1,15,32,42 'integr':40 'internet':13,62 'javascript':61,65 'javascript/typescript':6 'js':3 'messag':26 'peer':56 'real':23 'real-tim':22 'requir':49 'rust':64 'sdk':4,7 'ship':58 'standard':37 'time':24 'type':60 'typescript':59,68 'version':17 'via':31 'websocket':2,9,33,38,67","created_at":"2026-06-07T16:55:17.482812+00:00","updated_at":"2026-06-07T16:55:17.482812+00:00","problems":[{"fix":"npm install @dfinity/agent @dfinity/candid @dfinity/identity-secp256k1 @dfinity/principal","cause":"Missing peer dependencies.","error":"Cannot find module '@dfinity/agent' or its corresponding type declarations."},{"fix":"Use 'new IcWebSocket(...)'","cause":"Using IcWebSocket as a function instead of a class constructor.","error":"TypeError: Class constructor IcWebSocket cannot be invoked without 'new'"},{"fix":"Call send() only after the 'open' event fires.","cause":"WebSocket connection not yet open; send() called before connect() or open event.","error":"Uncaught (in promise) TypeError: ws.send is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/omnia-network/ic-websocket-sdk-js#readme","github":"https://github.com/omnia-network/ic-websocket-sdk-js","docs":null,"changelog":null,"pypi":null,"npm":"ic-websocket-js","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}