{"id":13768513,"url":"https://github.com/francisrosario/xumm4j","last_synced_at":"2025-05-10T23:31:22.390Z","repository":{"id":37982588,"uuid":"387440555","full_name":"francisrosario/xumm4j","owner":"francisrosario","description":"Java SDK - Interact with the XUMM Developer API the easy way 🌀","archived":false,"fork":false,"pushed_at":"2024-10-04T11:56:57.000Z","size":367,"stargazers_count":7,"open_issues_count":23,"forks_count":3,"subscribers_count":3,"default_branch":"development","last_synced_at":"2024-11-17T03:31:44.141Z","etag":null,"topics":["java","sdk","xrpl","xumm"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/francisrosario.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-19T11:28:40.000Z","updated_at":"2022-11-21T22:19:35.000Z","dependencies_parsed_at":"2023-10-02T18:32:59.702Z","dependency_job_id":"999c516e-504a-4bfc-96e3-188b14b2113e","html_url":"https://github.com/francisrosario/xumm4j","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrosario%2Fxumm4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrosario%2Fxumm4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrosario%2Fxumm4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/francisrosario%2Fxumm4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/francisrosario","download_url":"https://codeload.github.com/francisrosario/xumm4j/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253497296,"owners_count":21917683,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","sdk","xrpl","xumm"],"created_at":"2024-08-03T16:01:22.345Z","updated_at":"2025-05-10T23:31:20.948Z","avatar_url":"https://github.com/francisrosario.png","language":"Java","funding_links":[],"categories":["Libs"],"sub_categories":["Libs/SDK"],"readme":"# XUMM SDK (Java)\n[![](https://jitpack.io/v/francisrosario/xumm4j.svg)](https://jitpack.io/#francisrosario/xumm4j) [![DeepSource](https://deepsource.io/gh/francisrosario/xumm4j.svg/?label=active+issues\u0026show_trend=true\u0026token=E60qi8NmLp4upvGod8CDnNEX)](https://deepsource.io/gh/francisrosario/xumm4j/?ref=repository-badge)\n\n\nInteract with the XUMM API from Java environments.\n\n#### **Please note! The xumm4j SDK (XUMM API in general) is for BACKEND USE only. Please DO NOT use your API credentials in a FRONTEND environment.**\n\n\u003cdiv class=\"alert alert-danger shadow-sm\" style=\"color: #ca0000; border: 1px solid #ca0000; padding: 4px 6px; border-radius: 5px; background-color: rgba(200, 110, 50, .2)\"\u003eTo implement the xumm4j SDK (or XUMM API directly) in your web project, make sure your frontend calls your backend, where the follow-up\ncommunication with the xumm4j SDK (or XUMM API) will take place. Your XUMM credentials should never be publicly available.\u003c/div\u003e\n\n## Installation\nUse this XUMM SDK in your project by adding the following to your `pom.xml`:\n```\n\u003crepositories\u003e\n  \u003crepository\u003e\n    \u003cid\u003ejitpack.io\u003c/id\u003e\n    \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n  \u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.francisrosario\u003c/groupId\u003e\n    \u003cartifactId\u003exumm4j\u003c/artifactId\u003e\n    \u003cversion\u003e0.3.2\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nOptional dependecy if you want to use modified version of xrpl4j model:\n```\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.francisrosario.xrpl4j\u003c/groupId\u003e\n  \u003cartifactId\u003exrpl4j-model\u003c/artifactId\u003e\n  \u003cversion\u003ev2.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## How to use the xumm4j SDK\n\nImport required class.\n```java\nimport com.fl.xumm4j.sdk.builder.CredentialsBuilder;\nimport com.fl.xumm4j.sdk.XummClient;\nimport com.fl.xumm4j.sdk.Deserialize;\n```\n\nNow continue by creating an instance of CredentialsBuilder, XummClient, and Deserialize:\n```java\nCredentialsBuilder myAccess = new CredentialsBuilder.builder()\n  .apiKey(\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\")\n  .secretKey(\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\")\n  .build();\n\n//Pass the created CredentialsBuilder object to XummClient.\nXummClient xummclient = new XummClient(myAccess);\n\n//Use the instance of Deserialize for Deserializing JSON response.\nDeserialize deserialize = new Deserialize();\n```\n\n### Credentials\n\nThe XummClient will look in your CredentialsBuilder Object, and It's highly recommended not to hard-code the API Key and Secret Key, You may use https://docs.oracle.com/javase/tutorial/essential/environment/env.html **Environment Variables** to hide your API Key and Secret Key.\n\nCreate your app and get your XUMM API credentials at the XUMM Developer Console:\n\n- https://apps.xumm.dev\n\nMore information about the XUMM API, payloads, the API workflow, sending Push notifications, etc. please check the XUMM API Docs: \n\n- https://xumm.readme.io/docs\n\n\n### Methods \u0026 params (+ samples)\n\nFor more information about the XUMM API, payloads, the API workflow, sending Push notifications, etc., please check the XUMM API Docs: \n\n- `xummclient.*` for the helper methods; Along with methods to get/update payloads for users to sign.\n- `deserialize.*` for JSON deserialization.\n\nPlease note all snippets below assume you created an instance of the XummClient into the `xummclient` object name and DeserializeIT into the `deserialize` object name, as the [How to use the xumm4j](#how-to-use-the-xumm-sdk) section outlines.\n\n#### XummClient methods\n\n#### Payloads\n\nPayloads are the primary reason for the XUMM API (thus, this SDK) to exist. The [XUMM API Docs explain '**Payloads**'](https://xumm.readme.io/docs/introduction) like this:\n\n\u003e  An XRPL transaction \"template\" can be posted to the XUMM API. Your transaction template to sign (so: your \"sign request\") will be persisted at the XUMM API backend. We now call it a **Payload**. XUMM app user(s) can open the Payload (sign request) by scanning a QR code, opening a deep link, or receiving push notifications and resolve (reject or sign) on their device.\n\nA 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:\n\n```java\n/*\n{\n  txjson: {\n    TransactionType : 'Payment',\n    Destination : 'rwiETSee2wMz3SBnAG8hkMsCgvGy9LWbZ1',\n    Amount: '1337'\n  }\n}\n*/\n```\n\nAs you can see, the payload looks like a regular XRPL transaction, wrapped in a `txjson` object, omitting the mandatory `Account`, `Fee` and `Sequence` properties. They will be added containing the correct values when an app user signs the payload.\n\nOptionally (besides `txjson`) a payload can contain these properties ([XUMM API Postpayload](https://xumm.readme.io/reference/post-payload)):\n- `options` to define payload options like a return URL, expiration, etc.\n- `custom_meta` to add metadata, user insruction, your own unique ID, ...\n- `user_token` to push the payload to a user (after [obtaining a user specific token](https://xumm.readme.io/docs/pushing-sign-requests))\n\nInstead of providing a `txjson` transaction, a transaction formatted as HEX blob (string) can be provided in a `txblob` property.\n\n##### xummclient.getPayload\n\nTo get payload details, status and if resolved \u0026 signed: results (transaction, transaction hash, etc.) you can `.getPayload(UUID)` a payload.\n\nYou can `.getPayload(UUID)` a payload by:\n\n- Payload UUID  \n  ```java\n  String JSON = xummclient.getPayload(\"aaaaaaaa-bbbb-cccc-dddd-1234567890ab\");\n  \n  //Alternatively after getting the Response from xummclient.getPayload(), You can now use the DeserializeIT instance.\n  String userToken = deserialize.getPayload(JSON).getIssued_user_token();\n  ```\n\n##### xummclient.postPayload + PayloadBuilder + xrpl4j JSON Builder\n\nCreating payload by using `PayloadBuilder` class and xrpl4j JSON Builder.\n\nImport the following class:\n```java\nimport com.fl.xumm4j.sdk.builder.PayloadBuilder;\n\nimport com.fasterxml.jackson.core.JsonProcessingException;\nimport com.fasterxml.jackson.databind.ObjectMapper;\nimport com.fl.xrpl4j.model.jackson.ObjectMapperFactory;\nimport com.fl.xrpl4j.model.transactions.Address;\nimport com.fl.xrpl4j.model.transactions.Payment;\nimport com.fl.xrpl4j.model.transactions.XrpCurrencyAmount;\n```\n\nThe following code constructs an Payment object, which represents an Payment Transaction:\n```java\nPayment payment = Payment.builder()\n  .fee(XrpCurrencyAmount.ofDrops(12))\n  .destination(Address.of(\"ra5nK24KXen9AHvsdFTKHSANinZseWnPcX\"))\n  .amount(XrpCurrencyAmount.ofXrp(BigDecimal.valueOf(8787)))\n  .build();\n```\nThese objects can be serialized to and deserialized from the rippled JSON representations using the provided Jackson `ObjectMapper`, which can be instantiated using ObjectMapperFactory.\n\nUsing the Payment object we just created, we can use the supplied ObjectMapper to serialize to JSON:\n```java\nObjectMapper objectMapper = ObjectMapperFactory.create();\nString JSON = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(payment);\nSystem.out.println(JSON);\n/*\n{\n  \"Fee\" : \"12\",\n  \"Flags\" : 2147483648,\n  \"Amount\" : \"8787000000\",\n  \"Destination\" : \"ra5nK24KXen9AHvsdFTKHSANinZseWnPcX\",\n  \"TransactionType\" : \"Payment\"\n}\n*/\n```\n\nWe now can now generate the payload object by using `PayloadBuilder` class:\n```java\nString payload = new PayloadBuilder.builder()\n  .txjson(JSON) //Pass the generated JSON Object.\n  .build();\n```\n\nYou can also generate payload by using all of the attributes available:\n```java\nString payloadTwo = new PayloadBuilder.builder()\n  .userToken() //User (Push) token, to deliver a signing request directly to the mobile device of a user (Optional)\n  .txjson(JSON) //Mandatory JSON transaction template to sign. Alternatively a HEX string could be posted in a txblob field.\n  .txblob() // You can provide a HEX transaction template instead of a JSON formatted one here.\n  .submit() // Should the xumm app submit to the XRPL after signing? (Optional)\n  .multisign() // Should the transaction be signed as a multi sign transaction? (Optional)\n  .expire() //After how many minutes should the payload expire? (Optional)\n  .returnURL_App() //Smart device application return URL (Optional)\n  .returnURL_Web() //Web (browser) return URL (Optional)\n  .identifier() //Your own identifier for this payload. This identifier must be unique. If duplicate, an error code 409 will be returned (max 40 positions)\n  .blob() //A custom JSON object containing metadata, attached to this specific payload (stringified max 1500 positions)\n  .instruction() //A message (instruction, reason for signing) to display to the XUMM (signing) user (max 280 positions)\n  .build();\n```\nBy using xrpl4j JSON Builder + xumm4j PayloadBuilder we now have a payload object ready to be submmited using `.postPayload(JSON)` method.\n\n```java\nString JSON = xummclient.postPayload(payload);\n```\nOnce `.postPayload(JSON)` method is executed you'll get a response similar below: \n\nMore information regarding payload **For more information about payloads.** Take a look at the [Developer Docs for more information about payloads](https://xumm.readme.io/docs/your-first-payload).\n\n```json\nSystem.out.println(JSON);\n{\n  \"uuid\": \"1289e9ae-7d5d-4d5f-b89c-18633112ce09\",\n  \"next\": {\n    \"always\": \"https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09\",\n    \"no_push_msg_received\": \"https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09/qr\"\n  },\n  \"refs\": {\n    \"qr_png\": \"https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09_q.png\",\n    \"qr_matrix\": \"https://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09_q.json\",\n    \"qr_uri_quality_opts\": [ \"m\", \"q\", \"h\" ],\n    \"websocket_status\": \"wss://xumm.app/sign/1289e9ae-7d5d-4d5f-b89c-18633112ce09\"\n  },\n  \"pushed\": true\n}\n```\n\nThe `next.always` URL is the URL to send the end-user to, scan a QR code or automatically open the XUMM app (if on mobile). If a `user_token` has been provided as part of the payload data provided to `postPayload()`, you can see if the payload has been pushed to the end user. A button \"didn't receive a push notification\" could then take the user to the `next.no_push_msg_received` URL.\n\nAlternatively, user routing/instruction flows can be custom-built using the QR information provided in the `refs` object. There's more information about the [payload workflow](https://xumm.readme.io/docs/payload-workflow) and a [paylaod lifecycle](https://xumm.readme.io/docs/doc-payload-life-cycle) in the Developer Docs.\n\n##### xummclient.deletePayload\n```java\nString JSON = xummclient.deletePayload(\"00000000-1111-2222-3333-aaaaaaaaaaaa\");\n```\n\nTo cancel a payload, provide a payload UUID (string), By performing a `xummclient.getPayload();` first) or a `\u003cCreatedPayload\u003e` (by using the response of a `xummclient.postPayload();` call). By canceling an existing payload, the payload will be marked as expired and can no longer be opened by users. \n\n**Please note**: *if a user already opened the payload in XUMM APP, the payload cannot be canceled: the user may still be resolving the payload in the XUMM App and should have a chance to complete that process*.\n\n\n```java\nSystem.out.println(JSON);\n/*\n{\n  \"result\": {\n    \"cancelled\": true,\n    \"reason\": \"OK\"\n  },\n  \"meta\": {\n    \"exists\": true,\n    \"uuid\": \"\u003csome-uuid\u003e\",\n    \"multisign\": false,\n    \"submit\": true,\n    \"destination\": \"rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY\",\n    \"resolved_destination\": \"XRP Tip Bot\",\n    \"finished\": false,\n    \"expired\": true,\n    \"pushed\": true,\n    \"app_opened\": false,\n    \"return_url_app\": \"\u003csome-url-or-null\u003e\",\n    \"return_url_web\": \"\u003csome-url-or-null\u003e\"\n  },\n  \"custom_meta\": {\n    \"identifier\": \"some_identifier_1337\",\n    \"blob\": {},\n    \"instruction\": \"Hey ❤️ ...\"\n  }\n}\n*/\n```\n\n##### xummclient.doPing\n\nThe `ping` method allows you to verify API access (valid credentials) and returns some info on your XUMM APP:\n\n```java\nString JSON = xummclient.doPing();\n```\n\nReturns [`\u003cString\u003e`](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html):\n```java\nSystem.out.println(JSON);\n/*\n{\n  quota: {},\n  application: {\n    uuidv4: '00000000-1111-2222-3333-aaaaaaaaaaaa',\n    name: 'My XUMM APP',\n    webhookurl: '',\n    disabled: 0\n  },\n  call: { uuidv4: 'bbbbbbbb-cccc-dddd-eeee-111111111111' }\n}\n*/\n```\n\n##### xummclient.getCuratedAssets\n\nThe `.getCuratedAssets()` method allows you to get the list of trusted issuers and IOU. This is the same list used to\npopulate the \"Add Asset\" button at the XUMM home screen.\n\n```java\nString JSON = xummclient.getCuratedAssets();\n```\n\nReturns [`\u003cString\u003e`](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html):\n```java\nSystem.out.println(JSON);\n/*\n{\n  curatedAssets: {\n    issuers: [ 'Bitstamp', 'GateHub' ],\n    currencies: [ 'USD', 'BTC', 'EUR', 'ETH' ],\n    details: {\n      Bitstamp: [Object],\n      GateHub: [Object]\n    }\n  }\n}\n*/\n```\n\n##### xummclient.getKycStatus\n\nThe `.getKycStatus(user_token)` 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).\n\nIf a user token specified is invalid, revoked, expired, etc., the method will always\nreturn `NONE`, just like when a user didn't go through KYC. This is because you cannot see distinct a non-KYC'd user from an invalid token.\n\nAlternatively, KYC status can be retrieved for an XPRL account address: the address selected in XUMM when KYC was initiated.\n\n```java\nString JSON = xummclient.getKycStatus(\"00000000-0000-0000-0000-000000000000\");\n```\n\n... or using an account address:\n```java\nString JSON = xummclient.getKycStatus(\"wu1dgaUq8DCj3ZLFXzRbc1Aco5xLykMMQ\")\n```\n\nReturns [`\u003cString\u003e`](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html):\n###### Notes on KYC information\n\n- Once an account has completed the XUMM KYC flow, the KYC flag will be applied to the account even if the identity document used to KYC expired. The flag shows that the account was **once** KYC'd by a real person with an actual identity document.\n- Please note that the KYC flag provided by XUMM can't be seen as a \"all good, let's go ahead\" flag: it should be used as **one of the data points** to determine if an account can be trusted. There are situations where the KYC flag is still `true`, but an account can no longer be trusted. Eg. when account keys are compromised and a 3rd party now controls the account. While unlikely, depending on the level of trust required for your application you may want to mitigate against these kinds of fraud.\n\n##### xummclient.getTransaction\n\nThe `.getTransaction(txid)` method allows you to get the transaction outcome (mainnet)\nlive from the XRP ledger, as fetched for you by the XUMM backend.\n\n```java\nString JSON = xummclient.getTransaction(\"DA66B07C9FE0876A3447DE4C57D565FC9C5324485912D10B48C0507F191A4021\");\n```\n\nReturns [`\u003cString\u003e`](https://docs.oracle.com/javase/7/docs/api/java/lang/String.html):\n\n#### App Storage\n\nApp Storage allows you to store a JSON object at the XUMM API platform, containing a max of 60KB of data.\nYour XUMM APP storage is stored at the XUMM API backend, meaning it persists until you overwrite or delete it.\n\nThis data is private and accessible only with your API credentials. This private JSON data can be used to store credentials/config/bootstrap info / ... for your headless application (e.g., POS device).\n\n```java\nString storageSet =  xummclient.setStorage(\"{name: 'Francis', age: 22, male: true}\");\nSystem.out.println(storageSet);\n// true\n\nString storageGet = xummclient.getStorage();\nSystem.out.println(storageGet)\n// {name: 'Francis', age: 22, male: true}\n\nString storageDelete = xummclient.deleteStorage();\nSystem.out.println(storageDelete)\n// true\n\nString storageGetAfterDelete = xummclient.getStorage();\nSystem.out.println(storageGetAfterDelete)\n// null\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancisrosario%2Fxumm4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrancisrosario%2Fxumm4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrancisrosario%2Fxumm4j/lists"}