🛠️How To Integrate

To integrate your points program with Mysticswap, you will need to do two steps:

1. Let Mysticswap see your project's point count per user and

2. Let Mysticswap tell you what changes derived from trading have occurred to a user's points.

Lets go over how we do each of these.

1. Giving Access to Point Data

Your point data must be accessible to our backend, and for that, we need you to provide us an endpoint with each user's point count. This can be achieved by creating a GET endpoint we can use to access your project's point data. Here is the format we (ideally) expect:

GET <${BASE_URL}/:<user address>

An example response we expect is:

200 OK with data format below

{
 message?:"success", //optional
 ok?:true, //optional
 data:{
   points: <user point balance>
   balance?:<user point balance>, // if points are not found, we checks for balance. Either way is acceptable
   address?:<user address>, // useful to mention if something other than wallet address is being used to identify users
 }
}

2. Updating Point Data Via Webhook

When the integration is live, users will trade points with each other in several different ways. That means that you can expect updates to the total amount of points each user has. So your database point count is always up to date and acts as a single source of truth, you must incorporate these changes in your database as well. To do so, you need to read it from our webhook. Here's the expected format:

curl -X GET '<BASE_URL>/otc/<partner>/points-traded?user=<user address>&reference=<lastRequest or x [in hours]>' \ -H 'Authorization: Bearer <your_client_key>'

If no user is added as a query filter, you will receive the changes to all users' points since the last time the webhook was called. If a user is added as filter, you will only receive that user's point update/difference since the last time you have called the webhook.

Here is an example of the response we send:

{
  message: "success",
  data:{
    users:[
      {
        address: <user address>,
        oldPoints: <points they were the last time this webhook was called>,
        newPoints: <point as they are on our backend at the time of this call>,
        pointDifference: <difference in points>,
        lastRequestTime: <>,
      }
    ]
  }
}

3. Transaction Data Webhook (optional)

We also provide you a webhook which you can call to access and analyse data on point transactions, which may be used to introduce new logic such as Sybil protection, etc.

Here is the expected format:

curl -X GET '<BASE_URL>/otc/<partner>/points-transactions?user=<user address>&reference=<x [in hours]>' \ -H 'Authorization: Bearer <your_client_key>'

Just like above, the user needs to be added, otherwise all the trading activity on all users' points since the last time you called this webhook will be sent.

Here is an example of the response we send:

{
  message: "success",
  data:{
    users:[
      {
        address: <user address>,
        transactions:[
          {
            timeTraded: <time of trade completion>,
            pointsTraded: <point as they are on our backend at the time of this call>,
            tokenBalance: <new token balance>
            availableBalance:< available balance>,
          }
        ]
      }
    ]
  }
}

To help you easily measure the difference in points at every query, you can use a specific time reference instead of a global time reference. In other words, the default reference is last_request, i.e. the time the route was called. However, hours can also be used for more customization.

Data flow

First, a couple of concepts - we maintain three points balances for a user: the available balance, token balance, and current balance. The available balance indicates the balance of tokens that are tradeable. The token balance is any difference to a user's points resulting from trading activity since their last sync, and the current balance is what we get from your API whenever a user logs in.

The dataflow goes like this:

• A user logs in and wants to tokenize and trade [our partner] points. All new user points balances are initialized at zero.

• The first endpoint is then called, and the difference between the previous current point balance and new point balance received from the endpoint is added to the user's current balance.

• New points can only be minted after the user's available balance has been synced with their token balance.

• The oldPoints sent is the available Balance and the the newPoints is the token balance (must be <= availableBalance).

• On a successful webhook call, the endpoint is called to update the current balance for the user(s) sent. All user(s) sent will have their available balance updated to the newPoints + (currentBalance - availableBalance), plus the timestamp of the webhook call is also saved.

• The token balance will sync when the user next logs in, to mint/burn the difference of tokenBalance and new availableBalance.

• For [x] hours reference, we use the transaction data to know the balance as at [x] hours ago, sending the token balance as at [x] hours ago instead of the available balance as oldPoints and the token balance as at now as newPoints.

• Users coming in to the app can then mint new tradeable tokens based on the difference of availableBalance and tokenBalance.

And that's it! Follow these simple steps and you should be good to go to have your point program traded on Mysticswap. Facing any issues? Please contact us.