0
# Core Web3 Instance
1

2
The main Web3 class serves as the entry point and umbrella for all Ethereum-related functionality. It extends Web3Context to provide a unified interface for blockchain interaction with provider management, module access, and configuration.
3

4
## Capabilities
5

6
### Web3 Constructor
7

8
Creates a new Web3 instance with optional provider or context configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Web3 instance
13
 * @param providerOrContext - Provider URL, provider instance, or context options
14
 */
15
constructor(
16
  providerOrContext?: 
17
    | string 
18
    | SupportedProviders<EthExecutionAPI> 
19
    | Web3ContextInitOptions<EthExecutionAPI, CustomRegisteredSubscription>
20
);
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import Web3 from 'web3';
27

28
// With HTTP provider URL
29
const web3 = new Web3('https://mainnet.infura.io/v3/YOUR-PROJECT-ID');
30

31
// With WebSocket provider
32
const web3 = new Web3('wss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID');
33

34
// With provider instance
35
import { HttpProvider } from 'web3-providers-http';
36
const provider = new HttpProvider('https://localhost:8545');
37
const web3 = new Web3(provider);
38

39
// With context options
40
const web3 = new Web3({
41
  provider: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
42
  config: {
43
    defaultBlock: 'latest',
44
    defaultGasPrice: '20000000000'
45
  }
46
});
47

48
// Default (uses mainnet provider)
49
const web3 = new Web3();
50
```
51

52
### Static Properties
53

54
Access to utility functions, version information, and module constructors.
55

56
```typescript { .api }
57
class Web3 {
58
  /** Package version string */
59
  static version: string;
60
  
61
  /** Utility functions for data conversion, validation, and hashing */
62
  static utils: typeof utils;
63
  
64
  /** Module constructors for manual instantiation */
65
  static modules: {
66
    Web3Eth: typeof Web3Eth;
67
    Iban: typeof Iban;
68
    Net: typeof Net;
69
    ENS: typeof ENS;
70
    Personal: typeof Personal;
71
  };
72
  
73
  /** EIP-6963 provider discovery functions */
74
  static requestEIP6963Providers: typeof requestEIP6963Providers;
75
  static onNewProviderDiscovered: typeof onNewProviderDiscovered;
76
}
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
// Access version
83
console.log(Web3.version); // "4.16.0"
84

85
// Use static utils
86
const weiValue = Web3.utils.toWei('1', 'ether');
87
const isValid = Web3.utils.isAddress('0x742C1382...');
88

89
// Manual module instantiation
90
const ethModule = new Web3.modules.Web3Eth(provider);
91
const ibanInstance = new Web3.modules.Iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS');
92
```
93

94
### Instance Properties
95

96
Access to Ethereum functionality and utilities through the instance.
97

98
```typescript { .api }
99
class Web3 {
100
  /** Ethereum interaction module with extended interface */
101
  eth: Web3EthInterface;
102
  
103
  /** Utility functions (same as static utils) */
104
  utils: typeof utils;
105
}
106
```
107

108
### Provider Management
109

110
Methods for managing the connection provider.
111

112
```typescript { .api }
113
/**
114
 * Set a new provider for this Web3 instance and all sub-modules
115
 * @param provider - New provider instance or URL
116
 * @returns Boolean indicating success
117
 */
118
setProvider(provider: string | SupportedProviders<EthExecutionAPI>): boolean;
119

120
/**
121
 * Get the current provider
122
 * @returns Current provider instance or undefined
123
 */
124
get currentProvider(): SupportedProviders<EthExecutionAPI> | undefined;
125

126
/**
127
 * Get the given provider (from browser environment)
128
 * @returns Given provider or undefined
129
 */
130
static get givenProvider(): SupportedProviders<EthExecutionAPI> | undefined;
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
const web3 = new Web3('https://mainnet.infura.io/v3/YOUR-PROJECT-ID');
137

138
// Change provider
139
web3.setProvider('wss://mainnet.infura.io/ws/v3/YOUR-PROJECT-ID');
140

141
// Check current provider
142
console.log(web3.currentProvider);
143

144
// Check for browser-injected provider
145
if (Web3.givenProvider) {
146
  const web3 = new Web3(Web3.givenProvider);
147
}
148
```
149

150
### Batch Requests
151

152
Create and execute multiple RPC calls in a single request.
153

154
```typescript { .api }
155
/**
156
 * BatchRequest constructor for creating batch RPC calls
157
 */
158
BatchRequest: typeof Web3BatchRequest;
159

160
class Web3BatchRequest {
161
  constructor();
162
  
163
  /** Add a request to the batch */
164
  add(request: JsonRpcOptionalRequest): void;
165
  
166
  /** Execute all requests in the batch */
167
  execute(): Promise<JsonRpcResponse[]>;
168
}
169
```
170

171
**Usage Examples:**
172

173
```typescript
174
const batch = new web3.BatchRequest();
175

176
// Add multiple requests
177
batch.add({
178
  method: 'eth_getBalance',
179
  params: ['0x742C1382...', 'latest']
180
});
181
batch.add({
182
  method: 'eth_getTransactionCount', 
183
  params: ['0x742C1382...', 'latest']
184
});
185

186
// Execute batch
187
const responses = await batch.execute();
188
```
189

190
### Context and Configuration
191

192
Access to underlying context and configuration options.
193

194
```typescript { .api }
195
/**
196
 * Get the context object containing configuration and provider
197
 */
198
getContextObject(): Web3ContextObject;
199

200
/**
201
 * Subscribe to context events
202
 */
203
subscribeToContextEvents(context: Web3Context): void;
204
```
205

206
## Types
207

208
```typescript { .api }
209
interface Web3ContextInitOptions<API = unknown, RegisteredSubs = unknown> {
210
  provider?: string | SupportedProviders<API>;
211
  config?: Partial<Web3Config>;
212
  registeredSubscriptions?: RegisteredSubs;
213
}
214

215
interface Web3ContextObject {
216
  provider?: SupportedProviders;
217
  config: Web3Config;
218
  requestManager: Web3RequestManager;
219
  subscriptionManager?: Web3SubscriptionManager;
220
}
221

222
type SupportedProviders<API = unknown> = 
223
  | EIP1193Provider<API>
224
  | Web3BaseProvider<API>
225
  | HttpProvider
226
  | WebSocketProvider;
227
```