Integrate Claim API - Galxe Docs

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

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.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 integrate gasless claim)
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 get eligible(address:String!) field of credential object and use formula field to calculate the result on your side.
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 get holders(first:Int, after:String) field info to setup NFTs showcase page.

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

query {
  campaign
}

2.2.2. Arguments

Arguments	Description
id String!	You can get campaign id from Galxe Dashboard page’ 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	ormula 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”.

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

2.2.4. Query example

query {
  campaign(id: "GCqBzUtW7w") {
    numberID
    name
    description
    thumbnail
    numNFTMinted
    startTime
    endTime
    formula
    claimedTimes(address: "0xBb3A7bc36b5baFa7691Ccb708EbF299B6d521b05")

    space {
      name
      alias
      thumbnail
    }

    nftCore {
      name
      contractAddress
    }

    nftTemplates {
      name
      image
      ipfsImage
      traits {
        name
        value
      }
    }

    creds {
      id
      name
      description
      credType
      credSource
      eligible(address: "0xBb3A7bc36b5baFa7691Ccb708EbF299B6d521b05")
    }

    nftHolderSnapshot{
      holders(
        block:43009180
        first:100
        after:"-1"
      ){
        list{
          id
          holder
        }
      }
    }
  }
}

2.2.5. Response example

{
  "data": {
    "campaign": {
      "numberID": 4018,
      "name": "New To The Galaxy? Start your adventure here!",
      "description": "Galxe is a collaborative credential infrastructure that empowers brands to build better communities and products in Web3, by leveraging on and off-chain credentials into creative and influential growth campaigns.\n\nCampaigns range from on-chain (ex: depositing on the blockchain) to off-chain (Liking a Tweet, Being a Discord member or attending an AMA, etc)\n\n\nStep 1: Verify your Galaxy ID by setting a username [Here !](https://galxe.com/galaxyid/)\n\nStep 2: Follow us on Twitter \n[Here ! ](https://twitter.com/GalxeHQ?s=20&t=6fgf-DUT7ikDP9Bvuem_vQ)",
      "thumbnail": "https://d257b89266utxb.cloudfront.net/galaxy/images/avatar/0xbb3a7bc36b5bafa7691ccb708ebf299b6d521b05-1655889591.jpg",
      "numNFTMinted": 49618,
      "startTime": 1656450000,
      "endTime": null,
      "formula": "(C_3028&C_3034)*1",
      "claimedTimes": 0,
      "space": {
        "name": "Galaxy Space",
        "alias": "galaxy",
        "thumbnail": "https://d257b89266utxb.cloudfront.net/galaxy/images/galaxyspace/galaxyspace-logo-1640145282.png"
      },
      "nftCore": {
        "name": "[Old version]Galaxy OAT",
        "contractAddress": "0x1871464F087dB27823Cff66Aa88599AA4815aE95"
      },
      "nftTemplates": [
        {
          "name": "New To The Galaxy? Start your adventure here!",
          "image": "https://d257b89266utxb.cloudfront.net/galaxy/images/avatar/0xbb3a7bc36b5bafa7691ccb708ebf299b6d521b05-1655889591.jpg",
          "ipfsImage": "",
          "traits": [
            {
              "name": "Location",
              "value": ""
            }
          ]
        }
      ],
      "creds": [
        {
          "id": "3034",
          "name": "Set Galaxy ID Username",
          "description": "Set your Galaxy ID username in Galxe",
          "credType": "EVM_ADDRESS",
          "credSource": "GRAPHQL",
          "eligible": 1
        },
        {
          "id": "3028",
          "name": "Galxe Twitter Follower",
          "description": "Galxe Twitter Follower",
          "credType": "TWITTER",
          "credSource": "TWITTER_FOLLOW",
          "eligible": 0
        }
      ],
      "nftHolderSnapshot": {
        "holders": {
          "list": [
            {
              "id": "840612",
              "holder": "0xb85b3d61439a3d70d3df7913a3a764f352b32c55"
            },
            {
              "id": "840633",
              "holder": "0x2357f665d833c517238eda7f6ef4a1f323f677f0"
            },
            {
              "id": "840666",
              "holder": "0x8bb60421193a2c2ea2bb442ff162f3e3f3a70f68"
            },
            ...
          ]
        }
      }
    }
  }
}

