End-User Custodial Browser SDK Documentation

Overview

The End-User Custodial Browser SDK is a TypeScript/JavaScript library that enables secure wallet functionality for browser-based applications. It provides secure key management and transaction signing capabilities.

This guide walks you through the full end-user custodial payout flow:

1. Initializing the SDK
2. Triggering a user challenge
3. Initializing the SDK with a verification code
4. Signing the payout
5. Executing the payout

---

Installation

1npm install @muralpay/browser-sdk

---

1. Create the SDK Instance

Before using the SDK, mount the authentication iframe in your app.

Configuration

Field	Type	Description
iframeContainerId	string	The ID of the HTML element where the iframe will be mounted
iframeElement	HTMLElement	The actual HTML element (must match the ID above)

HTML:

1<div id="auth-iframe-container-id"></div>

JavaScript:

1import { EndUserCustodialSDK } from '@muralpay/browser-sdk';
2
3const sdk = await EndUserCustodialSDK.createInstance({
4  iframeContainerId: 'auth-iframe-container-id',
5  iframeElement: document.getElementById('auth-iframe-container-id'),
6});

---

2. Trigger Challenge

Trigger an authentication challenge for the user by calling your backend API:

1POST /approvers/end-user-custodial/initiate-challenge

Payload:

• publicKey — Use sdk.getPublicKey()
• approverId — The end-user custodial user's ID

1const publicKey = sdk.getPublicKey();

Response: Contains authorizationId for use in next step.

---

3. Initialize Session with Verification Code

Once the user receives their email verification code, collect it and call:

1await sdk.startSession({
2  code: 'code-from-user-email',
3  authenticatorId: 'authorization-id-from-initiate-challenge',
4});

This creates a secure, authenticated session.

---

4. Sign the Payout

First, retrieve the payload to sign:

1GET /payout/end-user-custodial/body-to-sign/:id

• :id is the payout request ID

Then sign it:

1const signature = await sdk.signPayoutPayload(body); // use the exact body as returned

⚠️ Important: Do not alter the body returned by the API. Modifications will invalidate the signature.

---

5. Execute the Payout

Send the signature to your backend to execute the payout:

1POST /payout/end-user-custodial/execute/:id

Body:

1{
2  "signature": "<signature-from-sdk>"
3}

---

SDK API Reference

Static Methods

createInstance(config: EndUserCustodialSDKConfig): Promise<EndUserCustodialSDK>

Creates and initializes the SDK instance.

1const sdk = await EndUserCustodialSDK.createInstance(config);

---

Instance Methods

startSession(payload: { code: string, authenticatorId: string }): Promise<void>

Initializes the SDK session using the verification code and authorizationId.

1await sdk.startSession({
2  code: 'email-code',
3  authenticatorId: 'auth-id',
4});

getPublicKey(): string

Returns the iframe public key to use in the challenge.

1const publicKey = sdk.getPublicKey();

signPayoutPayload(payload: any): Promise<string>

Signs a payout transaction.

1const signature = await sdk.signPayoutPayload(body);

isSessionActive(): boolean

Checks if a session is currently active.

1if (sdk.isSessionActive()) {
2  // Safe to proceed
3}

clearSession(): void

Clears the session state.

1sdk.clearSession();

getClientSessionExpiry(): Date | null

Returns the session's expiration time.

1const expiry = sdk.getClientSessionExpiry();

---

Full Usage Flow

1// 1. Create SDK instance
2const sdk = await EndUserCustodialSDK.createInstance({
3  iframeContainerId: 'auth-iframe-container-id',
4  iframeElement: document.getElementById('auth-iframe-container-id'),
5});
6
7// 2. Get public key
8const publicKey = sdk.getPublicKey();
9
10// 3. Backend: trigger challenge with publicKey + user ID
11
12// 4. User inputs email code → initialize session
13await sdk.startSession({
14  code: codeFromUser,
15  authenticatorId: authIdFromBackend,
16});
17
18// 5. Backend: fetch /body-to-sign/:id
19const signature = await sdk.signPayoutPayload(body);
20
21// 6. Backend: send signature to /execute/:id

---

Type Definitions

1interface EndUserCustodialSDKConfig {
2  iframeContainerId: string;
3  iframeElement: HTMLElement;
4}
5
6interface TransactionBodyData {
7  to: string;
8  value: string;
9}

Integration with Mural API

This SDK is designed to work seamlessly with the Mural API to enable complete end-user custodial payment solutions for your customers.

What You Can Build:

• Customer Management: Create and manage customer accounts
• End-User Custodial Payments: Enable secure, self-custody transactions
• Payout Systems: Automated or manual payout workflows
• Multi-signature Wallets: Enterprise-grade security features

Getting Started:

1. SDK Integration: Use this browser SDK for frontend wallet functionality
2. API Integration: Connect your backend to our Mural API for customer management
3. Complete Flow: Customers can securely sign transactions without you holding their keys

For API documentation, integration examples, and technical support, contact us at support@muralpay.com

---

Error Handling

The SDK throws clear errors for:

• Missing config or parameters
• Invalid or expired sessions
• Incorrect or altered payloads
• Network or signing failures

Wrap all SDK interactions in try/catch:

1try {
2  const sdk = await EndUserCustodialSDK.createInstance(...);
3} catch (err) {
4  console.error('SDK error:', err);
5}

---

Support & Contact

Questions about integration? We're here to help!

• 📧 Email: support@muralpay.com
• 🔧 Technical Support: API documentation, integration examples, and troubleshooting
• 💼 Business Inquiries: Custom solutions and enterprise features

---

License

MIT © Mural Pay Inc.