Skip to main content
Complete reference documentation for the @uphold/enterprise-travel-rule-widget-web-sdk package. The main class for creating and managing Travel Rule Widget instances is TravelRuleWidget. It requires a TravelRuleWidgetSession object that must be created through the API before instantiating the Widget.

​
Constructor

new TravelRuleWidget<T extends TravelRuleWidgetFlow = TravelRuleWidgetFlow>(
  session: TravelRuleWidgetSession,
  options?: TravelRuleWidgetOptions
)
Parameters:
ParameterTypeRequiredDescription
sessionTravelRuleWidgetSessionYesTravel rule session object obtained from the Create session endpoint
optionsTravelRuleWidgetOptionsNoConfiguration options for the Widget
Generic type parameter: The constructor accepts an optional generic type parameter that specifies the flow type. When provided, it enables better type inference for event handlers, particularly for the complete event. Examples: 
// Generic flow type (default)
const widget = new TravelRuleWidget(session);

// Specific flow type for better type inference
const depositWidget = new TravelRuleWidget<'deposit-form'>(session);
const withdrawalWidget = new TravelRuleWidget<'withdrawal-form'>(session);

​
Options

type TravelRuleWidgetOptions = {
  debug?: boolean;
};
PropertyTypeDefaultDescription
debugbooleanfalseEnable debug mode for additional logging

​
Methods

​
mountIframe()

Mounts the Travel Rule Widget iframe to the specified DOM element. Parameters:
  • element: The HTML element where the Widget should be mounted
Example: 
// Ensure the container has appropriate sizing
const container = document.getElementById('tr-container');

widget.mountIframe(container);
The container element should have explicit dimensions set via CSS. The Widget will fill the entire container. Minimum recommended size is 400px width × 600px height for optimal user experience.

​
unmount()

Unmounts and cleans up the Travel Rule Widget iframe. Example: 
widget.unmount();
The Widget will not unmount itself when a flow is finished, either by successful completion, user cancellation, or unrecoverable error, so it must always be called manually.

​
on()

Registers an event listener for Widget events. Parameters:
  • event: The event name to listen for
  • callback: Function to execute when the event is triggered
Example: 
widget.on('complete', (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
});

​
off()

Removes an event listener for Travel Rule Widget events. Parameters:
  • event: The event name to stop listening for
  • callback: The specific function to remove (must be the same reference as used in on())
Example: 
const handleComplete = (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
};

// Register the listener
widget.on('complete', handleComplete);

// Remove the listener
widget.off('complete', handleComplete);

​
Events

The Travel Rule Widget emits several events during its lifecycle that you can listen to using the on() method.

​
complete

Fired when the Travel Rule form is completed successfully. 
type TravelRuleWidgetCompleteEvent<T = TravelRuleWidgetFlow> = {
  detail: {
    value: T;
  };
};
The event.detail.value contains the Travel Rule compliance data collected from the user. This is an opaque data structure that should be passed to your backend and used when resolving RFIs or creating transactions. Example: 
widget.on('complete', (event: TravelRuleWidgetCompleteEvent) => {
  const travelRuleData = event.detail.value;

  console.log('Travel Rule form completed:', travelRuleData);

  // Send the data to your backend to resolve the RFI or create the transaction
  await submitTravelRuleData(travelRuleData);

  widget.unmount();
});
Usage in different flows: For deposit flows: 
const depositWidget = new TravelRuleWidget<'deposit-form'>(session);

depositWidget.on('complete', async (event) => {
  // Use the travel rule data to resolve the quote requirement
  await resolveQuoteRequirement(quoteId, event.detail.value);

  depositWidget.unmount();
});
For withdrawal flows: 
const withdrawalWidget = new TravelRuleWidget<'withdrawal-form'>(session);

withdrawalWidget.on('complete', async (event) => {
  // Use the travel rule data when creating the transaction
  await createTransaction({
    ...transactionParams,
    travelRuleData: event.detail.value
  });

  withdrawalWidget.unmount();
});

​
cancel

