Integrate Claim API
1.1. Entities Diagram
1.1.1. Space
Space is used for aggregating your campaigns.
1.1.2. Campaign
Campaign is the key object that holds all info for NFT claiming process. Except info of itself, like campaign name, thumbnail, description, it also contains info of NFT contract, NFT template etc.
1.1.3. NFT Core
NFT contract(ERC-721) that used for minting NFTs within the campaign.
1.1.4. NFT Template
NFT template of the campaign contains info that used for generating metadata of a minted NFT. Including NFT name, image, traits etc.
1.1.5. Credential
Credential is elemental object that determine whether an address is eligible to claim the NFT. It takes a single wallet address as input and outputs 0(false)/1(true) to indicate whether the wallet address is eligible for this credentail.
1.1.6. Formula(Deprecated)
Formula is a algebraic expression of credentials and entries, the output of formula decide whether and how many NFTs a user can claim witin the campaign. e.g. (C_2&C_3)_1 means a user eligible for both credential 2 and 3 can claim one NFT, (C_4|C_5)_2 means a user eligible for either credential 4 and 5 can claim two NFTs.
1.1.7. TaskConfig
TaskConfig is the configuration structure of campaign’s task condition and task reward. It replaces the previous structure of Formula and credgroup, but we will fill in the credgroup structure with data for compatibility. It is recommended to use this structure when there is TaskConfig.
detailed structure as follows:
1.2. Integration workflow
- Sign up for Galxe Space Dashboard, please visit Create a Space.
- Create credentials through the Dashboard. Upload data for your credentials if their source is CSV file.
- Create NFT core(NFT contract) if needed, if you are only need to intergrate OAT campaign, then it`s not needed.
- Create space through the Dashboard.
- Create campaign with with “Integrate campaign claiming into third-party websites” checked under your space through the Dashboard. (This will turn the campaign into gasless mode, right now we only support any campaign that does not require users to pay gas.)
- Go to your campaign page inside Galxe to check if the campaign info is correct and credentials lighted up for eligible users.
- Release your campaign through Dashboard.
- Integrate
query campaign
API, get campaign info data for rendering your NFT claim page. - If you need to check whether a user is eligible to claim before hand, integrate
query campaign
API to getTaskConfig(address: $address)
, If there is aparticipateCondition
field, it is determined thatparticipateCondition->eligible == true
. If not,rewardConfigs->eligible
it represents the achievement of each set of tasks, andrewardConfigs->rewards->rewardCount
represents the number of rewards that the user can obtain. - Integrate
mutation prepareParticipate
API, send the claim request once user claim. - If needed, integrate
query participations
API to check Tx status periodically. - If you want, integrate
query campaign
API and getholders(first:Int, after:String)
field info to setup NFTs showcase page. - If needed, integrate
query SpaceLeaderboard
API to get Leaderboard info (But if you need data after 1000 positions in the rankings, you need owner auth and add auth-token in query header).
NOTE: Then you will need an access token bound to your galxe account to use this API. Please go to the Galxe user setting page to generate an access token.Then add access-token
in the header of the query.
2.1. Overview
For endpoint and other info, please refer to Overview | Galxe Docs.
And for interface of each GraphQL query, please check docs/schema from Playground - https://graphigo.prd.galaxy.eco/query .
2.2. Query campaign
This API is used for get campaign object, a campaign is the key object that holds all info for NFT claiming process, integrate this API to setup your own NFT claim page. An example of how a campaign can be shown on website: New To The Galxe? Start your adventure here! by Galxe Space | Galxe .
2.2.1. Query
2.2.2. Arguments
Arguments | Description |
---|---|
id String! | You can get campaign id from Galxe Dashboard page`s url once you created a campaign |
2.2.3. Fields
Fields | Description |
---|---|
id | Campaign id is used to identify a certain campaign |
name | Campaign name |
description | Campaign description |
thumbnail | How many NFTs have been minted/claimed for this campaign |
numNFTMinted | How many NFTs have been minted/claimed for this campaign |
startTime | Campaign start time in unix time |
endTime | Campaign end time in unix time, if null means no end time |
formula | (Deprecated)Formula is a algebraic expression of credentials and entries, the output of formula decide whether and how many NFTs a user can claim. |
claimedTimes(address: $String!) | How many times a certain address has successfully claimed in this campaign |
space | Space is object for aggregating your campaigns. Check object fields below |
nftCore | NFT contract that used for this campaign. Check object fields below |
nftTemplate | NFT template contains info that used for generating metadata for a minted NFT. Check object fields below |
creds | Credentials are element object that determine whether an address is eligible to claim the NFT. Check object fields below |
holders(first:Int, after: String) | It shows user who have NFT minted from this campaign, first is same as limit, after is same as offset but it’s a number string and starts from “-1”. |
TaskConfig(address: $String) | TaskConfig is the configuration structure of campaign’s task condition and task reward. |
CredentialGroup(address: $String) | This structure is gradually deprecated. If there is TaskConfig, it is recommended to use the above data structure. If not, compatible data will be filled here. |
2.2.3.1. Space fields
Fields | Description |
---|---|
id | Space id |
name | Space name |
alias | Space alias, used for constructing the space url |
thumbnail | Space icon image |
2.2.3.2. NFT Core fields
Fields | Description |
---|---|
name | NFT contract name |
contractAddress | NFT contract address |
2.2.3.3. NFT Template fields
Fields | Description |
---|---|
name | NFT name metadata |
image | NFT image url metadata |
ipfsImage | NFT decentralized image url metadata |
traits | NFT traits(you can refer to opensea NFT traits) metadata |
2.2.3.4. Creds fields
Fields | Description |
---|---|
id | Credential ID |
name | Credential name |
description | Credential description |
credType | Credential type |
credSource | Credential data source |
eligible(address: $String) | If a certain address is eligible for this credential |
referenceLink | Call-to-Action: For example, Discord, Twitter, Telegram, etc. can use this link to jump to the third-party page for completing the task. If the value is empty, there is no direct jump point, and the task needs to be completed according to the task description. |
2.2.3.5. TaskConfig
Fields | Description |
---|---|
participateCondition | A necessary condition for the campaign, which is optional. If this is present, it is a threshold condition for participating in the campaign. It must be completed to verify the following. |
referralConfig | The task and reward configuration of the campaign`s referral, which is optional. The detailed structure is RewardConfig. |
rewardConfigs | Campaign`s task and reward configuration, the detailed structure is []RewardConfig. |
2.2.3.5.1. rewardConfigs fields
Fields | Description |
---|---|
conditions [ExprEntity] | Campaign Task condition config |
conditionalFormula | This is a combined expression that means conditions, usually simple ALL/ANY, but also supports complex expressions such as: (entity_0&&entity_1)||(entity_3&&entity_4)||(entity_5&&entity_6) |
eligible | It means rewardConfig is eligible. |
description | Reward config desc |
rewards [ExprReward] | Campaign`s rewards config |
rewardAttrVals | Parameter replacement value of multi credential |
2.2.3.5.1.1. condition ExprEntity fields
Fields | Description |
---|---|
cred | Credential Info |
attrs | This parameter is only available when encountering multi credential, such as space user, score, etc. |
attrFormula | This is a combined expression that means conditions, usually simple ALL/ANY, but also supports complex expressions such as: (entity_0&&entity_1)||(entity_3&&entity_4)||(entity_5&&entity_6) |
eligible | It means whether the entire ExprEntity is eligible. |
eligibleAddress | This represents which addresses are eligible (usually means when multiple binding addresses are eligible) |
2.2.3.5.1.2. reward ExprReward fields
Fields | Description |
---|---|
arithmetics | As ExprEntity before, but the attrFormula here is a little different from the above. Here is an arithmetic expression. ex: entity_0+entity_1, entity_0/entity_1, entity_0/2 |
arithmeticFormula | This is a combined expression that represents the amount of the reward, usually a simple constant, but complex expressions are also supported, such as: (entity_0+entity_1)/2, entity_0/2*5 |
rewardType | NFT,TOKEN,DISCORDROLE,LOYALTYPOINTS,OAT,CUSTOM,LOYALTYPOINTSMYSTERYBOX,MINTLIST |
rewardCount | This is the reward quantity value calculated by using the user’s actual data into the expression. |
2.2.3.6. CredentialGroup fields
Fields | Description |
---|---|
credentials | Credential detail strcut, There is an eligible field inside that represents the achievement status of each credential. |
conditionRelation | ALL/ANY |
conditions [CredentialGroupCondition] | Credential gruop condition config |
rewards [CredentialGroupReward] | Credential group rewards config |
2.2.3.6.1. condition CredentialGroupCondition fields
Fields | Description |
---|---|
eligible | It means whether the entire ExprEntity is eligible. |
eligibleAddress | This represents which addresses are eligible (usually means when multiple binding addresses are eligible) |
2.2.3.6.2. reward CredentialGroupReward fields
Fields | Description |
---|---|
rewardType | NFT,TOKEN,DISCORDROLE,LOYALTYPOINTS,OAT,CUSTOM,LOYALTYPOINTSMYSTERYBOX,MINTLIST |
rewardCount | This is the reward quantity value calculated by using the user’s actual data into the expression. |
2.2.4. Query example
2.2.5. Response example
2.3. Query and mutate credential
2.3.1. query credential info
2.3.2. update credential items
Use API to update credential Items | Galxe Docs
2.3.3. check address eligiblilty Single
**NOTE:**This can only check single credential eligible.
**NOTE:**This is just to get the eligible status and will not do verification.
2.3.4. check address eligiblilty(verify button) Single
**NOTE:**This can only check single credential eligible.
**NOTE:**This will verify the user’s data. Some cred types will have recaptcha restrictions (if verify gets a recaptcha error). Verification can only be initiated from the galxe page, we will regularly adjust the types that require recaptcha.
2.3.5. check address eligiblilty(verify button) Universal
**NOTE:**This will verify the user’s data. Some cred types will have recaptcha restrictions (if verify gets a recaptcha error). Verification can only be initiated from the galxe page, we will regularly adjust the types that require recaptcha.
**NOTE:**You can use ExprEntityInput like TaskConfig ExprEntity verify complex conditions.
2.4. Mutation prepareParticipate
This API send the request for minting a NFT once user claim, our backend will eventually call the NFT contract to have the NFT minted to user.
2.4.1. Mutation
2.4.2. Arguments
Arguments | Description |
---|---|
signature String! | Deprecating, keep it a empty string |
campaignID String! | Campaign ID |
address String! | User’ wallet address, you can get it from user’s wallet connection or just a plain test input. In either way, for a successful claim, this address must be eligible through credentials of this campaign. |
mintCount Int | Batch claim count, if batch claim is needed. Otherwise don’t pass in this argument. |
2.4.3. Fields
Fields | Description |
---|---|
allow | If the user is able to claim the NFT |
disallowReason | Claim failed reason |
mintFuncInfo-> verifyIDs | Unique ids(if it’s a batch claim, there will be multiple ids) for identifying and getting on-chain Tx(s) |
mintFuncInfo-> nftCoreAddress | NFT contract address |
2.4.4. Query example
2.4.5. Response example
2.5. Query participations
Once the claim request is sent, use this API to monitor on-chain Tx status.
2.5.1. Query
2.5.2. Arguments
Arguments | Description |
---|---|
id [Int!]! | ids are verify ids returned by mutation prepareParticipate API |
2.5.3. Fields
Fields | Description |
---|---|
tx | Tx address |
status | Tx status. Status enum: Generated, tx is just born; Pending, tx is in pending; Success, tx is succeed; Queueing, tx is still in message queue; Failed, tx is failed |
2.5.4. Query example
2.5.5. Response example
2.6. Query SpaceLeaderboard
You can use this query to query the info information of the leaderboard of space.
2.6.1. Query
2.6.2. Arguments
Arguments | Description |
---|---|
id Int! | space id |
pageSize Int! | page size |
order | Points/GalxeID |
cursorAfter String | You don’t need to pass in this value on the first page. On the second page, you can start passing in the endCursor value returned by the first page. |
sprintId Int | The id value of the Session can access the data of the specified Session. |
2.6.3. Fields
Fields | Description |
---|---|
rank | user rank in this leaderboard |
points | user point at this space/sprint |
address | user info has more field for detail |