How to integrate point query service

Description

Loyalty3 enables customized loyalty point experiences by integrating with your points query service.You need to implement the API for querying points in the following instructions to facilitate queries by Loyalty3.

Use Case

After integration of your points query service, you can set the corresponding points threshold in the allow list of NFTs. Only when users meet this condition will they be allowed to mint/claim NFTs.

Business-side configuration: set points threshold

Customer-side page: verify points eligibility

Next, let's take a look at the preparatory work that needs to be done, including API development and API configuration.

API Development

Request Parameters

Parameters	Type	Example	Description
account_id	string	0x6183b0e158e5e591b1d634E64861B8700F90ecb3	User unique identifier, corresponding to a single user and is immutable.
account_type	string	EVM_ADDRESS	Type of account, currently only supports EVM_ADDRESS.
source	string	loyalty3d	Request source, fixed as "loyalty3d" for this interface.
timestamp	number	1687766502	Current second-level Unix timestamp.
sig	string	0x6dabcd2a80311b138fa0855ef02e8faf7ff9c8031909d25635d725e3b661eae30c47edbb09d88c9ecab571077337bec3325058a5a5321e0f59e31b16974f1ad201	Hex format of the signature by the Loyalty3 backend for the request parameters.

Example:

{
   "param":{
      "account":{
         "account_id":"0x6183b0e158e5e591b1d634E64861B8700F90ecb3",
         "account_type":"EVM_ADDRESS"
      },
      "source":"loyalty3d",
      "timestamp":1687766502
   },
   "sig":"0x6dabcd2a80311b138fa0855ef02e8faf7ff9c8031909d25635d725e3b661eae30c47edbb09d88c9ecab571077337bec3325058a5a5321e0f59e31b16974f1ad201"
}

Response Parameters

Parameters	Type	Example	Description
account_id	string	0x6183b0e158e5e591b1d634E64861B8700F90ecb3	User unique identifier, corresponding to a single user and is immutable.
balance	string	100	User's points balance.

Example:

{
   "result":{
      "account_id":"0x6183b0e158e5e591b1d634E64861B8700F90ecb3",
      "balance":"100"
   },
   "error":null
}

API Configuration

After completing the API development, please perform the following 3 steps in the Loyalty3 business management dashboard. Otherwise, you will not be able to set the points allowlist.

Step 1

Step 2

Step 3

Specify the API URL and test address:

After clicking "Test," it will return the Request and Response.

When the response successfully returns the balance, you can click "Confirm" to save the settings:

🎉 Congratulations, you have successfully integrated your points system into Loyalty3! Now you can use points as a eligibility in the NFT allow list.

Frequently Asked Questions

How to ensure that API requests from Loyalty3?

You can verify the sig in the request parameters to confirm that the request is from Loyalty3.

Loyalty3 address: 0xd7f3dbc9d18b6257fe188fa7decb689e665817

Sample code:

msgbts, _ := json.Marshal(param) //get message bytes from "param" field
sigbts, _ := hexutil.Decode(sig) //get sig bytes from "sig" field
pass := ETHVerifySig(loyaltySignAddress,sigbts,msgbts)

func ETHVerifySig(from string, sig []byte, msg []byte) bool {
    fromAddr := common.HexToAddress(from)

    // https://github.com/ethereum/go-ethereum/blob/55599ee95d4151a2502465e0afc7c47bd1acba77/internal/ethapi/api.go#L442
    if sig[64] != 0 && sig[64] != 1 {
       if sig[64] != 27 && sig[64] != 28 {
          return false
       }
       sig[64] -= 27
    }
    pubKey, err := crypto.SigToPub(EthSignHash(msg), sig)
    if err != nil {
       return false
    }
    recoveredAddr := crypto.PubkeyToAddress(*pubKey)

    return strings.EqualFold(fromAddr.Hex(), recoveredAddr.Hex())
}
func EthSignHash(data []byte) []byte {
    msg := fmt.Sprintf("\x19Ethereum Signed Message:\n%d%s", len(data), data)
    return crypto.Keccak256([]byte(msg))
}