If you want to learn more about the XRP Ledger first (concepts, transaction types, etc.) we have a great resource for you at https://learn.xumm.dev:

While app users can simply use the Xaman application interact with the XRP Ledger with their accounts, balances and transactions, the true power of Xaman is unleashed through the platform available for developers.

This way users can interact with third party tools & platforms in the most secure and convenient way, while developers don't have to worry about wallet & key management.

Concept

XRP Ledger transactions are traditionally user initiated: users open their wallet, enter the destination, amount, etc. and then you submit a transaction. This is referred to as a Push Transaction.

In retail / e-commerce & third party interaction scenarios, the ideal flow is inverted: a Pull Transaction. The third party environment wants the user to sign a specific transaction, and a transaction to sign is offered to the user.

This is where the Xaman platform comes in. An XRP Ledger transaction template can be delivered to the end user through the Xaman platform. This is called a Sign Request.

Interaction

The most convenient way to interact with the Xaman platform is through the JavaScript/TypeScript SDK: . There are also some other SDKs available for Backend use in other languages:

The Xaman platform allows for easy integration in your application & workflow. Make sure to check the documentation for your environment:

Welcome to the Xaman Developer Docs! Xaman is a powerful platform designed to make your interaction with the XRP Ledger (XRPL) seamless. Whether you are an experienced developer or just getting started, Xaman offers a range of features, including xApps, payloads, transaction signing, and much more. This documentation will guide you through the essentials to get you up and running in no time.

While app users can simply use the Xaman app to manage their XRP ledger accounts, balances and transactions, the true power of Xaman can be experienced through the Xaman SDK, using our platform made available for developers.

Benefits of QR Scanning:

• Use Cases: QR scanning is common in retail scenarios or multi-device interactions. It is perfect for physical interaction, Point-of-sale terminals, or when users interact across devices (desktop to mobile).

Payload delivery from your native iOS / Android app happens through "Deep Links".

Deep Linking allows your mobile app to communicate directly with the Xumm app, enabling users to interact with payloads effortlessly.

For a detailed guide on implementing mobile payload delivery through Deep Linking, please refer to the page.

Deep Links are a well known flow to allow users to automatically launch and open another app in a specific state. Xumm allows for a Deep Link workflow, where your application (browser based or native) can trigger Xumm to open and immediately show your sign request.

Benefits of Deep Linking:

• When to Use: Opt for deep linking when you want to minimize user steps and create a fluid transition between your app and Xumm.

• Device Compatibility: Deep linking works when the origin (your app or browser) and Xumm are on the same device (iOS/Android).

• Link Creation: Generate a deep link that opens Xumm with the payload ready for interaction, making interactions more seamless while keeping users engaged.

• Return URL: Set a return URL in the payload to redirect users back to your app or browser post-interaction, maintaining a smooth flow.

Note for Web Origins:

For web origins, users return to the default browser, not necessarily the original tab. In order to make this smooth, handle session restoration to ensure continuity.

User Perspective:

For end users, deep linking is a breeze. They tap a link, interact with the payload in Xumm, and return to your app effortlessly.

