Integration Guide

Embedded Wallet Service (EWS) provides a JavaScript SDK that allows you to embed user wallets on any web-enabled platform or JS framework.

Tip: Use the Table of Contents to find what you need faster 👉

Quickstart

Install @paperxyz/embedded-wallet-service-sdk.
Configure Embedded Wallet settings on Developer Dashboard: Auth Settings.

Copy the code snippet containing your Client ID. Call loginWithPaperModal() to sign a user into your app.

import { PaperEmbeddedWalletSdk } from "@paperxyz/embedded-wallet-service-sdk";

const sdk = new PaperEmbeddedWalletSdk({
  clientId: "MY_CLIENT_ID",
  chain: "Mumbai",
  advancedOptions: {
    recoveryShareManagement: RecoveryShareManagement.AWS_MANAGED
  },
});

// Call when the user clicks your "Connect with Paper" button.
<button onClick={() => sdk.auth.loginWithPaperModal()}>
  Connect with Paper
</button>

Get the user object:
```
const user = await sdk.getUser();
```

Make a gasless blockchain call (requires a Sponsored Fees balance).

const params = {
  contractAddress: "0xb2369209b4eb1e76a43fAd914B1d29f6508c8aae",
  methodInterface: "function claimTo(address _to, uint256 _quantity, uint256 _tokenId) external",
  methodArgs: [ user.walletAddress, 1, 0 ],
} as ContractCallInputType;
const { transactionHash } = await user.gasless.callContract(params);

Prerequisites

Install the Embedded Wallet Service JS SDK with your preferred package manager:

npm install @paperxyz/embedded-wallet-service-sdk

yarn add  @paperxyz/embedded-wallet-service-sdk

Configure your application

On Developer Dashboard: Auth Settings, provide some details about your application.

App name: The name of your platform that will be shown to users in UI and emails.
Allowlisted domains: Domains that your app will be hosted on, including production and staging environments.
- Set the first domain as your website URL
- Localhost is supported: http://localhost:3000
- Subdomain wildcards are supported: https://*.example.com

🛠
Advanced: Already have an authentication provider?
Select Use my own authentication method to log in with Custom JWT Authentication. You'll be prompted for a JWKS URI and AUD Value.

Initialize the client SDK

First, create the SDK on the client to create and manage user wallets.

import { PaperEmbeddedWalletSdk } from "@paperxyz/embedded-wallet-service-sdk";

const sdk = new PaperEmbeddedWalletSdk({
  clientId: "c1e1c50a-dde5-4411-83c6-7867ede4a3d5",
  chain: "Mumbai",
  advancedOptions: {
    recoveryShareManagement: RecoveryShareManagement.AWS_MANAGED
  },
});

Reference: PaperEmbeddedWalletSdk

For the recoveryShareManagement option, choosing AWS_MANAGED is the easiest to get started and is generally what we recommend. For more information, see managing the user's recovery share.

Next steps

👉
Authenticate a User

👉
Interact with the Blockchain

👉
Send Transactions (Gasless)

FAQ

Why do I need a Client ID?

The Client ID scopes user wallets to your application. Example: [email protected] signs into App1 and App2 and gets different wallet addresses. App1 would not be able to retrieve or manage the user's wallet created under App2, and vice versa.

Why is the domain allowlist required?

The Client ID is provided on the frontend meaning it can be read by anyone. The domain allowlist ensures only your website can manage your app's user wallets. For instance, a bad actor might copy your client ID and build a similar-looking webpage. The domain allowlist prevents unspecified domains from hosting your login, tricking users to sign in, and transfer assets from those wallets.

Local development environments (e.g. localhost:3000) are safe because users cannot be tricked into loading a localhost link.

Can I use Embedded Wallet Service on a non-HTTPS domain?

No, Embedded Wallet Service relies on cryptography libraries that work only on secure origins. We recommend testing on http://localhost:<port> or with a tool like ngrok and hosting your production app on an HTTPS domain.