0
# web3-eth-iban
1

2
Web3-eth-iban provides utilities for converting between Ethereum addresses and International Bank Account Number (IBAN) format addresses. It implements the ISO13616 standard for IBAN validation and conversion, enabling interoperability between blockchain and traditional banking systems.
3

4
## Package Information
5

6
- **Package Name**: web3-eth-iban
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web3-eth-iban`
10

11
## Core Imports
12

13
```typescript
14
import { Iban } from "web3-eth-iban";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Iban } = require("web3-eth-iban");
21
```
22

23
Default import (also available):
24

25
```typescript
26
import Iban from "web3-eth-iban";
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { Iban } from "web3-eth-iban";
33

34
// Create IBAN from Ethereum address
35
const iban = Iban.fromAddress("0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8");
36
console.log(iban.toString()); // "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"
37

38
// Convert IBAN back to Ethereum address
39
const address = iban.toAddress();
40
console.log(address); // "0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8"
41

42
// Validate IBAN
43
const isValid = Iban.isValid("XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS");
44
console.log(isValid); // true
45

46
// Create indirect IBAN
47
const indirectIban = Iban.createIndirect({
48
  institution: "XREG",
49
  identifier: "GAVOFYORK"
50
});
51
console.log(indirectIban.toString()); // "XE81ETHXREGGAVOFYORK"
52
```
53

54
## Architecture
55

56
Web3-eth-iban implements two types of IBAN formats:
57

58
- **Direct IBAN**: Full Ethereum address encoded as IBAN (34-35 characters) - convertible to/from Ethereum addresses
59
- **Indirect IBAN**: Institution-based IBAN format (20 characters) - used for routing and identification, not directly convertible to addresses
60

61
The library provides both static utility methods for one-off operations and instance methods for working with specific IBAN objects.
62

63
## Capabilities
64

65
### IBAN Creation
66

67
Create IBAN instances from various inputs including Ethereum addresses, BBAN strings, and institutional components.
68

69
```typescript { .api }
70
/**
71
 * Construct a direct or indirect IBAN that has conversion methods and validity checks
72
 * @param iban - a Direct or an Indirect IBAN string
73
 */
74
constructor(iban: string): Iban;
75

76
/**
77
 * Create IBAN from Ethereum address
78
 * @param address - an Ethereum address
79
 * @returns Iban instance
80
 */
81
static fromAddress(address: HexString): Iban;
82

83
/**
84
 * Create IBAN from Basic Bank Account Number
85
 * @param bban - the BBAN to convert to IBAN
86
 * @returns Iban instance
87
 */
88
static fromBban(bban: string): Iban;
89

90
/**
91
 * Create indirect IBAN from institution and identifier
92
 * @param options - object with institution and identifier
93
 * @returns Iban instance
94
 */
95
static createIndirect(options: IbanOptions): Iban;
96
```
97

98
### IBAN Validation
99

100
Validate IBAN format and checksums according to ISO13616 standard.
101

102
```typescript { .api }
103
/**
104
 * Check if a string is a valid IBAN
105
 * @param iban - string to validate
106
 * @returns true if valid IBAN
107
 */
108
static isValid(iban: string): boolean;
109

110
/**
111
 * Check if the early provided IBAN is correct
112
 * @returns true if valid IBAN
113
 */
114
isValid(): boolean;
115

116
/**
117
 * Check if IBAN is Direct (length 34 or 35)
118
 * @param iban - IBAN to check
119
 * @returns true if Direct IBAN
120
 */
121
static isDirect(iban: string): boolean;
122

123
/**
124
 * Check if this IBAN is Direct
125
 * @returns true if Direct IBAN
126
 */
127
isDirect(): boolean;
128

129
/**
130
 * Check if IBAN is Indirect (length 20)
131
 * @param iban - IBAN to check
132
 * @returns true if Indirect IBAN
133
 */
134
static isIndirect(iban: string): boolean;
135

136
/**
137
 * Check if this IBAN is Indirect
138
 * @returns true if Indirect IBAN
139
 */
140
isIndirect(): boolean;
141
```
142

143
### Address Conversion
144

145
Convert between Ethereum addresses and direct IBAN format.
146

147
```typescript { .api }
148
/**
149
 * Convert direct IBAN to Ethereum address
150
 * @param iban - a Direct IBAN address
151
 * @returns equivalent Ethereum address
152
 */
153
static toAddress(iban: string): HexString;
154

155
/**
156
 * Convert this direct IBAN to Ethereum address
157
 * @returns equivalent Ethereum address
158
 */
159
toAddress(): HexString;
160

161
/**
162
 * Convert Ethereum address to IBAN string
163
 * @param address - an Ethereum address
164
 * @returns equivalent IBAN string
165
 */
166
static toIban(address: HexString): string;
167
```
168

169
### IBAN Information Extraction
170

171
Extract components and metadata from IBAN strings.
172

173
```typescript { .api }
174
/**
175
 * Get client identifier from indirect IBAN
176
 * @returns client identifier or empty string for direct IBANs
177
 */
178
client(): string;
179

180
/**
181
 * Get IBAN checksum (positions 2-4)
182
 * @returns checksum string
183
 */
184
checksum(): string;
185

186
/**
187
 * Get institution identifier from indirect IBAN
188
 * @returns institution identifier or empty string for direct IBANs
189
 */
190
institution(): string;
191

192
/**
193
 * Get the IBAN string
194
 * @returns IBAN string
195
 */
196
toString(): string;
197
```
198

199
## Types
200

201
```typescript { .api }
202
/**
203
 * Configuration object for creating indirect IBANs
204
 */
205
interface IbanOptions {
206
  /** Institution identifier */
207
  institution: string;
208
  /** Client identifier */
209
  identifier: string;
210
}
211

212
/**
213
 * Hexadecimal string type (imported from web3-types package)
214
 */
215
type HexString = import('web3-types').HexString;
216
```
217

218
## Error Handling
219

220
The library throws the following errors:
221

222
- `Error("Invalid IBAN was provided")` - When constructor receives invalid IBAN format
223
- `InvalidAddressError(address)` - When provided address is not a valid Ethereum address  
224
- `Error("Iban is indirect and cannot be converted. Must be length of 34 or 35")` - When attempting to convert indirect IBAN to address
225

226
**Usage Examples:**
227

228
```typescript
229
import { Iban } from "web3-eth-iban";
230

231
// Handle invalid IBAN
232
try {
233
  const iban = new Iban("INVALID");
234
} catch (error) {
235
  console.log(error.message); // "Invalid IBAN was provided"
236
}
237

238
// Handle invalid address
239
try {
240
  const iban = Iban.fromAddress("0x123"); // Invalid address
241
} catch (error) {
242
  console.log(error.constructor.name); // "InvalidAddressError"
243
}
244

245
// Handle indirect IBAN conversion
246
try {
247
  const iban = new Iban("XE81ETHXREGGAVOFYORK"); // Indirect IBAN
248
  const address = iban.toAddress(); // Will throw
249
} catch (error) {
250
  console.log(error.message); // "Iban is indirect and cannot be converted..."
251
}
252
```