{"id":17409,"library":"xdc3-providers-http","title":"XDC3 HTTP Provider","description":"xdc3-providers-http is a core sub-package within the XDC3 ecosystem, providing the essential functionality to establish RPC connections over HTTP(S) for interacting with the XinFin blockchain. As of version 1.3.13420, it is a stable component, primarily used in Node.js environments (requiring Node.js >= 8.0.0). It enables developers to configure various HTTP request parameters such as `keepAlive`, `timeout`, and custom `headers`, along with advanced `agent` options, for reliable and efficient communication with XDC network nodes. The library ships with TypeScript typings, facilitating its integration into modern TypeScript projects. While its exact release cadence isn't explicitly stated, the versioning suggests continuous maintenance and minor enhancements within the 1.x series, aligning with the broader XDC3 library development. Its key differentiator is its tight integration and optimization for the XinFin blockchain, offering a robust and configurable HTTP interface.","status":"active","version":"1.3.13420","language":"javascript","source_language":"en","source_url":"https://github.com/XinFinOrg/XDC3/tree/master/packages/web3-providers-http","tags":["javascript","typescript"],"install":[{"cmd":"npm install xdc3-providers-http","lang":"bash","label":"npm"},{"cmd":"yarn add xdc3-providers-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add xdc3-providers-http","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `Web3HttpProvider` class is commonly exported as a default export in ESM, aligning with its typical CommonJS usage where `require('xdc3-providers-http')` directly yields the class constructor.","wrong":"import { Web3HttpProvider } from 'xdc3-providers-http';","symbol":"Web3HttpProvider","correct":"import Web3HttpProvider from 'xdc3-providers-http';"},{"note":"In CommonJS, the package typically exports the `Web3HttpProvider` class directly as its `module.exports`, meaning no destructuring is required.","wrong":"const { Web3HttpProvider } = require('xdc3-providers-http');","symbol":"Web3HttpProvider (CJS)","correct":"const Web3HttpProvider = require('xdc3-providers-http');"},{"note":"For TypeScript projects, import the `HttpProviderOptions` interface using a type-only import for specifying configuration objects without incurring runtime overhead.","symbol":"HttpProviderOptions (type)","correct":"import type { HttpProviderOptions } from 'xdc3-providers-http';"}],"quickstart":{"code":"import Web3HttpProvider from 'xdc3-providers-http';\nimport XDC3 from 'xdc3'; // Ensure 'xdc3' package is also installed\n\n// --- Configuration ---\n// It's good practice to get URLs from environment variables\nconst xdcNodeUrl = process.env.XDC_NODE_URL ?? 'http://localhost:8545';\n\n// --- Provider Options (HttpProviderOptions type) ---\nconst providerOptions = {\n    keepAlive: true,\n    timeout: 30000, // RPC call timeout in milliseconds\n    headers: [\n        { name: 'X-App-Name', value: 'MyXDC3App' },\n        { name: 'Authorization', value: `Bearer ${process.env.XDC_AUTH_TOKEN ?? ''}` } // Example for authenticated nodes\n    ],\n    // For custom HTTP agent configuration in Node.js, e.g., to increase maxSockets:\n    // agent: { http: new (require('http').Agent)({ maxSockets: 10 }), https: new (require('https').Agent)({ maxSockets: 10 }) },\n};\n\n// --- Instantiate the Provider ---\nconst provider = new Web3HttpProvider(xdcNodeUrl, providerOptions);\n\n// --- Instantiate XDC3 with the provider ---\nconst xdc3 = new XDC3(provider);\n\n// --- Example Usage: Get the current block number and chain ID ---\nasync function getCurrentBlockchainInfo() {\n    try {\n        const blockNumber = await xdc3.eth.getBlockNumber();\n        const chainId = await xdc3.eth.getChainId();\n        console.log(`Successfully connected to XDC node at ${xdcNodeUrl}`);\n        console.log(`Current block number: ${blockNumber}`);\n        console.log(`Connected to Chain ID: ${chainId}`);\n\n    } catch (error) {\n        console.error('Failed to connect or retrieve data from XDC node:', error);\n        if (error instanceof Error) {\n             console.error(`Error details: ${error.message}`);\n        }\n    }\n}\n\ngetCurrentBlockchainInfo();\n\n// To run this example:\n// 1. Install packages: npm install xdc3 xdc3-providers-http\n// 2. Ensure an XDC node is accessible at the specified URL (e.g., http://localhost:8545).\n// 3. If using TypeScript, you can run directly with 'npx ts-node your-script.ts' (install ts-node).\n","lang":"typescript","description":"This quickstart demonstrates how to instantiate and configure `Web3HttpProvider` with custom options (like timeout and headers) and integrate it with the `XDC3` library to fetch the current block number and chain ID from an XDC node, showcasing basic connectivity."},"warnings":[{"fix":"Always install `xdc3-providers-http` if your project uses the `xdc3` library. Avoid interchanging it with `web3-providers-http` from the mainstream Web3.js library to prevent unexpected issues.","message":"This package is specifically designed for `xdc3`, the XinFin fork of Web3.js. While its API is similar to `web3-providers-http`, it's critical to use `xdc3-providers-http` when building applications with the `xdc3` core library to ensure full compatibility with XinFin-specific network behaviors and features.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects or when upgrading, prefer using ESM `import` statements. For existing CommonJS projects, monitor release notes for explicit guidance on ESM-only transitions and consider migration strategies or using dynamic `import()` where appropriate.","message":"Future major versions of `xdc3-providers-http`, in line with modern JavaScript ecosystem trends, may transition to ESM-only module distribution. This change would break existing CommonJS `require()` statements if the package does not provide dual CommonJS/ESM compatibility.","severity":"breaking","affected_versions":"future major versions (e.g., >=2.0.0)"},{"fix":"Ensure your development and production environments run on a supported Node.js LTS version. Tools like `nvm` (Node Version Manager) can facilitate easy switching and management of Node.js versions.","message":"The `engines` field in `package.json` specifies Node.js `>=8.0.0`. While this package might function on older Node.js versions, it is strongly recommended to use a currently supported Node.js LTS version (e.g., Node.js 16 or 18) to benefit from security patches, performance enhancements, and broader compatibility with other modern JavaScript tooling.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ESM, ensure you use `import Web3HttpProvider from 'xdc3-providers-http';`. For CommonJS, use `const Web3HttpProvider = require('xdc3-providers-http');`. Do not use `{ Web3HttpProvider }` with default exports.","cause":"This error typically occurs due to an incorrect import statement, either attempting to destructure a default CommonJS export or using a named import when the module provides a default export in ESM.","error":"TypeError: Web3HttpProvider is not a constructor"},{"fix":"Verify that your XDC node (or a public XDC RPC endpoint) is running and accessible from the machine where your application is executing. Double-check the configured `xdcNodeUrl` for typos and ensure no firewall rules are blocking the connection. Network latency or an overloaded node can also contribute to this.","cause":"The application failed to establish a connection with the specified XDC RPC node. This can be due to the node not running, being inaccessible, or listening on a different address/port.","error":"Error: CONNECTION ERROR: Couldn't connect to node http://localhost:8545."},{"fix":"If this package or its dependencies become ESM-only in a future update, you must convert your consuming file to an ESM module (e.g., by changing its extension to `.mjs` or by setting `\"type\": \"module\"` in your `package.json` and using `import` statements). Alternatively, consider using dynamic `import()` within your CommonJS module.","cause":"Attempting to `require()` an ESM-only package within a CommonJS module context. This happens if the package or one of its dependencies has fully transitioned to ESM.","error":"ERR_REQUIRE_ESM"}],"ecosystem":"npm","meta_description":null}