Query Examples

Common GraphQL queries for fetching data from Kleros subgraphs.

V2 Core Queries (Arbitrum)

Always use the decentralized network endpoint for production queries. Get the subgraph ID from the Studio pages listed in Subgraph Endpoints and construct the URL as https://gateway.thegraph.com/api/{API_KEY}/subgraphs/id/{SUBGRAPH_ID}.

Fetch Courts

Key fields: minStake (in wei), feeForJuror (juror reward per vote), timesPerPeriod (array of 4 phase durations in seconds).

{
  courts(first: 20, orderBy: id) {
    id
    hiddenVotes
    minStake
    alpha
    feeForJuror
    jurorsForCourtJump
    timesPerPeriod
    parent { id }
    policy { policy }
    numberDisputes
    numberStakedJurors
    stakedJurors {
      id
    }
  }
}

Fetch Recent Disputes

Key fields: externalDisputeID (your app’s ID), templateId (links to DisputeTemplateRegistry), ruled (finalized), currentRuling (active ruling option).

{
  disputes(first: 10, orderBy: createdAtBlock, orderDirection: desc) {
    id
    arbitrated { id }
    court { id }

    period
    ruled
    currentRuling
    tied
    overridden
    lastPeriodChange
    nbRounds
    nbChoices
    externalDisputeID
    templateId
    rounds {
      nbVotes
      totalFeesForJurors
      drawnJurors { juror { id } }
    }
  }
}

Fetch Dispute by External ID

Use externalDisputeID to correlate an on-chain dispute with your app’s internal ID (emitted in DisputeRequest):

query GetDisputeByExternalID($externalId: BigInt!) {
  disputes(where: { externalDisputeID: $externalId }) {
    id
    period
    ruled
    currentRuling
    tied
    templateId
  }
}

Fetch Juror Stakes for a Specific Address

{
  jurorTokensPerCourts(where: { juror: "0xYOUR_ADDRESS_LOWERCASE" }) {
    court { id }
    staked
    locked
  }
}

Fetch Juror’s Active Draws

query GetJurorDraws($juror: String!) {
  draws(where: { juror: $juror, vote_not: null }, first: 20) {
    dispute { id period currentRuling }
    round { id nbVotes }
    vote { choice }
  }
}

Curate Queries (V1)

Fetch Registered Items from a Light Curate List

{
  litems(
    first: 10
    where: {
      status: Registered
      registryAddress: "0xYOUR_LIST_ADDRESS_LOWERCASE"
    }
    orderBy: latestRequestResolutionTime
    orderDirection: desc
  ) {
    itemID
    data
    props {
      type
      label
      description
      value
    }
  }
}

Fetch Items in Challenge Period

{
  litems(
    first: 10
    where: {
      status_in: [RegistrationRequested, ClearingRequested]
      registryAddress: "0xYOUR_LIST_ADDRESS_LOWERCASE"
      disputed: false
    }
    orderBy: latestRequestSubmissionTime
    orderDirection: asc
  ) {
    itemID
    status
    props {
      label
      value
    }
    requests(first: 1, orderBy: submissionTime, orderDirection: desc) {
      submissionTime
      requester
    }
  }
}

Fetch Item Details with Request History

query ItemDetails($id: ID!) {
  item(id: $id) {
    data
    requests(orderBy: submissionTime, orderDirection: desc) {
      requestType
      disputed
      disputeID
      submissionTime
      resolved
      requester
      challenger
      rounds(orderBy: creationTime, orderDirection: desc) {
        appealPeriodStart
        appealPeriodEnd
        ruling
        hasPaidRequester
        hasPaidChallenger
      }
    }
  }
}

Item IDs in the subgraph use the format <itemID>@<listAddress>:

const compoundId = `${itemID}@${tcrAddress.toLowerCase()}`;
const result = useQuery(ITEM_DETAILS_QUERY, { variables: { id: compoundId } });

Address Tag Registries (Gnosis Chain)

Batched query to fetch address tags from the three Kleros address tag registries on Gnosis Chain:

{
  contractDomainTags: litems(
    where: {
      status_in: [Registered, ClearingRequested]
      registryAddress: "0x CONTRACT_DOMAIN_TAG_REGISTRY"
    }
    first: 1000
  ) {
    props { label value }
  }
  addressTags: litems(
    where: {
      status_in: [Registered, ClearingRequested]
      registryAddress: "0x ADDRESS_TAG_REGISTRY"
    }
    first: 1000
  ) {
    props { label value }
  }
}

Subgraph: legacy-curate-gnosis on Graph Explorer (subgraph ID 9hHo5MpjpC1JqfD3BsgFnojGurXRHTrHWcUcZPPCo6m8)

Proof of Humanity

Check Registration Status

{
  submission(id: "0xADDRESS_LOWERCASE") {
    registered
    name
    creationTime
    status
    requests(first: 1, orderBy: creationTime, orderDirection: desc) {
      evidence {
        URI
      }
    }
  }
}

Alternatively, call isRegistered(address) directly on the PoH contract at 0xC5E9dDebb09Cd64DfaCab4011A0D5cEDaf7c9BDb.

Tips

Addresses must be lowercase in all queries. The subgraph stores them as bytes and does not understand checksummed addresses.
Items with status ClearingRequested are still registered until the removal request is finalized. Include them when fetching “active” items.
The Graph hosted service has a 1000 item limit per query. For registries with more items, paginate using skip or id_gt.
Light Curate entities are prefixed with l (e.g., litems, lrequests). Classic Curate uses unprefixed entities (items, requests).

Subgraph Endpoints

Full list of subgraph URLs

Light Curate Integration

Full Light Curate developer guide

Getting Started

V2 Architecture

Arbitrable Apps

Products

Cross-chain

Examples

Subgraph & Data

Query Examples

Query Examples

V2 Core Queries (Arbitrum)

Fetch Courts

Fetch Recent Disputes

Fetch Dispute by External ID

Fetch Juror Stakes for a Specific Address

Fetch Juror’s Active Draws

Curate Queries (V1)

Fetch Registered Items from a Light Curate List

Fetch Items in Challenge Period

Fetch Item Details with Request History

Address Tag Registries (Gnosis Chain)

Proof of Humanity

Check Registration Status

Tips

Further Reading

Subgraph Endpoints

Light Curate Integration

​Query Examples

​V2 Core Queries (Arbitrum)

​Fetch Courts

​Fetch Recent Disputes

​Fetch Dispute by External ID

​Fetch Juror Stakes for a Specific Address

​Fetch Juror’s Active Draws

​Curate Queries (V1)

​Fetch Registered Items from a Light Curate List

​Fetch Items in Challenge Period

​Fetch Item Details with Request History

​Address Tag Registries (Gnosis Chain)

​Proof of Humanity

​Check Registration Status

​Tips

​Further Reading

Subgraph Endpoints

Light Curate Integration

Query Examples

V2 Core Queries (Arbitrum)

Fetch Courts

Fetch Recent Disputes

Fetch Dispute by External ID

Fetch Juror Stakes for a Specific Address

Fetch Juror’s Active Draws

Curate Queries (V1)

Fetch Registered Items from a Light Curate List

Fetch Items in Challenge Period

Fetch Item Details with Request History

Address Tag Registries (Gnosis Chain)

Proof of Humanity

Check Registration Status

Tips

Further Reading