☸️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

Name	Type	Description
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"

Name

Type

Description

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,	
}

{"success": false}

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

Name	Type	Description
address*	String	wallet address

Name

Type

Description

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

Name	Type	Description
*	String	User ID

Name

Type

Description

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

Name	Type	Description
discordId*	String	Discord ID of the user

Name

Type

Description

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

Name	Type	Description
external_id*	String	User ID

Name

Type

Description

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

Name	Type	Description
walletAddress*	String	Wallet address as string e.g., 0xblahblah

Name

Type

Description

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

Name	Type	Description
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

Name

Type

Description

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

Name	Type	Description
*	String	The User ID that want to grant rewards to

Name

Type

Description

String

The User ID that want to grant rewards to

Request Body

Name	Type	Description
xp*	Int	XP
credits*	Int	Credits
eventName*	String	eventName assocated with the reward.

Name

Type

Description

xp*

Int

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

Name	Type	Description
external_id*	String	The ID of the user in your DB that want to grant rewards to

Name

Type

Description

external_id*

String

The ID of the user in your DB that want to grant rewards to

Request Body

Name Type Description

Name	Type	Description
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

xp*

Int

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}

PreviousAPI NextWidget API

Last updated 6 months ago