2.3. Query and mutate credential

2.3.1. query credential info

query {
  credential(id:220244101447720960){
    name
    description
    referenceLink
    credType
    credSource
  }
}

# response
{
  "data": {
    "credential": {
      "name": "MantaNetwork - Twitter Followers",
      "description": "MantaNetwork‘s Twitter followers",
      "referenceLink": "https://twitter.com/MantaNetwork",
      "credType": "TWITTER",
      "credSource": "TWITTER_FOLLOW"
    }
  }
}

2.3.2. update credential items

Use API to update credential Items | Galxe Docs

2.3.3. check address eligiblilty

query {
  credential(id:220244101447720960){
    eligible(address:"0xBb3A7bc36b5baFa7691Ccb708EbF299B6d521b01")
  }
}

# response
{
  "data": {
    "credential": {
      "eligible": 0
    }
  }
}

2.3.4. check address eligiblilty(verify button)

mutation {
  verifyCredential(input:{
    credId:220244101447720960
    address:"0xBb3A7bc36b5baFa7691Ccb708EbF299B6d521b01"
  })
}

# response
{
  "data": {
    "verifyCredential": false
  }
}

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

mutation {
  prepareParticipate
}

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

mutation {
  prepareParticipate(input: {
    signature: ""
    campaignID: "GCqBzUtW7"
    address: "0xBb3A7bc36b5baFa7691Ccb708EbF299B6d521b05"
  }) {
    allow
    disallowReason
    mintFuncInfo {
      verifyIDs
      nftCoreAddress
    }
  }
}

2.4.5. Response example

{
  "data": {
    "prepareParticipate": {
      "allow": true,
      "disallowReason": "",
      "mintFuncInfo": {
        "verifyIDs": [
          52547302
        ],
        "nftCoreAddress": "0x6798f4E7dA4Fc196678d75e289A9d4801C3C849E"
      }
    }
  }
}

2.5. Query participations

Once the claim request is sent, use this API to monitor on-chain Tx status.

2.5.1. Query

query {
  participations
}

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

query {
  participations(id:[53936841]) {
    tx
    status{
  "data": {
    "participations": [
      {
        "tx": "0x95d86011835663ff12e562e3f751817e1b4c2028dc8045bfc38d0b0e2592e2a4",
        "campaign": {
          "id": "GCtf9UUuTn"
        },
        "status": "Success"
      }
    ]
  }
}

2.5.5. Response example

{
  "data": {
    "participations": [
      {
        "tx": "0x95d86011835663ff12e562e3f751817e1b4c2028dc8045bfc38d0b0e2592e2a4",
        "status": "Success"
      }
    ]
  }
}

Getting Started

Smart Contract

Galxe ID Integration

Credential API

Public GraphQL API

​1.1. Entities Diagram

​1.1.1. Space

​1.1.2. Campaign

​1.1.3. NFT Core

​1.1.4. NFT Template

​1.1.5. Credential

​1.1.6. Formula

​1.2. Integration workflow

​2.1. Overview

​2.2. Query campaign

​2.2.1. Query

​2.2.2. Arguments

​2.2.3. Fields

​2.2.3.1. Space fields

​2.2.3.2. NFT Core fields

​2.2.3.3. NFT Template fields

​2.2.3.4. Creds fields

​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

​2.3.3. check address eligiblilty

​2.3.4. check address eligiblilty(verify button)

​2.4. Mutation prepareParticipate

​2.4.1. Mutation

​2.4.2. Arguments

​2.4.3. Fields

​2.4.4. Query example

​2.4.5. Response example

​2.5. Query participations

​2.5.1. Query

​2.5.2. Arguments

​2.5.3. Fields

​2.5.4. Query example

​2.5.5. Response example