PaymentChannelAuthorize is normally a 'Command' or locally signed object. Implemented in Xumm as a TransactionType (which it actually isn't, also: the resulting signed blob can never be submitted to an XRPL node as is). For more information, see: https://xrpl.org/use-payment-channels.html

Sample PayChan transactions (gist):

https://gist.github.com/WietseWind/c7b6addfd9b8cb465894209cc9073c47

See on(xAppEvent, fn)

If you want to make sure a WebHook received by your platform has been sent by the Xumm platform, verify the signature the platform sends in an HTTP header.

Every WebHook call contains a signature to verify the authenticity. It sends an HMAC using your application secret as a key. Sample verification in NodeJS:

import crypto from 'crypto'

// Xumm App secret (Xumm developer console)
const secret = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

const timestamp = req.headers?.['x-xumm-request-timestamp'] || ''
const json = req.body

const hmac = crypto.createHmac('sha1', secret.replace('-', ''))
  .update(timestamp + JSON.stringify(json))
  .digest('hex')

console.log(hmac, hmac === req.headers?.['x-xumm-request-signature'])

The getRates method allows you to get the exchange rates for an XRP <> requested pair. The source information is aggregated from several data providers.

const rate = await Sdk.getRates('BTC');

Example response

{
	"USD": 1,
	"XRP": 0.52069,
	"__meta": {
		"currency": {
			"en": "US Dollar",
			"code": "USD",
			"symbol": "$",
			"isoDecimals": 4
		}
	}
}

What is a Payload?

In Xumm, a payload is a sign request sent by applications or developers to users for interaction. Users review the payload and decide to reject or accept by signing.

Delivery Methods

Xumm offers various payload delivery methods:

• Deep Linking: Open the Xumm app with the payload already loaded.

• QR Code Scanning: Users scan a QR code to access the payload.

• Push Notifications: Send payloads as push notifications.

Status Updates

After delivering a payload, tracking its status is vital to know whether the user has interacted with it. Xumm provides mechanisms for obtaining notifications and results of payload interactions. You can learn more about this in the section.

Moving Forward

Now that you have an overview of what payload delivery entails in Xumm, you can delve into the specifics of each delivery method.

Overview

When users interact with payloads, Xumm provides real-time status updates and results (e.g., rejected, signed with signature). These updates allow you to make your application user interface reflect the status of the interaction with the user, and return sign request results to your application.

Real-Time Status Updates

• Keep track of user interactions with the payload.

• Update the UI to reflect statuses like "opened" or "signed".

• They provide status but not the final resolved data (for security reasons, resolved data like signatures can only be separately fetched from the Xumm platform).

Websocket Usage

• Receive real-time updates in your front-end and back-end.

• Frontend: Keep the user informed about the status.

• Backend: Determine when you can fetch final results.

• This ensures responsiveness and keeps the end-user informed.

Fetching End Results

• Webhook: Once the payload is resolved, a Webhook can be sent to your platform for backend processing. For more on WebHooks, see .

• API/SDK: Alternatively, fetch the payload end results using the Xumm API or SDK for more control and flexibility.

Status Updates for End users

Understanding the end user's workflow/experience is vital. The real-time status updates and Webhooks are not just technical tools but communication channels between your application and the user.

By effectively using these features, you ensure an engaging and informed experience for the user.

On average, the Xumm platform allows API consumers to make between 60~200 calls per minute. These numbers depend on the load on the platform and the use of the API consumer.

Some endpoints have lower limits, e.g.:

• POST a Payload (sign request) on average allows for sending 30 payloads per minute

• Fetching TXs (no need to use our platform, best use a native XRPL WebSocket connection): 60 requests per minute

• KYC status: 600 calls per minute

• Account metadata: 120 calls per minute

These numbers are not guarantees: they are averages and can be adjusted by our platform on the fly, based on your overall API call behaviour & end user interaction(s).

Raising API limits

If there are good reasons to assign elevated API limits, we're happy to have a discussion to hear about the reasons how your application consumes the Xumm API, and why your application needs higher limits. Please .

API limits will only be raised if:

• Your app does not use polling techniques: to retrieve the status of a payload, use the websocket we provide for status updates (or the createAndSubscribe / subscribe method provided by the SDK: / ). Backend applications can also use a webhook: .

• (If your app is an xApp) - Your app respects the xApp \

Instead of polling, consider these efficient alternatives:

• Webhooks: Once a payload is resolved, Xumm can send a WebHook to your platform, eliminating the need for constant polling. Learn more: Webhooks.

• Websocket Subscription: Use Websocket to receive live status updates. Learn more: Websocket.

Excessive polling can lead to your application being temporarily rate limited, disrupting your service. If your application has been rate limited, you will receive a notification email later the same day on the e-mail address entered in the application details in the .

• Standard Transaction Types: Xumm accepts all mainnet XRPL transaction types.

  • Exception: Transaction types for non-voted in amendments may be unavailable

  • Payment Channel signature types (non-transaction, receipt) are not yet supported (to be added in Xumm 2.5.0)

• Pseudo-Transaction Types: One pseudo-transaction type: SignIn -

• Limited Transaction Types:: Some transaction types, such as setting a Regular Key or setting a Signer List (multisign), require special permission for user security reasons:

  • Setting a Regular Key

  • Setting a Signer List (multisign)

The difference between XRP Ledger Transaction JSON and a Xumm Payload is that the XRP Ledger JSON needs to be complete and signed locally, while a Xumm Payload can contain an incomplete transaction.

The incomplete transaction, referred to as a Transaction Template, can be delivered to Xumm users allowing end users to view the Payload in the form of a "Sign Request": a transaction to sign and submit, or reject.

Xumm will then add the missing fields like the signer account, network Fee, Account Sequence, based on the context the user provides.

Xumm Payloads use the exact same syntax as the XRP Ledger JSON transaction format.

Here's a step-by-step guide to understanding and implementing Xumm's workflow in your application:

1. Create a Payload: Start by using Xumm's API to create a payload. A payload is essentially a transaction template containing all the details for the transaction you want the User to sign.

2. Deliver the Payload to the User: Once the payload is created, you need to deliver it to the User for signing. Xumm offers multiple delivery options, including push notifications, QR codes, and deep links. Choose the method that best suits your application.

Here's a comprehensive guide to understanding and implementing Xumm's transaction lifecycle:

1. Transaction Template

Start by composing the transaction you want to be signed in JSON format, as per the . You can include all except "Account" and "Sequence", which will be automatically filled by Xumm.

Therefore, any JSON value you'd use to sign and send to an XRPL node can be sent to the Xumm SDK/API, with the (signing) account fields being added/filled being the only major difference.

CORS (Cross-Origin Resource Sharing) is a mechanism that allows a web page from one origin (domain) to access resources from another origin. In other words, it is a security feature implemented by web browsers that restricts a web page from making requests to a different domain than the one that served the web page.

The Xumm API endpoints allow cross origin requests: we want your web application to be able to make calls to the Xumm platform using the credential (JWT) you have received when a user logged in.

If you are building a integration, CORS is irrelevant.

If you are building something in the browser (a web application), the most convenient way to interact with the Xumm platform is through the Javascript/TypeScript SDK: .

However, a payload can include a forced network identifier to specify a particular network. When a user signs a payload, the result includes information about the network the user was on when signing, allowing developers to track and manage transactions across different networks.

This includes options like QR code scanning and deep linking, adapted for larger screens.

• If you can't already identify the user, refer to the

• If you have already identified the user and obtained a user_token, refer to the

While developing your xApp, you may want to easily test & debug your web application. You may even benefit from live reaload during development. You can expose your local development environment with a tool like or and configure your public URL as your xApp URL.

You can get access to the remote browser console using the techniques explained in the article.

If you want to share your xApp with a small group of testers or team members, you can ask them for their Xumm Device Identifier (Xumm - Settings - Advanced). You can add up to 10 Device Identifiers as xApp testers, so they can open your sandboxed xApp.

Offering a direct link / QR code to a payload does not come with the advantages of creating a of getting live feedback & webhooks based on the user's engagement.

The advantage of a simple Sign Link / QR is that you can craft the link / QR once, and it will be available for all users without further code implementations.

Simple Sign Link/QR is available for the following transaction type(s)

• TrustSet (adding a Trust Line, a.k.a. adding a Token)

The Return URL (return_url) determines where the user is sent when the payload is signed. If none is given, the user will simply be displayed Close button in Xumm. Otherwise, the user will be presented a button which launches the Return URL.

The SignIn transaction type is Xaman specific, signature only, can never be submitted. When sending a JSON transaction payload, you can use all XRPL transaction types, including a Xumm-specific "pseudo transaction type": SignIn.

The payload for a SignIn transaction can look like this:

To offer users a direct payment link, you can send them straight to a URL (deeplink) or QR containing that same URL. The URL already contains destination, network, currency & other parameters.

Don't keep a list of explorer links youself: you can easily rely on our explorer launchpad URL.

When using TX Hash

The network param can be mainnet, xahau and any other key from the rails endpoint

The getTransaction method allows you to get the transaction outcome (mainnet) live from the XRP ledger, as fetched for you by the XUMM backend.

Note: it's best to retrieve these results yourself instead of relying on the XUMM platform to get live XRPL transaction information! You can use the package to do this:

Returns:

The getRails method allows you to get the network information for all networks known to Xumm.

Returns:

This method is only available when using the SDK in a JWT context!

The getNftokenDetail method allows you to get basic XLS20 token information as fetched/parsed/cached for you by the XUMM backend.

Note: it's best to retrieve these results yourself instead of relying on the XUMM platform to get live XRPL transaction information!

Returns:

Sdk.getHookHashes()

The getHookHashes allows you to get all meta information for all Hooks known to Xumm.

Returns:

The ping method allows you to verify API access (valid credentials) and returns some info on your XUMM APP:

Returns :

Parameters

The refreshEvents param. is optional. If passed (and true) the Event list will be forcefully refreshed (updated) when the xApp closes. This can be useful if the xApp closes programatically after e.g. resolving (cancelling) or signing a Sign Request.

Parameters

Syntax

Response

Returns an event: qr

Parameters

Syntax

Parameters

Syntax

Parameters

The verifyUserTokens (or single token: verifyUserToken) method allows you to verify one or more User Tokens obtained from previous sign requests. This allows you to detect if you will be able to push your next Sign Request to specific users.

const someToken = '691d5ae8-968b-44c8-8835-f25da1214f35')

