0
# Wallet Operations
1

2
Wallet interface management and payment integration with support for multiple fiat-to-crypto providers and WalletConnect.
3

4
## Capabilities
5

6
### Wallet Interface
7

8
Open and navigate the Torus wallet interface in a popup window.
9

10
```typescript { .api }
11
/**
12
 * Open the Torus wallet interface in a popup window
13
 * @param path - Wallet section to display
14
 * @param params - Optional query parameters for the wallet
15
 */
16
showWallet(path: WALLET_PATH, params?: Record<string, string>): void;
17

18
type WALLET_PATH = 
19
  | "transfer"  // Send/receive tokens
20
  | "topup"     // Buy cryptocurrency  
21
  | "home"      // Main wallet dashboard
22
  | "settings"  // Wallet settings
23
  | "history"   // Transaction history
24
  | "discover"; // DApp browser/discovery
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
// Open main wallet dashboard
31
torus.showWallet("home");
32

33
// Open transfer page
34
torus.showWallet("transfer");
35

36
// Open topup page with specific token
37
torus.showWallet("topup", { 
38
  selectedCryptoCurrency: "ETH",
39
  selectedCurrency: "USD"
40
});
41

42
// Open transaction history
43
torus.showWallet("history");
44

45
// Open settings with specific tab
46
torus.showWallet("settings", { 
47
  tab: "privacy" 
48
});
49
```
50

51
### Fiat-to-Crypto Payments
52

53
Initiate cryptocurrency purchases through integrated payment providers.
54

55
```typescript { .api }
56
/**
57
 * Initiate fiat-to-crypto purchase through payment providers
58
 * @param provider - Payment provider to use
59
 * @param params - Payment configuration parameters
60
 * @returns Promise resolving to success status
61
 */
62
initiateTopup(provider: PAYMENT_PROVIDER_TYPE, params: PaymentParams): Promise<boolean>;
63

64
type PAYMENT_PROVIDER_TYPE = 
65
  | "moonpay"     // MoonPay
66
  | "rampnetwork" // Ramp Network
67
  | "mercuryo"    // Mercuryo  
68
  | "transak"     // Transak
69
  | "banxa";      // Banxa
70

71
interface PaymentParams {
72
  /** Recipient wallet address */
73
  selectedAddress?: string;
74
  /** Fiat currency for payment */
75
  selectedCurrency?: string;
76
  /** Amount in fiat currency */
77
  fiatValue?: number;
78
  /** Cryptocurrency to purchase */
79
  selectedCryptoCurrency?: string;
80
  /** Blockchain network for the purchase */
81
  chainNetwork?: SUPPORTED_PAYMENT_NETWORK_TYPE;
82
}
83

84
type SUPPORTED_PAYMENT_NETWORK_TYPE =
85
  | "mainnet"           // Ethereum
86
  | "matic"             // Polygon
87
  | "bsc_mainnet"       // Binance Smart Chain
88
  | "avalanche_mainnet" // Avalanche
89
  | "xdai"              // Gnosis Chain
90
  | "arbitrum_mainnet"  // Arbitrum
91
  | "optimism_mainnet"; // Optimism
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
// Basic topup with MoonPay
98
const success = await torus.initiateTopup("moonpay", {
99
  selectedAddress: "0x742d35Cc6765C788200b9aa5FdCFD9A3ebFCF2d7",
100
  selectedCurrency: "USD",
101
  fiatValue: 100,
102
  selectedCryptoCurrency: "ETH",
103
  chainNetwork: "mainnet"
104
});
105

106
if (success) {
107
  console.log("Payment process initiated");
108
}
109

110
// Buy MATIC on Polygon
111
await torus.initiateTopup("transak", {
112
  selectedCurrency: "EUR",
113
  fiatValue: 50,
114
  selectedCryptoCurrency: "MATIC", 
115
  chainNetwork: "matic"
116
});
117

118
// Buy BNB on BSC
119
await torus.initiateTopup("banxa", {
120
  selectedCurrency: "GBP",
121
  fiatValue: 200,
122
  selectedCryptoCurrency: "BNB",
123
  chainNetwork: "bsc_mainnet"
124
});
125
```
126

