GraphQL API

Our GraphQL API provides a flexible and efficient way to interact with our atomic data structure system. Through this documentation, you'll learn how to query and manipulate atomic data using our GraphQL endpoints. To help you explore and test the API interactively, we've integrated Apollo Explorer sandbox environments throughout this documentation.

These interactive playgrounds allow you to experiment with queries in real-time, seeing exactly how the API responds to different inputs and parameters.

This documentation will be split into sections by primitive, such as Atoms, Triples, and so on.

tip

We maintain a GraphQL SDK for our API that includes these queries with additional hooks for React developers to use directly in their apps. You can find it here: https://github.com/0xIntuition/intuition-ts/tree/main/packages/graphql

Our SDK utilizes GraphQL Codegen and Fragments, but for the sake of clarity and simplicity the query examples in the playgrounds won’t utilize Fragments.

Backend Architecture Overview

This architecture diagram illustrates the data flow and integration stack for the Intuition backend. We ingest data from two primary RPC sources: our EthMultiVault contract and a ChainLinkOracle contract. This blockchain data is processed in a Docker environment indexed through Substreams, parsing and structuring the data into a PostgreSQL database.

Hasura then provides a GraphQL API layer on top of Postgres, enabling flexible data querying powering our app layers. This architecture provides efficient blockchain data indexing, reliable storage, and scalable API access. Our upcoming GraphQL SDK will further streamline the process for app developers looking to consume our data for building and extending the Intuition protocol.

GraphQL Playground

The interactive Apollo Sandbox below lets you explore our GraphQL API in real-time. You can write and execute queries, inspect the schema, and see live responses from our API. We've set up this environment to help you get familiar with our data structure and available operations.

Try starting with some basic queries like fetching atoms or exploring relationship triples. Here's a query to get you started:

query GetAtoms(
  $limit: Int
  $offset: Int
  $orderBy: [atoms_order_by!]
  $where: atoms_bool_exp
) {
  atoms_aggregate(where: $where) {
    aggregate {
      count
    }
  }
  atoms(limit: $limit, offset: $offset, order_by: $orderBy, where: $where) {
    # AtomMetadata fields
    id
    image
    label
    emoji
    type
    wallet_id
    creator {
      id
      label
      image
    }

    # AtomTxn fields
    block_number
    block_timestamp
    transaction_hash
    creator_id

    # AtomVaultDetails fields
    vault_id
    wallet_id
    vault {
      position_count
      total_shares
      current_share_price
      positions_aggregate {
        aggregate {
          count
          sum {
            shares
          }
        }
      }
      positions {
        id
        account {
          label
          id
        }
        shares
      }
    }
  }
}

You can start with this initial GetAtoms query in the Apollo Sandbox or write your own. The schema Explorer (docs tab) on the left side of the sandbox shows all available queries, mutations, and types. As you type, you'll get real-time autocompletion and documentation hints to help you build your queries. You can then click the play button to see the response and then adjust your query as you explore our data.

Need inspiration? Check out the example queries in the GraphQL API Example Queries page to get started, or jump right in and start exploring!