const tokenValidity = Sdk.verifyUserTokens([
  someToken,
  'b12b59a8-83c8-4bc0-8acb-1d1d743871f1',
  '51313be2-5887-4ae8-9fda-765775a59e51'
])

if ((await Sdk.verifyUserToken(someToken).active) {
  // Push, use `user_token` in payload
} else {
  // QR or Redirect (deeplink) flow
}

Returns: Promise<UserTokenValidity[]> or Promise

Can be used to check connectivity / JWT (credential) validity & to obtain basic information about the calling credentials.

Sample response

{
  "pong": true,
  "auth": {
    "quota": {},
    "application": {
      "uuidv4": "8525e32b-1bd0-4839-af2f-f794874a80b0",
      "name": "Some App",
      "webhookurl": "https://webhook.site/3e5dee90-a654-4e34-8112-c4391247a8ee",
      "disabled": 0
    },
    "call": {
      "uuidv4": "4b97cf7a-1837-471f-baed-2ebebcf5adb4"
    }
  }
}

If you are building a backend integration, the flow is slightly different.

Backend

If your application features user sign-in (to identify your user) and you obtained a user_token from a previously signed payload from this specific user, you can add the user_token to the next payload to deliver the payload through a push notification.

The first interaction (to obtain the user_token) will always involve either: showing a QR code for the user to scan with the Xumm app or a deep link to the Xumm app to sign a payload.

A payload containing a user token looks like this:

After posting the payload the Xumm SDK/API, the response will confirm push notification delivery:

Obtaining the `user_token`

From a webhook

After the end user resolves the sign request by signing, the configured application Webhook URL will receive a JSON body per POST request containing the accessToken section:

From a resolved Payload

When you get the payload results, the application.issued_user_token contains the user token.

Delivering Payloads within xApps

Delivering payloads within xApps is about efficiency and user experience. Since the user is already engaged with your xApp inside Xumm, delivering the payload directly within the xApp streamlines the process. This minimizes context switching for the user and keeps them focused on the task at hand.

How to Deliver Payloads within xApps

1. Create a Payload: First, you need to create a payload with the transaction details. This payload is essentially a sign request you want the user to interact with. See:

2. Use Xumm SDK: To deliver the payload within your xApp, use the Xumm SDK. The SDK provides functions allowing you to seamlessly integrate the payload within your xApp. See:

3. Once integrated, the payload will be displayed to the user within your xApp. The user can then review and interact with the payload without leaving the xApp.

JavaScript/TypeScript

NPM

The Xaman Javascript/TypeScript SDK can be found on npm:

CDN

The latest version of the Xumm SDK is always available at:

Code samples

See

Warning (legacy packages)

Some things that may help debugging your xApp:

Remote JS Console

Using you can drop one line (script) in your page's <head> and get realtime access to the remote console (bi-directional).

Replay OTT's

If you open your own xApp using the device you added in the Xumm Developer Console as debug device (using the Device Identifier), the OTT (one time token) can be replayed when visiting from the same IP address.

• Make sure your device (Xumm - Settings - Advanced) is whitelisted as Debug Identifier in the Xumm Developer Console

• Make sure your phone and computer are visiting from the same public IP address (e.g. by having them both on the same WiFi and internet connection

• Obtain your OTT in the xApp: it's the value of the xAppToken query parameter. Your xApp is being called with https://your-url/?xAppToken=...

You will now see your xApp in your browser.

Use your local dev URL as xApp URL

Use a tool like ngrok () or localtunnel.me () to temporarily publish your local development URL to a publicly available URL you can use to access your xApp during live debug/development.

• Partial Payments: if you are processing received payments: make sure to check the delivered_amount (meta) field for the transaction outcome, and not the Amount field. Amount is the instruction, Delivered Amount is the actual delivered amount, which may be lower. See: https://xrpl.org/partial-payments.html

• When determining if users are able to send funds, make sure to take the Account and Owner reserve into account. See: https://xrpl.org/reserves.html You can obtain them with a server_info and account_info call on the chain (tip: use to interact with the network). Then calculate like this:\

• Use WebSockets over HTTP RPC (JSON POST) if you want realtime status updates from the ledger using the subscribe method. You can subsribe to ledger closes, transaction stream and account activity:

A sign SignIn sign request can be as simple as this:

{
  "txjson": {
    "TransactionType": "SignIn"
  }
}

All Xumm payload options are valid for a SignIn transaction.

After the user signs your SignIn request, the server to server call (to your configured Webhook location) will receive the signed transaction containing the signed transaction HEX blob.

Response

When the user signs the Sign Request, you will get a signed transaction (that has never been submitted to the XRP Ledger).

You can now get the account address and some basic public account information from the payload details, and assign this information to your own local dataset, like a session.

Verify the signature

If you want to you can run your own signature verification on the signed SignIn pseudo transaction our platform returns to you. Of course the Xumm platform also verified the signature for you. Would you like to check yourself as well, we have created this package

This makes it really convenient to obtain three things at once, making calls to your own backend with an Autorization: Bearer {The Xumm JWT} header:

1. You obtain basic user information, like the r-address and network the user is connected to, as this information is encoded in the JWT.

2. You can verify the authenticity of the JWT, as it is signed with your own Xumm API Secret.

3. You can make calls from the user context to the Xumm backend with this JWT (for as long as it is valid: 24h).

Every time when a user opens your xApp, a new JWT is issued, valid for 24h.

How to validate a JWT

When using the JWT for authorization, you need to validate it before you can make sure that the user is who they say they are. This is a brief explanation in how to verify the JWT using a npm package called and the bearer provided by the Xumm SDK.

You can obtain the JWT associated with the OTT by initiating the Xumm SDK:

Then get the bearer by awaiting the environment:

First, run:

After this, use the code underneath to verify the JWT. You'll need the xApp API Secret to sign the JWT and check it's validity.

This xApp API Secret is found in the developer console at .

To get payload details, status and if resolved & signed: results (transaction, transaction hash, etc.) you can get() a payload.

Note! Please don't use polling! The XUMM API offers Webhooks (configure your Webhook endpoint in the Developer Console) or use a subscription to receive live payload updates (for non-SDK users: Webhooks).

You can get() a payload by:

• Payload UUID

  Copy

  const payload = await Sdk.payload.get("aaaaaaaa-bbbb-cccc-dddd-1234567890ab");

• Passing a created Payload object (see: Sdk.payload.create)

If a payload can't be fetched (eg. doesn't exist), null will be returned, unless a second param (boolean) is provided to get the SDK to throw an Error in case a payload can't be retrieved:

Object

To cancel a payload, provide a payload UUID (string), a <XummPayload> (by performing a Sdk.payload.get() first) or a <CreatedPayload> (by using the response of a Sdk.payload.create() call). By cancelling an existing payload, the payload will be marked as expired and can no longer be opened by users.

Please note: if a user already opened the payload in XUMM APP, the payload cannot be cancelled: the user may still be resolving the payload in the XUMM App, and should have a chance to complete that process.

A response (generic API types here) looks like:

{
  result: {
    cancelled: boolean;
    reason: XummCancelReason;
  }
  meta: XummPayloadMeta;
  custom_meta: XummCustomMeta;
}

Object

Parameters

If you want to request the destination address only, skipping the "Destination Tag" required check & input, you can provide the ignoreDestinationTag param. If not provided (or false) Xumm will chech if the destination account requires a Destination Tag and ask the user to input one.

{ ignoreDestinationTag: boolean }

Syntax

Response

Returns an event: destination. Use to subscribe to the return data.

xumm.payload?.get('some-payload-uuid').then(payloadResult => { /**/ })

If you want the actual blob and signature for the user signed in with the Xumm OAuth2 flow:

1. Get the JWT contents

2. Get the payload from the JWT (that's the Sign In payload)

3. Get that payload with the SDK

4. Check the payload data, the response.hex property holds the signed TX Blob

Now you can verify the signature using the xrpl-verify-signature package, or using any native method capable of verifying XRP Ledger signatures:

Troubleshooting

If an xApp integration doesn't allow for running commands, and the console shows messages like "Couldn't connect to host", problems are a result of the same cause: CORS issues.

• The SDK can't reach Xumm (the app), so:

• "Could not contact Xumm host" error appears, and:

• For example: the openSignRequest trigger doesn't fire, the Sign Request doesn't open, and:

• Xumm keeps on trying, and is stalling the init. to see if the host can be reached - yielding "Attempt n » Retry" console messages (just to make sure it isn't a timing issue).

Find the cause

Check the following things:

1. Are you getting this messages from your frontend console, or backend (node?)

2. Do you have CORS setup correctly? (Allow iframe loading, allow CORS (origin: *)

3. Does your app run over http (instead of https with a valid certificate?)

While #3 and #4 should be valid, we've seen some Android phones where this prevented the integration from working. We use ngrok to work around the local http and non standard port development issues.

\

When creating Sign Requests from a backend environment, the Xumm SDK is called with your API Key & Secret. A payload can be opened by any user. A user will not get notified about a payload, unless if they interacted with the payload through a deeplink or scanning the Payload QR code.

If you want to deliver backend created Sign Requests to a user & the user is identified by your application, you have to provide a user_token to the payload. The user_token can be obtained after the user interacted with your application & signed a payload. See: Push

Seamless xApp Emulation

This is where xAppBuilder shines - it seamlessly emulates your xApp directly on your local development environment.

What does this mean for you? Instant, real-time feedback on your code modifications. Every tweak you save in your IDE, you can immediately see its effect on the emulated xApp.

xAppBuilder transforms these challenges into a smooth, manageable process.

Simplified OTT Replay

One Time Tokens (OTTs) and replay tokens can often present challenges, particularly for those new to xApp development.

xAppBuilder assists in addressing this issue by offering an automatic fetching feature for OTT and Replay OTT, reducing development time and allowing developers to concentrate more on enhancing the functionality of their xApp.

Real-Time Debugging

Debugging becomes a breeze with xAppBuilder. How? With live console logs of your xApp, spotting and fixing bugs is a more efficient process.

These real-time logs help you to monitor and understand your xApp's performance and behavior better.

Get Started with xAppBuilder

Ready to level up your xApp development process? xAppBuilder is now live for Linux on the , , and . Check out the demo video and download the tool today!

For more about xApps and Xumm, visit our . Here's to smoother, faster, and more efficient xApp development. Happy building, developers! 🏗️ 🛠️

Information

• ott

• jwt

• openid

• bearer

Promises (state)

• ready

• retrieving

• success

Authorization

Backend

When communicating with the Xumm platform from your backend environment, you will need a

All payloads get assigned a payload-specific Websocket URL. You can connect to this socket from the client side of your application to receive live status updates (if the user opens the payload on their device and the user resolves the payload).

The pushed information contains minimal information; it is meant to trigger your application to fetch more information from your application's backend.

If a payload doesn't exist, the Websocket connection will receive an {"message":"..."} update, and the socket will be closed. If the payload has expired, the connection will receive a {"expired":true"} message.

If the payload exists and did not expire, the connection will start with a message containing the remaining seconds until expiration: {"expires_in_seconds":51}. This message will be sent every 15 seconds for keepalive reasons. If the connection is still active when the payload expires, a {"expired":true"} message will be sent. The connection will be kept alive, leaving it up to the client to disconnect.

Webhooks are essential for asynchronous communication and can trigger specific actions in your application based on events in Xumm.

If you entered a valid Webhook URL in your Application Settings at the Xumm, your application would receive an HTTP POST containing a JSON body with limited details for the given payload.

Please note a Webhook will not contain the entire payload: to get the entire payload, you should GET the payload using an SDK/API call.

A sample webhook looks like this:

Backend integration intro here...

Sample code

The process to integrate Sign In with Xumm and transaction signing by Xumm with your own native app is actually quite similar to either the flow: it uses OAuth2 (PKCE or Implicit flow) or the flow.

Combined with "Deep Links", your application sending off the user to Xumm will happen with a simple app-redirect. After the user interacted with your sign request, Xumm will return the user to the Return URL: the URL you added to your sign request payload to be opened post-signing.

If your application registers a Deep Link URL as well, and you pass that URL to Xumm as the payload Return URL, the user will be redirected back to your app. To match state, you can add information to the Deep Link URL Xumm sends the user to.

Q: I do not see my xApp in the xAppBuilder. What should I do?

A: Ensure your Device ID has been entered in the Debug Device ID section.

• Step 1: Retrieve your Device ID from Xumm by going to Xumm -> Settings -> Advanced -> Device ID (double tap to copy it).

• Step 2: Visit , select your application, navigate to the xApp section, and paste the Device ID you copied in Step 1 into the Debug Device ID section.

Step 1: Create Your xApp

Begin by opening your preferred code editor (in this case, we are using VS Code). Establish a project folder, and within this, create an index.html file. Type some text between the body tag.

Next, install the Live Server extension for VS Code.

Then, initiate the Live Server by clicking the 'Go Live' button/link located in the bottom right corner of VS Code. Take note of the port number that is displayed.

Step 2: Make Your Website or Web Service Globally Accessible

In your terminal, execute the command npm install -g localtunnel. If you encounter a permission error, use sudo npm install -g localtunnel.

Following this, run lt --port 5500, making sure to replace '5500' with the port number noted in Step 1.

To create a payload, a txjson XRPL transaction can be provided. Alternatively, a transaction formatted as HEX blob (string) can be provided in a txblob property.

Example contents of a payload

The getKycStatus return the KYC status of a user based on a user_token, issued after the user signed a Sign Request (from your app) before (see Payloads - Intro).

If a user token specified is invalid, revoked, expired, etc. the method will always return NONE, just like when a user didn't go through KYC. You cannot distinct a non-KYC'd user from an invalid token.

Alternatively, KYC status can be retrieved for an XPRL account address: the address selected in XUMM when the session KYC was initiated by.

... or using an account address:

Returns .

Notes on KYC information

xApps are WebApps. They are opened in Xumm for a great user experience. They add value (tooling, wizards) for end users, using Sign Requests to help users perform tasks on the XRPL.

To add value for end users, your xApp will most likely implement some of the features Xumm offers natively in your xApp. E.g. open the QR scanner, Account Destination Picker, or start a Sign Request flow. Then to receive the response from these native Xumm flows in your xApp (WebApp).

Your xApp can trigger specific actions in Xumm:

These actions can be sent form your xApp (frontend Javascript) context, and will trigger functionality native to the Xumm app:

• Open a Sign Request

• Returning non-void in the callback function passed to the Sdk.payload.subscribe() method

• Manually calling <PayloadSubscription>.resolve() on the object returned by the Sdk.payload.subscribe() method

The subscription will be closed by either:

Two types of Push:

1. Payload (Sign Request Push). Any application can send Sign Requests with a push notification after the user interacted with the app at least once.

   1. Backend integration: the Webhook & Payload get will contain a user token after the user decided to interact by signing a payload.

Font family

The main application uses the font-family: proxima-nova, sans-serif. Only when using this font for your (web) xApp to be embedded in XUMM, use this stylesheet:

When offering your application anywhere else than as embedded (web) xApp, check your licensing needs and requirements for the use of Proxima Nova.

Parameters

Syntax

• Verify transactions on ledger: Secure Payment Verification

1. Fetch Payload Results: Trigger your application to fetch payload results after receiving a Webhook callback.

2. Inspect Payload Output: Confirm meta.resolved and meta.signed are both true in the payload output.

3. Identify Dispatched Node Type: Ensure response.dispatched_nodetype is "MAINNET" for real payments.

4. Validate Transaction ID: Validate the response.txid value on the ledger.

5. Examine Delivered Amount: Confirm the meta.delivered_amount equals the expected payment amount.

6. Use xrpl-txdata Package: Establish a connection to the XRP Ledger, fetch the transaction by hash, and cross-verify transaction details with the XRPL ledger.

• Consider the end user network:

1. Network Independence: Use the Xumm API/SDK, which operates independently of the network, to allow users the freedom of network choice.

2. Network Information: Ensure the results of a signed payload include the network the user was on during the signing.

3. Forced Network Identifier: Check for the expected result in the Payload results or specify a particular network using a forced network identifier in a payload.

• Verify Webhook signatures:

1. Secure Your Webhooks: Implement appropriate security measures.

2. Verify Payloads: Authenticate received payloads.

3. Error Handling: Develop robust error management mechanisms.

• Protecting your application from the "partial payments exploit" is crucial when implementing payment functionalities. Instead of relying on the Amount field, which merely indicates the transaction instruction, you should base your logic on the delivered_amount field in the transaction metadata. The Amount field is the instruction, and the delivered_amount metadata field is the result. For more detailed information, please refer to the .\

• xApps:

1. xApp Creation & Audit: Anyone can create sandbox xApps, but public release requires an audit by XRPL Labs for user safety, compliance, and value addition.

2. User Experience: xApps must be self-explanatory, prevent dangerous mistakes, and provide a unique experience tailored to Xumm users.

3. Technical & Styling Standards: xApps must meet Xumm's technical guidelines and respect or have unique styling.

xApps are natively aware of the end user context, so a Sign Request payload can easily be served with the xumm.xapp.openSignRequest method: openSignRequest({ … })

<html lang="en">
  <head>
    <script src="https://xumm.app/assets/cdn/xumm.min.js"></script>
  </head>
  <body>
    <pre id=

When a payload (Sign Request) has been created and opened in your xApp, you probably want to be informed if the payload has been signed or rejected, then to check the payload results and act on the results. You can do so by subscribing to the payload event, see:

The Xumm SDK can run fully client side: either as part of your compiled web app or using plain HTML and Javascript using our ready to use browserified version.

Using the Xumm SDK, you can easily add "Sign in with Xumm" capabilities to your web app. You don't even need a backend. You get the full "Web3" experience (sign in with a blockchain account) with our "Web2" compatible stack (see: Identity (OAuth2, OpenID) / Native Apps).

Capabilities

Using the Xumm SDK in your web project, you get:

• Sign in with a QR code for when loaded on a desktop

• Deeplink (redirect to Xumm, back to your web app) on mobile

• Basic user information: XRP Ledger account address, icon (hashicon or even avatar), connected chain (mainnet, testnet, ..) & some basic information about the end user's environment (currency, language, ...)

Sample code

More links

For the SDK documentation (objects, methods), see the SDK section: . For a simple demo of the Xumm SDK in a React Native environment, check this sample repository:

The <PayloadAndSubscription> object is basically a <PayloadSubscription> object with the created payload results in the created property:

All information that applies on Sdk.payload.create() and Sdk.payload.subscribe() applies. create( … ) / subscribe( … ). For the contents of a Payload, see the API Docs for more information about payloads object contents. Differences are:

1. The input for a Sdk.payload.createAndSubscribe() call isn't a payload UUID / existing payload, but a payload to create.

2. The response object also contains (<PayloadAndSubscription>.created) the response obtained when creating the payload.

Example code

Object

The following properties are part of the user object. Every property is a Promise that is resolved when the user is signed in.

• account - r-address

• picture - Profile picture or Hashicon URL

• name - Account name (if present) - e.g. Xumm Pro account name

• domain - Domain name (if present) for account

• source - Information source (e.g. a specific explorer)

• networkType - Enum, e.g. MAINNET, TESTNET, ... the user is connected to

• networkEndpoint - WebSocket endpoint to connect to the network

• blocked - If the account is on a blacklist (e.g. because of scams)

• kycApproved - If the account owner went through opt in KYC with Xumm

• proSubscription - If the account has a Xumm Pro subscription

• profile - Xumm Pro Profile slug (URL)

• token - User Token for future sign request Push delivery

The token field contains a user_token; this token is specific to both the application (SDK) credentials and the end user. It grants you access to asynchronously send notifications to the end user (for 30 days, unless granted long living tokens).

When your application creates a payload for the end user to sign using the SDK session (or JWT), a user will always receive a push notification.

If you want to asynchronously create a payload on your backend using the flow, you can include this token in the user_token field of the payload.

To prevent showing a double loader (first the Xumm xApp loader, then your xApp's loader while hydrating / booting) you have to enable the "Xumm loader till SDK ready() is called" option in the Xumm Developer Console (xApp tab). The xApp will then show the Xumm native loader, until your application calls the ready() method on the Xumm SDK.

Syntax

First your app loads, fetches, etc. Then you have all the information you need to render & show your app, and you call:

Exception flows

1. The xApp doesn't load, to be able to debug the app needs to be displayed (e.g. reverse proxy 502 error or some other app error, preventing the SDK's ready() call being made). With Xumm in Developer Mode, the Xumm loading screen shows a 'Proceed to xApp' button at the Xumm loader screen, below the spinner. This way you can dismiss the Xumm loader and view the underlying problem.

2. The xApp takes very long to load or doesn't load at all: users are confronted with a long wait. If the ready() method in the Xumm SDK isn't called within ~6 seconds a label + button is made visible: "xApp is slow to respond..." [Contact Developer]. This button then opens the Support URL for the xApp as entered in the Developer Console.

xApps are web apps. They are offered to users as integrated apps, opened in Xumm for a great user experience. They add value (tools, apps, wizards, ...) for end users. They receive context information when opened, and can interact with some of the native Xumm features & users through Sign Requests.

Payload Completion and Verification

After a payload completes its lifecycle, which includes creation, user interaction, transaction signing, and transaction submission to the XRP Ledger by Xumm, your application will receive (if configured) a Webhook callback.

This callback should trigger your application to fetch the payload results. It is highly advisable to fetch the payload results again on your "thank you" or "return" page in case you did not persist the payload results after receiving a Webhook.

Payloads are the primary reason for the XUMM API (thus this SDK) to exist.

An XRPL transaction "template" can be posted to the XUMM API. Your transaction tample to sign (so: your "sign request") will be persisted at the XUMM API backend. We now call it a a Payload. XUMM app user(s) can open the Payload (sign request) by scanning a QR code, opening deeplink or receiving push notification and resolve (reject or sign) on their own device.

A payload can contain an XRPL transaction template. Some properties may be omitted, as they will be added by the XUMM app when a user signs a transaction. A simple payload may look like this:

As you can see the payload looks like a regular XRPL transaction, wrapped in an txjson object, omitting the mandatory Account, Fee and Sequence properties. They will be added containing the correct values when the payload is signed by an app user.

Sdk.getHookHash(hookHash: string)

The getHookHash method allows you to get meta information for a specific Hook hash (64 hex chars)

Returns:

The getCuratedAssets method allows you to get the list of trusted issuers and IOU's. This is the same list used to populate the "Add Asset" button at the XUMM home screan.

Returns :

Event order

The following order of events can be expected per environment.

xApp (always auto-signed in)

1. retrieved - xApps always auto-resolve

2. success- all information is populated to SDK properties (Promises)

3. ready - ready to render your application with the correct Xumm SDK state

Web3 (browser) - Signed out & then signing in

1. retrieving - but the user is signed out

2. ready - ready to render your application with the correct Xumm SDK state, but the user must still log in

3. The user signs in

Web3 (browser) - Already signed in

1. retrieving - existing session information is being fetched & verified

2. success - all information is populated to SDK properties (Promises)

3. retrieved - you are dealing with an already signed in user

OAuth2 flows

xApps are WebApps, embedded in Xumm for a great user experience. They add value (tooling, wizards) for end users, using Sign Requests and their Web UI to help users perform tasks on the XRPL and beyond.

• Anyone can create sandbox xApp

• Only you can use your own sandbox xApp from a specific Xumm installation you can whitelist after activating xApp features.

• The fact that you got a sandbox xApp is not to be presented anywhere as an endorsement (e.g. in communication like on social media, etc.))

• To build an xApp, you need to have experience with Frontend Web Development as xApps are WebApps (loaded in Xumm)

• xApps need to add value to a significant share of the Xumm user base

• xApps need to be self explanatory to have clear instructions for end users

• xApps need to be designed in a way where users can not make dangerous mistakes: users need to be protected

• xApps developers can not be anonymous (accountability)

• Promotion of speculation, pushing users towards buying tokens is not allowed (see: user protection)

• Activating xApp features and building a sandbox xApp does NOT guarantee your xApp will be going live in the future. To take your xApp live, it will be audited by XRPL Labs. The rules above apply, security & usability will be tested. If you want to have more certainty in advance, please .

All xApps

• The xApp should be self explanatory, or do a good job explaining to the users what the xApp offers in the very first screen the xApp shows

• xApps can not be designed in a way where it it completely unclear to end users if they are using a third party developed xApp or a XRPL Labs maintained component

• xApps must not be a regular website/webapp fitted in an xApp: the user experience must be to seme degree tailored to users in Xumm, and must have relevance for Xumm users

Technical

• All links to external sites / window opens must be replaced by a openBrowser call on the Xumm SDK: so that users won't reach another website through navigating in the xApp

• Reliable user-bound storage is available not through cookies / localStorage, but through the Xumm userstore:

• No polling should be used: to retrieve the status of a payload, use the websocket we provide for status updates (or the createAndSubscribe

Accessibility

• Simple accessible navigation

• Clear icons:

• Reduce clutter: Keep minimum content on screen

• Use accessible fonts