Integration with Monerium

Install dependencies

Initialize the MoneriumPack

The protocolKit is an instance of the Safe (opens in a new tab) class. For more information on how to instantiate the protocol-kit refer to the Protocol Kit Quickstart section.

The MoneriumPack will use the Safe account address configured in the protocolKit to link to your Monerium account.

Login with Monerium

Start the Login with Monerium flow by creating a button or link in your application. Use your favorite UI library to add a handler and start the login flow. In the button handler you should start the flow by calling the open method:

This action will open the Monerium web page to begin the authentication process and get the permissions to gain access to your information.

Take a look to the Monerium web page URL. You will see that the query string includes parameters such as these, among others:

• address: The Safe address you want to bind to your Monerium account.
• signature: Always "0x." It means the origin wallet is a multisig, just like the Safe. Monerium will then verify for onchain signatures in your Safe contract.
• chain: The Monerium selected chain. The value is automatically calculated using the protocolKit instance.
• network: The Monerium selected network. The value is automatically calculated using the protocolKit instance.
• redirect_uri: The redirectUrl you sent in the MoneriumPack constructor. Once authenticated Monerium dashboard will redirect to that URL.

It's important to be aware of what's happening during this initial interaction. A signMessage transaction accepting the required Monerium message (opens in a new tab) will be proposed to your Safe the first time you try to link your Safe address. To confirm and execute it, you must also add the remaining signatures in the Safe UI and execute the transaction.

Once you are in the Monerium web page, you should login or create a new account if you don't have one already.

After that, the Monerium UI, will wait until it detects the Safe address has signed the message as explained above and the transaction is executed. You may need to reload the Monerium UI page once you know the transaction was executed in order to continue with the flow. Alternatively, you can start the process again and Monerium will detect the transaction confirmation immediately.

Note. If you use the sandbox environment, you can test this flow without KYC in Goerli. To use the mainnets for Ethereum, Gnosis or Polygon in production, you need to create an account in the Monerium dashboard and complete KYC. The production environment involves real money, whereas the sandbox environment uses fake money and test tokens.

Accept access permission

Once you authenticate through the Monerium UI, a window will appear asking for permission to access your information. If you accept, control will be returned to the redirectUrl you specified in the MoneriumPack constructor.

Authentication

Once we reach the redirectUrl we can call open again, now without using arguments.

If the process was successful, you will be now authenticated with Monerium and your Safe will be linked. You can start using the safeMoneriumClient instance to interact with your Monerium account. This instance is an enhanced version of the Monerium SDK, with some additional Safe features.

To learn more about the methods you can use with the safeMoneriumClient instance, check the Monerium SDK documentation (opens in a new tab).

Here are some examples:

When you reload a page, you usually want to stay authenticated as long as the tokens are valid. To do this, just call the open() method without arguments.

Place an order

In the production environment, real funds will be transferred. In the sandbox environment, fake money will be used. If you add funds using the sandbox or create a transfer from your bank account to your Monerium IBAN in the production environment, you'll receive the corresponding tokens in your Safe. For example, if your Monerium IBAN is associated with the EURe token of your Safe, and you transfer 10 euros, the EURe balance of your Safe will be 10 after the SEPA system completes the transfer.

Add tokens to your Safe using the sandbox. They should be available almost instantly. You can check the balance of your assets here (opens in a new tab) afterwards.

Once you have tokens, you can create a redeem order (opens in a new tab) to burn them and convert them to fiat. Include a text box for an IBAN and a button to place the order. Add a handler for the button and do the following:

Once you place your order, it will be sent to the destination account. Two things will occur:

• A signMessage transaction will be proposed to the Safe services indicating in the message the amount of tokens to burn and the destination IBAN. To verify the message to be signed, refer to the API docs (opens in a new tab). You should confirm and execute it using the Safe UI or an alternative method as the transaction data is returned in the send() call.
• An order is placed in the Monerium system, it listens for the signMessage transaction above to be confirmed and executed.

Once the transaction is recorded on the blockchain, the token is burned and the transfer of real money begins, completing the order 🚀.

Listen to Monerium events

Listening to events is important for understanding what's happening around. It helps us to create a proper UI in our web page.

You probably want to know when the order is completed. For this you can listen to events using the Monerium API web sockets (opens in a new tab)

Connecting to the socket is easy, just use the moneriumPack instance along with the subscribe() and unsubscribe() methods.

To subscribe, do this:

The potential states are this ones:

If you wish to unsubscribe, you can do: