0
# Web3 HTTP Provider
1

2
Web3 HTTP Provider is a TypeScript implementation of an HTTP-based JSON-RPC provider for the Web3.js ecosystem. It enables communication with Ethereum nodes over HTTP/HTTPS protocols, providing a reliable transport layer for blockchain interactions with comprehensive error handling and type safety.
3

4
## Package Information
5

6
- **Package Name**: web3-providers-http
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web3` (web3-providers-http is included as part of the Web3.js library)
10

11
## Core Imports
12

13
**Recommended - Use with Web3.js library:**
14

15
```typescript
16
import { Web3 } from "web3";
17

18
// HttpProvider is used automatically when you provide an HTTP URL
19
const web3 = new Web3("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
20
```
21

22
**Direct import (advanced usage):**
23

24
```typescript
25
import HttpProvider from "web3-providers-http";
26
```
27

28
Named import:
29

30
```typescript
31
import { HttpProvider } from "web3-providers-http";
32
```
33

34
With options interface:
35

36
```typescript
37
import HttpProvider, { HttpProviderOptions } from "web3-providers-http";
38
```
39

40
For CommonJS:
41

42
```javascript
43
const HttpProvider = require("web3-providers-http");
44
// or
45
const { HttpProvider } = require("web3-providers-http");
46
```
47

48
## Basic Usage
49

50
**Recommended - Using with Web3.js:**
51

52
```typescript
53
import { Web3 } from "web3";
54

55
// HttpProvider is used automatically for HTTP URLs
56
const web3 = new Web3("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
57

58
// Get account balance using Web3 convenience methods
59
const balance = await web3.eth.getBalance("0x742d35cc6634c0532925a3b8d404dff86c521890");
60
console.log(balance); // Account balance
61
```
62

63
**Direct HttpProvider usage:**
64

65
```typescript
66
import HttpProvider from "web3-providers-http";
67

68
// Create provider with basic URL
69
const provider = new HttpProvider("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
70

71
// Create provider with custom options
72
const providerWithOptions = new HttpProvider(
73
  "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
74
  {
75
    providerOptions: {
76
      headers: {
77
        "Authorization": "Bearer your-token"
78
      },
79
      timeout: 10000
80
    }
81
  }
82
);
83

84
// Make JSON-RPC request
85
const response = await provider.request({
86
  jsonrpc: "2.0",
87
  id: 1,
88
  method: "eth_getBalance",
89
  params: ["0x742d35cc6634c0532925a3b8d404dff86c521890", "latest"]
90
});
91

92
console.log(response.result); // Account balance
93
```
94

95
## Architecture
96

97
The Web3 HTTP Provider is built around:
98

99
- **HttpProvider Class**: Main provider implementation extending Web3BaseProvider
100
- **Generic Type System**: Full TypeScript support with Web3APISpec generics for type-safe method calls
101
- **URL Validation**: Client URL validation ensuring HTTP/HTTPS protocols only
102
- **Fetch Integration**: Uses cross-fetch for Node.js/browser compatibility
103
- **Error Handling**: Comprehensive error handling with specific Web3 error types
104
- **Request Configuration**: Supports all standard Fetch API options through HttpProviderOptions
105

106
## Capabilities
107

108
### HTTP Provider Class
109

110
Main provider class for HTTP-based JSON-RPC communication with Ethereum nodes.
111

112
```typescript { .api }
113
/**
114
 * HTTP provider implementation for Web3.js JSON-RPC communication
115
 * @template API - Web3 API specification type, defaults to EthExecutionAPI
116
 */
117
export default class HttpProvider<API extends Web3APISpec = EthExecutionAPI> extends Web3BaseProvider<API> {
118
  /**
119
   * Creates a new HTTP provider instance
120
   * @param clientUrl - HTTP or HTTPS URL of the JSON-RPC endpoint
121
   * @param httpProviderOptions - Optional configuration for HTTP requests
122
   * @throws InvalidClientError when clientUrl is invalid
123
   */
124
  constructor(clientUrl: string, httpProviderOptions?: HttpProviderOptions);
125
}
126
```
127

128
### JSON-RPC Request Method
129

130
Performs HTTP JSON-RPC requests with full type safety and error handling.
131

132
```typescript { .api }
133
/**
134
 * Makes an HTTP JSON-RPC request to the configured endpoint
135
 * @template Method - The JSON-RPC method being called
136
 * @template ResultType - Expected return type for the method
137
 * @param payload - JSON-RPC payload containing method and parameters
138
 * @param requestOptions - Optional Fetch API RequestInit options for this specific request
139
 * @returns Promise resolving to JSON-RPC response with typed result
140
 * @throws ResponseError when HTTP response indicates an error
141
 */
142
async request<
143
  Method extends Web3APIMethod<API>,
144
  ResultType = Web3APIReturnType<API, Method>
145
>(
146
  payload: Web3APIPayload<API, Method>,
147
  requestOptions?: RequestInit
148
): Promise<JsonRpcResponseWithResult<ResultType>>;
149
```
150

151
### Subscription Support Check
152

153
Indicates whether the provider supports real-time subscriptions.
154

155
```typescript { .api }
156
/**
157
 * Indicates subscription support capability
158
 * @returns false - HTTP providers do not support subscriptions
159
 */
160
supportsSubscriptions(): boolean;
161
```
162

163
### Provider Status (Not Implemented)
164

165
Provider status checking method - throws MethodNotImplementedError.
166

167
```typescript { .api }
168
/**
169
 * Gets the current provider status
170
 * @throws MethodNotImplementedError - Not implemented for HTTP provider
171
 */
172
getStatus(): Web3ProviderStatus;
173
```
174

175
### Event Handling Methods (Not Implemented)
176

177
Event handling methods required by Web3BaseProvider interface - all throw MethodNotImplementedError.
178

179
```typescript { .api }
180
/**
181
 * Registers an event listener
182
 * @throws MethodNotImplementedError - Event handling not supported over HTTP
183
 */
184
on(): void;
185

186
/**
187
 * Removes an event listener
188
 * @throws MethodNotImplementedError - Event handling not supported over HTTP
189
 */
190
removeListener(): void;
191

192
/**
193
 * Registers a one-time event listener
194
 * @throws MethodNotImplementedError - Event handling not supported over HTTP
195
 */
196
once(): void;
197

198
/**
199
 * Removes all event listeners
200
 * @throws MethodNotImplementedError - Event handling not supported over HTTP
201
 */
202
removeAllListeners(): void;
203
```
204

205
### Connection Management Methods (Not Implemented)
206

207
Connection lifecycle methods required by Web3BaseProvider interface - all throw MethodNotImplementedError.
208

209
```typescript { .api }
210
/**
211
 * Establishes provider connection
212
 * @throws MethodNotImplementedError - Connection management not applicable for HTTP
213
 */
214
connect(): void;
215

216
/**
217
 * Closes provider connection
218
 * @throws MethodNotImplementedError - Connection management not applicable for HTTP
219
 */
220
disconnect(): void;
221

222
/**
223
 * Resets provider state
224
 * @throws MethodNotImplementedError - State management not applicable for HTTP
225
 */
226
reset(): void;
227

228
/**
229
 * Reconnects the provider (HttpProvider-specific method)
230
 * @throws MethodNotImplementedError - Connection management not applicable for HTTP
231
 */
232
reconnect(): void;
233
```
234

235
### Inherited Methods from Web3BaseProvider
236

237
These methods are inherited from the Web3BaseProvider base class and provide backward compatibility and additional functionality.
238

239
```typescript { .api }
240
/**
241
 * Sends a JSON-RPC request (deprecated, use request() instead)
242
 * @deprecated Use request() method instead
243
 * @param payload - JSON-RPC payload
244
 * @param callback - Optional callback function
245
 * @returns Promise resolving to JSON-RPC response
246
 */
247
send<Method extends Web3APIMethod<API>, ResultType = Web3APIReturnType<API, Method>>(
248
  payload: Web3APIPayload<API, Method>,
249
  callback?: (error: Error | null, result?: JsonRpcResponseWithResult<ResultType>) => void
250
): Promise<JsonRpcResponseWithResult<ResultType>>;
251

252
/**
253
 * Sends a JSON-RPC request asynchronously (deprecated, use request() instead)
254
 * @deprecated Use request() method instead
255
 * @param payload - JSON-RPC payload
256
 * @param callback - Callback function for handling response
257
 */
258
sendAsync<Method extends Web3APIMethod<API>, ResultType = Web3APIReturnType<API, Method>>(
259
  payload: Web3APIPayload<API, Method>,
260
  callback: (error: Error | null, result?: JsonRpcResponseWithResult<ResultType>) => void
261
): void;
262

263
/**
264
 * Returns an EIP-1193 compatible provider interface
265
 * @returns EIP1193Provider instance wrapping this provider
266
 */
267
asEIP1193Provider(): EIP1193Provider<API>;
268
```
269

270
## Types
271

272
### Core Web3 Types
273

274
These types are imported from the web3-types package and used throughout the provider:
275

276
```typescript { .api }
277
/**
278
 * Base Web3 API specification interface
279
 */
280
interface Web3APISpec {
281
  [method: string]: {
282
    Parameters: any[];
283
    ReturnType: any;
284
  };
285
}
286

287
/**
288
 * Default Ethereum execution API specification
289
 */
290
interface EthExecutionAPI extends Web3APISpec {
291
  eth_getBalance: {
292
    Parameters: [string, string];
293
    ReturnType: string;
294
  };
295
  eth_blockNumber: {
296
    Parameters: [];
297
    ReturnType: string;
298
  };
299
  // ... additional Ethereum JSON-RPC methods
300
}
301

302
/**
303
 * JSON-RPC method names from API specification
304
 */
305
type Web3APIMethod<API extends Web3APISpec> = keyof API;
306

307
/**
308
 * JSON-RPC payload for specific method
309
 */
310
interface Web3APIPayload<API extends Web3APISpec, Method extends Web3APIMethod<API>> {
311
  jsonrpc: "2.0";
312
  id: number | string;
313
  method: Method;
314
  params: API[Method]["Parameters"];
315
}
316

317
/**
318
 * Return type for specific API method
319
 */
320
type Web3APIReturnType<API extends Web3APISpec, Method extends Web3APIMethod<API>> = 
321
  API[Method]["ReturnType"];
322

323
/**
324
 * JSON-RPC response with typed result
325
 */
326
interface JsonRpcResponseWithResult<T> {
327
  jsonrpc: "2.0";
328
  id: number | string;
329
  result: T;
330
}
331

332
/**
333
 * Base provider class from web3-types
334
 */
335
abstract class Web3BaseProvider<API extends Web3APISpec> {
336
  abstract request<Method extends Web3APIMethod<API>>(
337
    payload: Web3APIPayload<API, Method>
338
  ): Promise<JsonRpcResponseWithResult<Web3APIReturnType<API, Method>>>;
339
  abstract supportsSubscriptions(): boolean;
340
  abstract getStatus(): Web3ProviderStatus;
341
  // ... additional provider interface methods
342
}
343

344
/**
345
 * Provider status enumeration
346
 */
347
enum Web3ProviderStatus {
348
  CONNECTING = "connecting",
349
  CONNECTED = "connected",
350
  DISCONNECTED = "disconnected",
351
  ERROR = "error"
352
}
353

354
/**
355
 * EIP-1193 compatible provider interface
356
 */
357
interface EIP1193Provider<API extends Web3APISpec> {
358
  request<Method extends Web3APIMethod<API>>(
359
    args: { method: Method; params?: API[Method]["Parameters"] }
360
  ): Promise<Web3APIReturnType<API, Method>>;
361
  on(event: string, listener: (...args: any[]) => void): void;
362
  removeListener(event: string, listener: (...args: any[]) => void): void;
363
}
364
```
365

366
### Standard Web API Types
367

368
```typescript { .api }
369
/**
370
 * Standard Fetch API RequestInit interface for HTTP configuration
371
 */
372
interface RequestInit {
373
  method?: string;
374
  headers?: HeadersInit;
375
  body?: BodyInit | null;
376
  referrer?: string;
377
  referrerPolicy?: ReferrerPolicy;
378
  mode?: RequestMode;
379
  credentials?: RequestCredentials;
380
  cache?: RequestCache;
381
  redirect?: RequestRedirect;
382
  integrity?: string;
383
  keepalive?: boolean;
384
  signal?: AbortSignal | null;
385
  window?: any;
386
}
387
```
388

389
### Error Types
390

391
Error types from the web3-errors package:
392

393
```typescript { .api }
394
/**
395
 * Error thrown when invalid client URL is provided
396
 */
397
class InvalidClientError extends Error {
398
  constructor(clientUrl: string);
399
}
400

401
/**
402
 * Error thrown when calling unimplemented provider methods
403
 */
404
class MethodNotImplementedError extends Error {
405
  constructor();
406
}
407

408
/**
409
 * Error thrown when HTTP response indicates failure
410
 */
411
class ResponseError extends Error {
412
  constructor(response: any);
413
}
414
```
415

416
## Configuration
417

418
### HTTP Provider Options
419

420
Configuration interface for customizing HTTP requests and provider behavior.
421

422
```typescript { .api }
423
/**
424
 * Configuration options for HTTP provider
425
 */
426
interface HttpProviderOptions {
427
  /** Standard Fetch API RequestInit options for HTTP requests */
428
  providerOptions: RequestInit;
429
}
430
```
431

432
The `providerOptions` field accepts all standard Fetch API options:
433

434
- `headers`: Custom HTTP headers
435
- `timeout`: Request timeout (browser-dependent)
436
- `credentials`: Cookie/authentication credential handling
437
- `cache`: Caching behavior
438
- `redirect`: Redirect handling
439
- `integrity`: Subresource integrity value
440
- `keepalive`: Keep connection alive
441
- `referrer`: Referrer information
442
- `referrerPolicy`: Referrer policy
443
- `signal`: AbortController signal for request cancellation
444

445
## Error Handling
446

447
The provider throws specific error types for different failure scenarios:
448

449
### InvalidClientError
450

451
Thrown when an invalid client URL is provided to the constructor.
452

453
```typescript
454
try {
455
  const provider = new HttpProvider("invalid-url");
456
} catch (error) {
457
  // error is InvalidClientError
458
  console.error(`Invalid client URL: ${error.message}`);
459
}
460
```
461

462
### MethodNotImplementedError
463

464
Thrown when calling methods not implemented by the HTTP provider (event handling, connection management).
465

466
```typescript
467
try {
468
  provider.getStatus();
469
} catch (error) {
470
  // error is MethodNotImplementedError
471
  console.error("Method not implemented for HTTP provider");
472
}
473
```
474

475
### ResponseError
476

477
Thrown when HTTP requests return non-ok status codes.
478

479
```typescript
480
try {
481
  const response = await provider.request(payload);
482
} catch (error) {
483
  // error is ResponseError containing the error response
484
  console.error("HTTP request failed:", error.message);
485
}
486
```
487

488
## URL Validation
489

490
The provider validates client URLs using the following rules:
491

492
- Must be a string
493
- Must start with `http://` or `https://` (case-insensitive)
494
- Invalid URLs will throw `InvalidClientError` during construction
495

496
Valid URL examples:
497
- `https://mainnet.infura.io/v3/PROJECT_ID`
498
- `http://localhost:8545`
499
- `https://rpc.ankr.com/eth`
500

501
## HTTP Request Details
502

503
All JSON-RPC requests are made with:
504

505
- **Method**: POST
506
- **Content-Type**: application/json
507
- **Body**: JSON-stringified RPC payload
508
- **Custom Options**: Merged from constructor options and per-request options
509
- **Response Parsing**: Automatic JSON parsing with error checking
510

511
## Usage Examples
512

513
### Basic Ethereum Balance Query
514

515
**Using Web3.js (recommended):**
516

517
```typescript
518
import { Web3 } from "web3";
519

520
const web3 = new Web3("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
521
const balance = await web3.eth.getBalance("0x742d35cc6634c0532925a3b8d404dff86c521890");
522
console.log("Balance:", balance);
523
```
524

525
**Direct HttpProvider usage:**
526

527
```typescript
528
import HttpProvider from "web3-providers-http";
529

530
const provider = new HttpProvider("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
531

532
const balance = await provider.request({
533
  jsonrpc: "2.0",
534
  id: 1,
535
  method: "eth_getBalance",
536
  params: ["0x742d35cc6634c0532925a3b8d404dff86c521890", "latest"]
537
});
538

539
console.log("Balance:", balance.result);
540
```
541

542
### Custom Headers and Timeout
543

544
```typescript
545
import HttpProvider, { HttpProviderOptions } from "web3-providers-http";
546

547
const options: HttpProviderOptions = {
548
  providerOptions: {
549
    headers: {
550
      "Authorization": "Bearer your-api-token",
551
      "User-Agent": "MyApp/1.0"
552
    },
553
    // Note: timeout handling varies by environment
554
  }
555
};
556

557
const provider = new HttpProvider("https://api.example.com/rpc", options);
558
```
559

560
### Type-Safe Method Calls with Custom API
561

562
```typescript
563
import HttpProvider from "web3-providers-http";
564
import { Web3APISpec } from "web3-types";
565

566
// Define custom API specification
567
interface CustomAPI extends Web3APISpec {
568
  custom_method: {
569
    Parameters: [string, number];
570
    ReturnType: { result: string; status: boolean };
571
  };
572
}
573

574
const provider = new HttpProvider<CustomAPI>("https://custom-node.example.com");
575

576
// Type-safe request with custom API
577
const response = await provider.request({
578
  jsonrpc: "2.0",
579
  id: 1,
580
  method: "custom_method",
581
  params: ["parameter1", 42]
582
});
583

584
// response.result is typed as { result: string; status: boolean }
585
console.log(response.result.status);
586
```
587

588
### Request Cancellation
589

590
```typescript
591
import HttpProvider from "web3-providers-http";
592

593
const provider = new HttpProvider("https://mainnet.infura.io/v3/YOUR_PROJECT_ID");
594
const controller = new AbortController();
595

596
// Cancel request after 5 seconds
597
setTimeout(() => controller.abort(), 5000);
598

599
try {
600
  const response = await provider.request(
601
    {
602
      jsonrpc: "2.0",
603
      id: 1,
604
      method: "eth_getBalance",
605
      params: ["0x742d35cc6634c0532925a3b8d404dff86c521890", "latest"]
606
    },
607
    { signal: controller.signal }
608
  );
609
} catch (error) {
610
  if (error.name === 'AbortError') {
611
    console.log("Request was cancelled");
612
  }
613
}
614
```