127
### WalletConnect Integration
128

129
Display WalletConnect QR code scanner for connecting to dApps.
130

131
```typescript { .api }
132
/**
133
 * Show WalletConnect QR code scanner interface
134
 * Requires useWalletConnect to be enabled and user to be logged in
135
 * @returns Promise resolving to success status
136
 */
137
showWalletConnectScanner(): Promise<boolean>;
138
```
139

140
**Usage Example:**
141

142
```typescript
143
// Initialize with WalletConnect support
144
await torus.init({
145
  useWalletConnect: true,
146
  // ... other config
147
});
148

149
// After user login, show WalletConnect scanner
150
if (torus.isLoggedIn) {
151
  try {
152
    const success = await torus.showWalletConnectScanner();
153
    if (success) {
154
      console.log("WalletConnect scanner opened");
155
    }
156
  } catch (error) {
157
    console.error("Failed to open WalletConnect scanner:", error);
158
  }
159
}
160
```
161

162
### Payment Provider Configuration
163

164
Access and validate available payment providers.
165

166
```typescript { .api }
167
/** Available payment providers with configurations */
168
readonly paymentProviders: Record<PAYMENT_PROVIDER_TYPE, IPaymentProvider>;
169

170
interface IPaymentProvider {
171
  /** Provider description line 1 */
172
  line1: string;
173
  /** Provider description line 2 */
174
  line2: string;
175
  /** Provider description line 3 */
176
  line3: string;
177
  /** Support page URL */
178
  supportPage: string;
179
  /** Minimum order value */
180
  minOrderValue: number;
181
  /** Maximum order value */
182
  maxOrderValue: number;
183
  /** Supported fiat currencies */
184
  validCurrencies: string[];
185
  /** Supported cryptocurrencies by chain */
186
  validCryptoCurrenciesByChain: Partial<Record<string, { value: string; display: string }[]>>;
187
  /** Whether fees are included in the price */
188
  includeFees: boolean;
189
  /** Whether maximum limits are enforced */
190
  enforceMax: boolean;
191
  /** Whether selling is supported */
192
  sell?: boolean;
193
}
194
```
195

196
**Usage Example:**
197

198
```typescript
199
// Check available payment providers
200
const providers = torus.paymentProviders;
201

202
Object.entries(providers).forEach(([key, provider]) => {
203
  console.log(`${key}:`, {
204
    description: `${provider.line1} - ${provider.line2}`,
205
    limits: `${provider.minOrderValue} - ${provider.maxOrderValue}`,
206
    currencies: provider.validCurrencies,
207
    supportsSelling: provider.sell
208
  });
209
});
210

211
// Validate provider supports specific currency and amount
212
function canUseProvider(providerType: PAYMENT_PROVIDER_TYPE, currency: string, amount: number): boolean {
213
  const provider = torus.paymentProviders[providerType];
214
  return provider.validCurrencies.includes(currency) &&
215
         amount >= provider.minOrderValue &&
216
         amount <= provider.maxOrderValue;
217
}
218

219
if (canUseProvider("moonpay", "USD", 100)) {
220
  await torus.initiateTopup("moonpay", {
221
    selectedCurrency: "USD",
222
    fiatValue: 100
223
  });
224
}
225
```
226

227
### Wallet State and Utilities
228

229
Check wallet state and configure wallet-related settings.
230

231
```typescript { .api }
232
/** Whether the wallet widget button is currently visible */
233
readonly torusWidgetVisibility: boolean;
234

235
/** Whether the iframe is currently in fullscreen mode */
236
readonly isIframeFullScreen: boolean;
237
```
238

239
**Usage Example:**
240

