π˜…π˜‚π—Ίπ—Ί for developers

π˜…π˜‚π—Ίπ—Ί for developers

Use the π˜…π˜‚π—Ίπ—Ί API to send payloads (sign requests) to app users.
npm version

Get Started    API Docs

xApp (technical) flow

xApps are small, user friendly embedded WebApps in XUMM for XRPL Labs / XUMM partners.

πŸ“˜

To publish xApps, contact XRPL Labs Support. Please note: publishing xApps is currently limited to partners XRPL Labs reaches out to.

Getting verified, secure session / user data when an xApp is launched

Your xApp URL will get two extra GET parameters appended when opened, with an "OTT": One Time Token, and the app style (light, dark, ...) for to render the xApp UI. The first GET param. is called xAppToken and contains a UUID. To retrieve the environment and user data for your own xApp session, you must fetch the OTT data from the XUMM API within one minute (and only once): xapp/ott/:token. You can find an example on consuming the OTT data using the XUMM SDK for JS/TS.

🚧

Don't call the XUMM API from your frontend(!)

The XUMM API is not supposed to be called from your frontend (for security reasons). Your XUMM tokens could be used by a 3rd party to trick users into signing sign requests.

You can use our ready to use NodeJS-proxy if you need a simple back end for your SPA / frontend WebApp:

The OTT data will contain the selected r-address of the XRPL account managed with XUMM, as well as the selected locale (in XUMM) and other data. When your WebApp relies on eg. browser locale, please note that you'll have to get the locale from the OTT, as the XUMM xApp frame locale will always be default.

The second GET parameter is called xAppStyle, and contains one of the values as mentioned in the xapp/ott/:token reference. For standard stylesheets to use, see the xApp style guide.

If your xApp URL is configured as https://my.app/?load=true, we will effectively fact call:
https://my.app/?load=true&xAppToken=af0eabb2...&xAppStyle=MOONLIGHT

Special actions (JS) in xApps

Your xApp can trigger specific actions in XUMM:

  • Open a Sign Request (eg. to obtain a user token for future xapp/push / xapp/event (Request) interaction, or simply to sign an XRPL transaction like a Payment, Offer, etc.
  • Open the QR scanner and retrieve a scanned value
  • Close the xApp

Javascript

<script>
  (function() {
    if (typeof window.ReactNativeWebView !== 'undefined') {
      window.ReactNativeWebView.postMessage(JSON.stringify({
        command: 'something'
      }))
    }
  })()
</script>

Open a Sign Request

{
  "command": "openSignRequest",
  "uuid": "5d744667-1e04-4713-86fb-1c1258eda0fd"
}

Open the Destination Picker dialog (since XUMM 2.1)

This method opens the Destination Picker, containing the own accounts, address book & lookup for external accounts:

{
  "command": "selectDestination"
}

Open transaction details panel (since XUMM 2.1)

This method opens the familiar XUMM transaction details panel, with the from/to/amounts/... etc. fields, as if the user opened the transaction from the Events list.

{
  "command": "txDetails",
  "tx": "00000SOMETXHASH000000",
  "account": "r........"
}

Response if closed without selecting a destination:

{
  "method": "selectDestination",
  "destination": null,
  "info": null,
  "reason": "USER_CLOSE"
}

Open the browser (open new URL) (since XUMM 2.1)

This method opens default browser on the OS, with the URL provided:

{
  "command": "openBrowser",
  "url": "https://..."
}

Close the xApp (send command only)

{
  "command": "close",
  "refreshEvents": false
}

When closing an xApp, by default the Event list will not be refreshed. If your xApp uses Events, you can force an Event list refresh by providing the refreshEvents property, with a boolean value true.

Open the QR Scanner, receive scanned QR contents

{
  "command": "scanQr"
}

Subscribe to events (frontend, JS) for scanned QR results:

🚧

Events (eg. QR scanner)

Please note: on iOS, events will be received on window. On Android, events will be received on document. You will need to listen for messages on both to support both platforms (see example above).

function messageHandler (event) {
  console.log(event.data)
}

if (typeof window.addEventListener === 'function') {
  window.addEventListener("message", messageHandler)
}
if (typeof document.addEventListener === 'function') {
  document.addEventListener("message", messageHandler)
}

Possible response event data:

QR code scanned

  • User closed without scanning.

    {
      "method": "scanQr",
      "qrContents": null,
      "reason": "USER_CLOSE"
    }
    
  • User scanned an invalid QR.

    {
      "method": "scanQr",
      "qrContents": null,
      "reason": "INVALID_QR"
    }
    
  • User scanned a QR, the qrContents contain the value of the scanned QR code

    {
      "method": "scanQr",
      "qrContents": "the://scanned-qr/contents?...",
      "reason": "SCANNED"
    }
    

Payload resolved event (receive only)

{
  "method": "payloadResolved",
  "reason": "DECLINED"
}

When the user signs the payload, reason will be SIGNED . Alternatively, when the user closes the payload (sign request) without signing, the value of reason will be DECLINED

Response if closed after selecting a destination:

{
  "method": "selectDestination",
  "destination": {
    "address": "r...",
    "tag": 123456,
    "name": "Wietse's Savings"
  },
  "info":{
   "blackHole":false,
   "disallowIncomingXRP":false,
   "exist":true,
   "possibleExchange":false,
   "requireDestinationTag":false,
   "risk":"UNKNOWN"
  },
  "reason": "SELECTED"
}

Updated 19 days ago


What's next

What are xApps

xApp (technical) flow


xApps are small, user friendly embedded WebApps in XUMM for XRPL Labs / XUMM partners.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.