0
# Torus Embed
1

2
Torus Embed is a JavaScript/TypeScript library that provides seamless Web3 authentication and wallet integration for decentralized applications. It creates an embeddable iframe-based wallet solution that aggregates OAuth logins (Google, Twitter, Discord, etc.) with Multi Party Computation (MPC) technology to provide passwordless authentication for Web3 applications.
3

4
## Package Information
5

6
- **Package Name**: @toruslabs/torus-embed
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @toruslabs/torus-embed`
10

11
## Core Imports
12

13
```typescript
14
import Torus from "@toruslabs/torus-embed";
15
import { 
16
  TorusInpageProvider,
17
  NetworkInterface,
18
  TorusParams,
19
  TorusCtorArgs,
20
  UserInfo,
21
  LOGIN_TYPE,
22
  BUTTON_POSITION_TYPE,
23
  PaymentParams,
24
  PAYMENT_PROVIDER_TYPE
25
} from "@toruslabs/torus-embed";
26
```
27

28
For CommonJS:
29

30
```javascript
31
const Torus = require("@toruslabs/torus-embed").default;
32
const { 
33
  TorusInpageProvider,
34
  NetworkInterface,
35
  TorusParams,
36
  UserInfo
37
} = require("@toruslabs/torus-embed");
38
```
39

40
## Basic Usage
41

42
```typescript
43
import Torus from "@toruslabs/torus-embed";
44

45
// Initialize Torus
46
const torus = new Torus({
47
  buttonPosition: "bottom-left",
48
  modalZIndex: 99999
49
});
50

51
// Initialize the widget
52
await torus.init({
53
  buildEnv: "production",
54
  network: {
55
    host: "mainnet"
56
  },
57
  showTorusButton: true
58
});
59

60
// Login user
61
const accounts = await torus.login({ verifier: "google" });
62
console.log("User accounts:", accounts);
63

64
// Access the Ethereum provider
65
const provider = torus.provider;
66
const balance = await provider.request({
67
  method: "eth_getBalance",
68
  params: [accounts[0], "latest"]
69
});
70
```
71

72
## Architecture
73

74
Torus Embed is built around several key components:
75

76
- **Torus Class**: Main API for widget initialization, authentication, and wallet operations
77
- **TorusInpageProvider**: EIP-1193 compliant Ethereum provider for Web3 interactions
78
- **Iframe Communication**: Secure communication between host application and Torus wallet iframe
79
- **OAuth Integration**: Multi-provider OAuth authentication with verifier management
80
- **Network Management**: Support for multiple Ethereum networks and custom RPC endpoints
81
- **Payment Integration**: Built-in support for multiple fiat-to-crypto providers
82

83
## Capabilities
84

85
### Widget Initialization and Management
86

87
Core functionality for initializing and managing the Torus wallet widget, including configuration, display control, and lifecycle management.
88

89
```typescript { .api }
90
class Torus {
91
  constructor(args?: TorusCtorArgs);
92
  init(params?: TorusParams): Promise<void>;
93
  clearInit(): void;
94
  cleanUp(): Promise<void>;
95
  hideTorusButton(): void;
96
  showTorusButton(): void;
97
}
98

99
interface TorusCtorArgs {
100
  buttonPosition?: BUTTON_POSITION_TYPE;
101
  buttonSize?: number;
102
  modalZIndex?: number;
103
  apiKey?: string;
104
}
105

106
interface TorusParams {
107
  network?: NetworkInterface;
108
  buildEnv?: TORUS_BUILD_ENV_TYPE;
109
  enableLogging?: boolean;
110
  showTorusButton?: boolean;
111
  loginConfig?: LoginConfig;
112
  integrity?: IntegrityParams;
113
  whiteLabel?: WhiteLabelParams;
114
  useWalletConnect?: boolean;
115
  mfaLevel?: "none" | "default" | "optional" | "mandatory";
116
}
117
```
118

119
[Widget Management](./widget-management.md)
120

121
### User Authentication
122

123
OAuth-based authentication system supporting multiple providers (Google, Facebook, Discord, etc.) with session management and user profile access.
124

125
```typescript { .api }
126
login(params?: TorusLoginParams): Promise<string[]>;
127
logout(): Promise<void>;
128
getUserInfo(message: string): Promise<UserInfo>;
129
loginWithPrivateKey(loginParams: {
130
  privateKey: string;
131
  userInfo: Omit<UserInfo, "isNewUser">;
132
}): Promise<boolean>;
133

134
interface TorusLoginParams {
135
  verifier?: string;
136
  login_hint?: string;
137
}
138

139
interface UserInfo {
140
  email: string;
141
  name: string;
142
  profileImage: string;
143
  verifier: string;
144
  verifierId: string;
145
  isNewUser: boolean;
146
  typeOfLogin: LOGIN_TYPE;
147
}
148
```
149

150
[Authentication](./authentication.md)
151

152
### Network and Provider Management
153

154
Ethereum network configuration and Web3 provider management with support for multiple networks and custom RPC endpoints.
155

156
```typescript { .api }
157
setProvider(network: NetworkInterface): Promise<void>;
158
getPublicAddress(args: VerifierArgs): Promise<string | TorusPublicKey>;
159

