☸️Community Hub API
Our powerful Community Hub API makes it easy to detect, track and auto-verify any in-app or off-chain action.
Authentication
You need to pass your API token as a header x-api-key for all requests.
Where to find your API key
You can find your API key by signing in to sesamelabs.xyz and then visiting Settings -> In-App Events API section.
Events API
Our product already has integrations with social platforms (like Twitter, Discord, Telegram, Youtube, etc). We also have on-chain integrations (Ethereum, Polygon). However, sometimes you might want to create Quests that incentivize off-chain activity that happens within your product (website, mobile, etc). This is where our events API can be used. Use the below POST endpoint to send events. Once that is hooked up, you can create a Quest, select Action type In-App and select the event name from the dropdown.
Create an Event
POST https:/sesamelabs.xyz/api/v0/events
Use this API to send an event that takes place on your website to our servers. This can then be used to create Quests to incentivize user activity within your product.
Request Body
walletAddress*
String
walletAddress of the user that completed the in-game event
value*
Number
number of events completed by the wallet. In most cases it is best to use 1. However if you need to batch multiple completions of the same event, then this value can be something other than 1.
event
String
The name of the event. It would be great to keep the format of the events consistent. E.g. camel casing, active/passive voice etc. e.g., "battleWon"
{
"success":true,
"id":"cl9n8v8io00009k0rtjzwsofm",
"appId":"cl6gosk7700368gbh4h1xwvcz",
"walletAddress":"0x8abDecab4ad7Fc00C599631B662eC103a2F559a4",
"timestamp":"2022-10-24T20:41:43.391Z",
"eventName":"battleWon",
"value":1,
}Users API
User Type
Our User type has the following schema. It would either return the wallet address if the user authenticated with the wallet address or will return the discord id and the user name if requested with the discord id.
User {
id: string,
appId: string,
xp: number,
credits: number,
points: number
level: number,
walletAddress: string?,
discordId: string?,
discordUser: string?,
twitterId: string?,
twitterUsername: string?,
externalId: string?
}Get User by Wallet Address
User by wallet address
GET https://sesamelabs.xyz/api/v0/users/by/wallet/<address>
Fetch a user based on their wallet address.
Path Parameters
address*
String
wallet address
{
"appId": "clif75qg30016usyr0gb0c4mt",
"credits": 0,
"id": "clif7o49z0005usolwkuf7nv0",
"level": 1,
"walletAddress": "0xblahblah",
"xp": 0
}Get User by ID
User by ID
GET https://sesamelabs.xyz/api/v0/users/<id>
Fetch user based on id
Path Parameters
*
String
User ID
{
"appId": "clif75qg30016usyr0gb0c4mt",
"credits": 0,
"id": "clif7o49z0005usolwkuf7nv0",
"level": 1,
"walletAddress": "0xblahblah",
"xp": 0
}Get User by Discord ID
User by DiscordID
GET https://sesamelabs.xyz/api/v0/by/discord/<discordId>
Fetch user based on discord ID.
Path Parameters
discordId*
String
Discord ID of the user
{
"id": "clif7o49z0005usolwkuf7nv0",
"appId": "clif75qg30016usyr0gb0c4mt",
"xp": 0,
"level": 1,
"credits": 0,
"discordId": "3050389892855xxxx",
"discordUsername": "user#2828"
}Get User by External ID
User by External ID
GET https://sesamelabs.xyz/api/v0/users/by/external-identity/<external_id>
Fetch user based on external id
Path Parameters
external_id*
String
User ID
{
"appId": "clif75qg30016usyr0gb0c4mt",
"credits": 0,
"id": "clif7o49z0005usolwkuf7nv0",
"level": 1,
"walletAddress": "0xblahblah",
"xp": 0
}Get Users
Leaderboard
GET https://sesamelabs.xyz/api/v0/users/
Gets a list of users sorted by XP
[
{
"appId": "clif75qg30016usyr0gb0c4mt",
"credits": 0,
"id": "clif7o49z0005usolwkuf7nv0",
"level": 1,
"startedAt": "2023-06-02T23:43:23.303Z",
"walletAddress": "0x3d7ec64a87ed1c446a414bef7d939f39ea16271e",
"xp": 0
},
....
]Create a User with a wallet address
Create user with a wallet address
POST https://sesamelabs.xyz/api/v0/users/
Create a user with a given wallet address.
Request Body
walletAddress*
String
Wallet address as string e.g., 0xblahblah
{
"id": "clif8vqjf000ausolyzzocrfc",
"appId": "clif75qg30016usyr0gb0c4mt",
"xp": 0,
"level": 1,
"credits": 0,
"walletAddress": "0x22ba14068266f2e3daC1d441782001590E0d8EA0"
}Create a User with an external ID
Create user with a external id
POST https://sesamelabs.xyz/api/v0/users/by/external-identity
Create a user with an external identity, email, and name
Request Body
externalId*
String
ID of the user in your DB
fullName*
String
full name of the user
email*
String
email of the user
avatar
String
URL of user's profile picture
{
"id": "clif8vqjf000ausolyzzocrfc",
"appId": "clif75qg30016usyr0gb0c4mt",
"xp": 0,
"level": 1,
"credits": 0,
"walletAddress": "0x22ba14068266f2e3daC1d441782001590E0d8EA0"
}Reward user with XP and Credits
Reward User
POST https://sesamelabs.xyz/api/v0/users/<id>/reward
Reward users with XP and Credits.
Path Parameters
*
String
The User ID that want to grant rewards to
Request Body
xp*
Int
XP
credits*
Int
Credits
eventName*
String
eventName assocated with the reward.
{"success": true}Reward by external user id with XP and Credits
Reward User by external ID
POST https://sesamelabs.xyz/api/v0/users/by/external-identity/<external_id>/reward
Reward external user id with XP and Credits.
Path Parameters
external_id*
String
The ID of the user in your DB that want to grant rewards to
Request Body
xp*
Int
XP
credits
Int
Credits
eventName*
String
eventName assocated with the reward.
points
Int
Same as Credits. Exactly one out of credits or points must be present
{"success": true}Last updated