GraphQL API Reference

The GraphQL API provides a flexible and efficient interface for querying and aggregating blockchain data on IOST Layer 2. Using this API, you can build custom queries to retrieve exactly the data your application needs, reducing over-fetching and under-fetching commonly encountered in REST APIs.

Endpoint

The GraphQL API endpoint for IOST Layer 2 is:
https://l2-scan.iost.io/graphql

Request Format

GraphQL queries are sent via HTTP POST requests with a JSON payload that includes:

• A query string containing your GraphQL query.
• An optional variables object for dynamic query parameters.

Example request format:

{
  "query": "query { blocks(limit: 10) { number timestamp transactions { hash } } }",
  "variables": {}
}

Schema Overview

The GraphQL schema provides access to various resources, including:

• Blocks: Retrieve block details, timestamps, and transaction summaries.
• Transactions: Query transaction status, values, and related metadata.
• Accounts: Get account balances, history, and associated transactions.
• Tokens: Access token details, transfers, and holder information.
• Statistics: Fetch aggregate data such as transaction volumes and network metrics.

For complete details on available types, fields, and queries, please refer to the GraphQL Playground provided at the endpoint.

Response Format

GraphQL responses follow the standard format:

{
  "data": {
    // Your query result data
  },
  "errors": [
    // Any errors encountered during query execution
  ]
}

Example Usage

Below are several examples demonstrating how to query the GraphQL API for recent blocks on IOST Layer 2.

Sample GraphQL Query

The following sample query retrieves the latest 5 blocks along with their numbers, timestamps, and a summary of transactions (hash, from, and to):

query {
  blocks(limit: 5) {
    number
    timestamp
    transactions {
      hash
      from
      to
    }
  }
}

Using cURL

curl -X POST https://l2-scan.iost.io/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "query { blocks(limit: 5) { number timestamp transactions { hash from to } } }"}'

Using JavaScript (Fetch API)

Here is an example using JavaScript with the fetch API:

async function getRecentBlocks() {
  const query = `
    query {
      blocks(limit: 5) {
        number
        timestamp
        transactions {
          hash
          from
          to
        }
      }
    }
  `;
  
  const response = await fetch("https://l2-scan.iost.io/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query })
  });
  
  const result = await response.json();
  console.log("Recent Blocks:", result.data.blocks);
}

getRecentBlocks();

These examples should help you get started with querying the GraphQL API for IOST Layer 2.

Additional Resources

For more information on constructing GraphQL queries and exploring the schema, please refer to the GraphQL official documentation.