241
```typescript
242
// Check wallet state
243
console.log("Wallet state:", {
244
  widgetVisible: torus.torusWidgetVisibility,
245
  fullscreen: torus.isIframeFullScreen,
246
  loggedIn: torus.isLoggedIn
247
});
248

249
// Show wallet conditionally
250
if (torus.isLoggedIn && !torus.torusWidgetVisibility) {
251
  torus.showTorusButton();
252
}
253
```
254

255
### Advanced Payment Integration
256

257
For applications requiring custom payment flows or additional validation.
258

259
```typescript
260
// Custom payment validation
261
async function initiateCustomTopup(amount: number, currency: string, crypto: string) {
262
  // Validate user is logged in
263
  if (!torus.isLoggedIn) {
264
    throw new Error("User must be logged in to purchase crypto");
265
  }
266
  
267
  // Get user's current address
268
  const address = torus.provider.selectedAddress;
269
  if (!address) {
270
    throw new Error("No active wallet address");
271
  }
272
  
273
  // Find suitable payment provider
274
  const suitableProvider = findBestProvider(amount, currency, crypto);
275
  
276
  // Initiate purchase
277
  try {
278
    const success = await torus.initiateTopup(suitableProvider, {
279
      selectedAddress: address,
280
      selectedCurrency: currency,
281
      fiatValue: amount,
282
      selectedCryptoCurrency: crypto,
283
      chainNetwork: getCurrentNetwork()
284
    });
285
    
286
    if (success) {
287
      // Track purchase initiation
288
      analytics.track("crypto_purchase_initiated", {
289
        provider: suitableProvider,
290
        amount,
291
        currency,
292
        crypto
293
      });
294
    }
295
    
296
    return success;
297
  } catch (error) {
298
    console.error("Purchase failed:", error);
299
    throw error;
300
  }
301
}
302

303
function findBestProvider(amount: number, currency: string, crypto: string): PAYMENT_PROVIDER_TYPE {
304
  const providers = torus.paymentProviders;
305
  
306
  // Find providers that support the currency and amount
307
  const suitable = Object.entries(providers).filter(([key, provider]) => 
308
    provider.validCurrencies.includes(currency) &&
309
    amount >= provider.minOrderValue &&
310
    amount <= provider.maxOrderValue
311
  );
312
  
313
  if (suitable.length === 0) {
314
    throw new Error(`No provider supports ${currency} for amount ${amount}`);
315
  }
316
  
317
  // Return the first suitable provider (or implement custom logic)
318
  return suitable[0][0] as PAYMENT_PROVIDER_TYPE;
319
}
320

321
function getCurrentNetwork(): SUPPORTED_PAYMENT_NETWORK_TYPE {
322
  const chainId = torus.provider.chainId;
323
  
324
  switch (chainId) {
325
    case "0x1": return "mainnet";
326
    case "0x89": return "matic";
327
    case "0x38": return "bsc_mainnet";
328
    case "0xa86a": return "avalanche_mainnet";
329
    case "0x64": return "xdai";
330
    case "0xa4b1": return "arbitrum_mainnet";
331
    case "0xa": return "optimism_mainnet";
332
    default: return "mainnet";
333
  }
334
}
335
```
336

337
### Constants and Configuration
338

339
```typescript { .api }
340
const PAYMENT_PROVIDER = {
341
  MOONPAY: "moonpay",
342
  RAMPNETWORK: "rampnetwork", 
343
  MERCURYO: "mercuryo",
344
  TRANSAK: "transak",
345
  BANXA: "banxa"
346
} as const;
347

348
const SUPPORTED_PAYMENT_NETWORK = {
349
  MAINNET: "mainnet",
350
  MATIC: "matic",
351
  BSC_MAINNET: "bsc_mainnet",
352
  AVALANCHE_MAINNET: "avalanche_mainnet",
353
  XDAI: "xdai",
354
  ARBITRUM_MAINNET: "arbitrum_mainnet",
355
  OPTIMISM_MAINNET: "optimism_mainnet"
356
} as const;
357
```