🛠️How To Integrate

To integrate with our system for fetching traded points data, you just need to use the following CURL command format:

curl -X GET '<BASE_URL>/otc/points-traded?user=<user_address>&points=<current_user_points>' \
-H 'Authorization: Bearer <your_client_key>'

This endpoint will give you the difference in points (previous point count, new point count) for any given user and for any given set period of time. For example, calling this endpoint every 12 hours will give you the updated points for your users based on their transactions on Mysticswap over the last 12 hours.

As such, for a full integration to be done, call this endpoint periodically with a frequency of your choice (e.g. every 6 hours, every 12 hours) and update the point counts on your database, so you always have the most updated source of truth. Anything more frequent than one update per user per hour will be rate limited, to manage load on our systems.

Key Components of the Query

  • <BASE_URL>: Replace this with the base URL of your application.

  • <user_address>: Provide the Ethereum address of the user whose points-traded data you wish to retrieve.

  • <current_user_points>: Include the current number of points held by the user at the time of the request.

  • <your_client_key>: Authenticate your request with your unique client key.

Example Response Structure

Upon a successful request, you will receive a JSON response structured as follows:

{
  "message": "success",
  "data": {
    "users": [
      {
        "address": "<user_address>",
        "oldPoints": "<available_user_point_on_our_end>",
        "currentPoints": "<current_user_point_from_your_call>",
        "newPoints": "<new_point_based_on_the_data_gotten>",
        "pointDifference": "<difference_in_points_between_new_and_old_points>",
        "lastRequestTime": "<timestamp>"
      }
    ]
  }
}

Explanation of Response Fields

  • message: Indicates the status of the request. A value of "success" signifies a successful operation.

  • data.users: An array containing objects representing individual users.

    • address: The Ethereum address of the user.

    • oldPoints: The number of points available to the user according to our records prior to the latest update.

    • currentPoints: The number of points reported by the partner at the time of the request.

    • newPoints: The recalculated number of points based on the data received from the partner.

    • pointDifference: The difference in points between the new and old values.

    • lastRequestTime: The timestamp of the last request made by the user.

This structure aims to provide a clear and concise overview of the user's points situation, facilitating easy integration and understanding of the data flow between your system and ours.

What happens when you do this

Doing this integration will communicate to you any point changes on our side and communicate to us any point changes on your side on a regular basis. That way, your community can trade points on our platform and you will have real-time updates of those trades!

Points Data Access (Optional)

To enable your users to see their points in real-time on Mysticswap (as opposed to their point count asociated with your last API call update), you can send us the URL (GET) with the real-time point count per user, so we may integrate it and show that information to users accordingly. It should follow this format:

GET <${BASE_URL}/:<user_address>>

Expected Response Format

Upon successful retrieval, the expected response format is:

{
  "message": "success", // Optional
  "ok": true, // Optional
  "data": {
    "points": "<user points balance>",
    "balance": "<user points balance>", // If points are not found, checking for balance is acceptable
    "address": "<user address>" // Useful if another identifier besides address is used to identify users
  }
}

Point Data Transactions API (Optional)

For deeper analytics and security measures like Sybil protection, you can integrate the Points Transaction Data API. This will give you a more comprehensive list of transaction data and trading activity for any given user during a period of time. Our integration format for this is:

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

Note: If a specific user is not specified, the response will include all trading activity on users' points since the last reference.

Example Response

A typical response from this endpoint is structured as follows:

{
  "message": "success",
  "data": {
    "users": [
      {
        "address": "<user_address>",
        "transactions": [
          {
            "timeTraded": "<time of trade completion>",
            "pointsTraded": "<point value at this time on our end>",
            "tokenBalance": "<new token balance>",
            "availableBalance": "<available balance>"
          }
        ]
      }
    ]
  }
}

These optional integrations empower partners with insights into trading dynamics and enhance system interoperability, ensuring real-time updates and robust data analysis capabilities.

Advanced Technical Considerations

Managing Points Updates Before Webhook Invocation

To address rapid points accumulation and synchronization challenges, MysticSwap employs a three-tiered balance system: available balance, token balance, and current balance. This approach ensures accurate point tracking and prevents access to newly accrued points until synchronization is complete. Consequently, users cannot access these newly accrued points until the synchronization process completes, ensuring a perfect match between points deducted and added across both systems. The available balance represents the quantity of tokens eligible for trading. The token balance reflects any adjustments to a user's points arising from trading activities since the last synchronization. Meanwhile, the current balance is derived from your API upon user login.

The sequence of events unfolds as follows:

  1. When a user logs in intending to tokenize and trade points associated with our partner, all new points balances are set to zero.

  2. Subsequently, an initial endpoint call calculates the difference between the previously recorded current points balance and the newly obtained points balance from the endpoint. This difference is then added to the user's current balance.

  3. Minting of new points is contingent upon syncing the user's available balance with their token balance.

  4. The oldPoints parameter refers to the available balance, whereas newPoints denotes the token balance, which must not exceed the available balance.

  5. Upon a successful webhook call, the endpoint updates the current balance for the specified users. Their available balance is adjusted to newPoints plus the difference between the current balance and the available balance, with the timestamp of the webhook call also recorded.

  6. The token balance is reconciled upon the user's subsequent login, facilitating the minting or burning of the difference between the token balance and the new available balance.

  7. For a reference period of [x] hours, transaction data is utilized to determine the balance as of [x] hours ago, reflecting the token balance at that time rather than the available balance as oldPoints and the current token balance as newPoints.

  8. New users joining the app can mint tradable tokens based on the discrepancy between the available balance and the token balance.

Addressing Edge Cases

  • Double Minting Prevention: To prevent users from attempting to mint tokens more than once before the available balance is updated, the minting process is restricted to occur only when the available balance changes during the Data Update webhook call. This mechanism invalidates any attempts to mint tokens within this timeframe, thereby avoiding duplicate points issuance.

  • Invalidating Unaccepted Listings: To counteract the possibility of users creating multiple listings for tokenized points before the token count is updated, our Smart Contract deems unaccepted listings as invalid or expired. This measure thwarts potential exploitation by preventing acceptance of listings created before the token count is refreshed.

  • Authorized Token Transfers Only: To safeguard against unauthorized trades or transfers of tokens before the token count is updated, only designated addresses (admin and Seaport contracts) are permitted to conduct transactions. This restriction ensures that only legitimate transactions are processed, preserving the integrity of the tokenized points ecosystem.

Mitigating Synchronization Challenges

  • Rollback Mechanism for Failed Updates: In scenarios where balance synchronization fails during a webhook call, a rollback procedure is activated to restore stability.

  • Handling Negative Differences: To manage situations where a reduction or slashing of user points by the partner or others results in a negative difference in the current balance, a burn mechanism is employed. This approach effectively neutralizes any negative discrepancies, maintaining balance accuracy.

Example project

You can find below the link to an example integration with Mysticswap. In this case, an OTC DEX (another one) integrates with Mysticswap so their points can be traded on our platform.

You will find the integration code under a couple of directories:

  • Service layer in app.service.ts - this is where the core business logic of the integration lives;

  • Controller layer in app.controller.ts - this acts as the intermediary between the client and the service layer.

You can find more detailed info on this in the repo's README file: https://github.com/mysticswap/example-otc-project

PreviousHow It WorksNextMystical Wizard Guild NFT

Last updated