160
interface NetworkInterface {
161
  host: ETHEREUM_NETWORK_TYPE | string;
162
  chainId?: number;
163
  networkName?: string;
164
  blockExplorer?: string;
165
  ticker?: string;
166
  tickerName?: string;
167
}
168

169
interface VerifierArgs {
170
  verifier: "google" | "reddit" | "discord";
171
  verifierId: string;
172
  isExtended?: boolean;
173
}
174
```
175

176
[Network Management](./network-management.md)
177

178
### Ethereum Provider Interface
179

180
EIP-1193 compliant Ethereum provider for Web3 interactions, RPC requests, and blockchain operations.
181

182
```typescript { .api }
183
class TorusInpageProvider {
184
  readonly chainId: string | null;
185
  readonly selectedAddress: string | null;
186
  readonly networkVersion: string | null;
187
  readonly isTorus: true;
188
  
189
  isConnected(): boolean;
190
  request<T>(args: RequestArguments): Promise<Maybe<T>>;
191
  sendAsync(payload: JRPCRequest<unknown>, callback: Function): void;
192
}
193

194
interface RequestArguments {
195
  method: string;
196
  params?: unknown[] | Record<string, unknown>;
197
}
198
```
199

200
[Ethereum Provider](./ethereum-provider.md)
201

202
### Wallet Operations and Payments
203

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

206
```typescript { .api }
207
showWallet(path: WALLET_PATH, params?: Record<string, string>): void;
208
initiateTopup(provider: PAYMENT_PROVIDER_TYPE, params: PaymentParams): Promise<boolean>;
209
showWalletConnectScanner(): Promise<boolean>;
210

211
interface PaymentParams {
212
  selectedAddress?: string;
213
  selectedCurrency?: string;
214
  fiatValue?: number;
215
  selectedCryptoCurrency?: string;
216
  chainNetwork?: SUPPORTED_PAYMENT_NETWORK_TYPE;
217
}
218

219
type WALLET_PATH = "transfer" | "topup" | "home" | "settings" | "history" | "discover";
220
```
221

222
[Wallet Operations](./wallet-operations.md)
223

224
## Core Types
225

226
```typescript { .api }
227
type BUTTON_POSITION_TYPE = "bottom-left" | "top-left" | "bottom-right" | "top-right";
228

229
type LOGIN_TYPE = 
230
  | "google" | "facebook" | "reddit" | "discord" | "twitch" | "apple"
231
  | "github" | "linkedin" | "twitter" | "weibo" | "line" | "jwt"
232
  | "email_password" | "passwordless" | "wechat" | "kakao";
233

234
type ETHEREUM_NETWORK_TYPE = 
235
  | "sepolia" | "mainnet" | "goerli" | "localhost" | "matic" | "mumbai"
236
  | "xdai" | "bsc_mainnet" | "bsc_testnet";
237

238
type PAYMENT_PROVIDER_TYPE = 
239
  | "moonpay" | "rampnetwork" | "mercuryo" | "transak" | "banxa";
240

241
type SUPPORTED_PAYMENT_NETWORK_TYPE =
242
  | "mainnet" | "matic" | "bsc_mainnet" | "avalanche_mainnet"
243
  | "xdai" | "arbitrum_mainnet" | "optimism_mainnet";
244

245
type TORUS_BUILD_ENV_TYPE =
246
  | "production" | "development" | "binance" | "testing"
247
  | "lrc" | "beta" | "bnb" | "polygon" | "alpha";
248

249
interface TorusPublicKey {
250
  address: string;
251
  X: string;
252
  Y: string;
253
}
254

255
type Maybe<T> = Partial<T> | null | undefined;
256

257
interface WhiteLabelParams {
258
  theme: ThemeParams;
259
  defaultLanguage?: string;
260
  logoDark: string;
261
  logoLight: string;
262
  topupHide?: boolean;
263
  featuredBillboardHide?: boolean;
264
  disclaimerHide?: boolean;
265
  tncLink?: LocaleLinks<string>;
266
  privacyPolicy?: LocaleLinks<string>;
267
  contactLink?: LocaleLinks<string>;
268
  customTranslations?: LocaleLinks<unknown>;
269
}
270

271
interface ThemeParams {
272
  isDark: boolean;
273
  colors: Record<string, string>;
274
}
275

276
interface IntegrityParams {
277
  version?: string;
278
}
279

280
interface LoginConfig {
281
  [verifier: string]: LoginConfigItem;
282
}
283

284
interface LoginConfigItem {
285
  name: string;
286
  typeOfLogin: LOGIN_TYPE;
287
  description?: string;
288
  clientId?: string;
289
  logoHover?: string;
290
  logoLight?: string;
291
  logoDark?: string;
292
  showOnModal?: boolean;
293
  showOnMobile?: boolean;
294
  jwtParameters?: JwtParameters;
295
  mainOption?: boolean;
296
  showOnDesktop?: boolean;
297
  priority?: number;
298
}
299

300
interface JwtParameters {
301
  domain: string;
302
  client_id?: string;
303
  redirect_uri?: string;
304
  leeway?: number;
305
  verifierIdField?: string;
306
  isVerifierIdCaseSensitive?: boolean;
307
  [key: string]: unknown;
308
}
309

310
interface LocaleLinks<T> {
311
  en?: T;
312
  ja?: T;
313
  ko?: T;
314
  de?: T;
315
  zh?: T;
316
  es?: T;
317
}
318
```