Fired when the user cancels the Travel Rule form. 
type TravelRuleWidgetCancelEvent = {
  detail: {};
}
Example: 
widget.on('cancel', (event: TravelRuleWidgetCancelEvent) => {
  console.log('Travel Rule form cancelled by user');

  widget.unmount();
});

​
error

Fired when an unrecoverable error occurs during the Travel Rule flow. 
type TravelRuleWidgetError = {
  name: string;
  code: string;
  message: string;
  details?: Record<string, unknown>;
  stack?: string;
  cause?: TravelRuleWidgetError;
  httpStatusCode?: number;
}

type TravelRuleWidgetErrorEvent = {
  detail: {
    error: TravelRuleWidgetError;
  };
};
Example: 
widget.on('error', (event: TravelRuleWidgetErrorEvent) => {
  const { error } = event.detail;
  console.error('Travel Rule form error:', error);

  // Handle specific error types
  if (error.code === 'entity_not_found') {
    // Quote or transaction not found - may have expired
    handleExpiredSession();
  } else if (error.code === 'validation_failed') {
    // Form validation error (shouldn't happen in normal flow)
    console.error('Validation error:', error.details);
  } else {
    // Generic error handling
    showGenericError(error.message);
  }

  widget.unmount();
});

​
ready

Fired when the Travel Rule Widget has finished loading and is ready for user interaction. 
type TravelRuleWidgetReadyEvent = {
  detail: {};
}
Example: 
widget.on('ready', (event: TravelRuleWidgetReadyEvent) => {
  console.log('Travel Rule form is ready');
});

​
Types

​
TravelRuleWidgetSession

The session object obtained from the Create session endpoint. 
type TravelRuleWidgetSession = {
  url: string;
  token: string;
  flow: TravelRuleWidgetFlow;
  data: TravelRuleWidgetData;
}

​
TravelRuleWidgetFlow

Represents the different flows supported by the Travel Rule Widget. 
type TravelRuleWidgetFlow = 'deposit-form' | 'withdrawal-form';

​
TravelRuleWidgetData

The data object included in the session, containing context for the flow. 
type TravelRuleWidgetData = {
  provider: 'notabene';
  parameters: object;
};

​
TravelRuleResult

The result object returned upon successful completion of the Travel Rule form. 
type TravelRuleResult = Record<string, unknown>;
The event.detail.value object is an opaque data structure that should be used as-is when resolving RFIs or creating transactions.

​
Complete usage example

Here’s an end-to-end example showing how to use the Travel Rule Widget with all events and type safety: 
import { TravelRuleWidget } from '@uphold/enterprise-travel-rule-widget-web-sdk';

// Create a Travel Rule Widget session from your backend
const session = await createTravelRuleWidgetSession(quoteId);

// Initialize the Widget with type inference
const widget = new TravelRuleWidget<'deposit-form'>(session, { debug: true });

// Handle ready event
widget.on('ready', () => {
  console.log('Travel Rule form is ready');
});

// Handle completion with the Travel Rule data
widget.on('complete', async (event) => {
  const travelRuleData = event.detail.value;
  console.log('Travel Rule form completed:', travelRuleData);

  try {
    // Send the data to your backend to resolve the quote requirement
    await resolveQuoteRequirement(quoteId, travelRuleData);

    // Proceed with the transaction flow
    showSuccessMessage('Travel Rule compliance completed');
  } catch (error) {
    console.error('Failed to submit Travel Rule data:', error);
    showErrorMessage('Failed to submit compliance information');
  }

  widget.unmount();
});

// Handle cancellation
widget.on('cancel', () => {
  console.log('Travel Rule form cancelled by user');
  showCancellationMessage();
  widget.unmount();
});

// Handle errors with specific error handling
widget.on('error', (event) => {
  const { error } = event.detail;
  console.error('Travel Rule form error:', error);

  if (error.code === 'entity_not_found') {
    showErrorMessage('Session expired. Please start over.');
  } else {
    showErrorMessage(error.message);
  }

  widget.unmount();
});

// Mount the Widget to a DOM element
widget.mountIframe(document.getElementById('tr-container'));