API-Verified Quest (GraphQL)

How to set up custom quest using GraphQL API.


GraphQL verification takes a single wallet address or email as input and outputs 0(false)/1(true) to indicate whether the wallet address is eligible. It requires 3 fields to be filled in: GraphQL Endpoint (HTTPs), Query and Expression.

Sequence Diagram

GraphQL Endpoint (HTTPs)

It's the HTTPs endpoint where Subgraph queries go to, see the example below.

NOTE: If you saw an error when testing the API, check if the endpoint is a valid GraphQL API endpoint. Common misconfigurations include:

  • Incorrectly used a GraphQL playground url, that usually ends with /graph

  • The GraphQL endpoint does now allow CORS from carv.io.


The GraphQL query requires a single wallet address as input. In the dashboard, once you finish your query, fill in a test address and click 'Run' button to check if the query's return is good.


A JavaScript (ES6) function with this type signature: (object) => int. The function must be anonymous, which means that the first line of the expression should be like function(data) {, instead of let expression = (data) => {.

The function should return either number 1 or 0, representing if the address has completed the quest. Behind the scenes, first, we send the query with the user's address to the GraphQL endpoint, and then we will apply the function against the 'data' field of the response. If the returned value is 1, then user is considered to have completed this quest, otherwise not.

Once the query's output is good, click 'Run' button to check if expression processes the query's output correctly.

Subgraph Examples




query info($address: String!) {
  # write you query here 
    first: 1
    where: {token_: {identifier: "1"}, account_: {id: $address}}
  ) {
    account {
    token {

# test address: 0x357A5eE000B5cA0935Aad7bb4Cb96E8AcAf46727

Query Output

  "erc1155Balances": [
      "account": {
        "id": "0x357a5ee000b5ca0935aad7bb4cb96e8acaf46727"
      "token": {
        "id": "0xc2f24ffe96a69e381a747dc73fcd51492e29a0a4/0x1",
        "identifier": "1"


function verify(data){
    if (data.erc1155Balances.length > 0){
        return true
    } else {
        return false

Expression Output


Last updated