Reads
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.
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:
💡 Tip: You can copy and paste the code snippet below into the sandbox above to view the results.
query GetAtoms(
$limit: Int
$offset: Int
$orderBy: [atoms_order_by!]
$where: atoms_bool_exp
) {
total: atoms_aggregate(where: $where) {
aggregate {
count
}
}
atoms(limit: $limit, offset: $offset, order_by: $orderBy, where: $where) {
# Basic metadata
term_id
data
image
label
emoji
type
wallet_id
creator {
id
label
image
}
# Transaction details
block_number
created_at
updated_at
transaction_hash
creator_id
# Vault details
term {
vaults(where: { curve_id: { _eq: "1" } }, order_by: { curve_id: asc }) {
position_count
total_shares
current_share_price
market_cap
positions_aggregate {
aggregate {
count
sum {
shares
}
}
}
positions {
id
account {
label
id
}
shares
}
}
}
# Value metadata
value {
person {
name
image
description
url
}
thing {
name
image
description
url
}
organization {
name
image
description
url
}
account {
id
label
image
}
}
}
}
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!
Query Examples
GetAtoms
The GetAtoms query is the primary way to fetch atom data from the Intuition system. It provides comprehensive information about atoms including metadata, transaction details, and vault information.
query GetAtoms(
$limit: Int
$offset: Int
$orderBy: [atoms_order_by!]
$where: atoms_bool_exp
) {
total: atoms_aggregate(where: $where) {
aggregate {
count
}
}
atoms(limit: $limit, offset: $offset, order_by: $orderBy, where: $where) {
# Basic metadata
term_id
data
image
label
emoji
type
wallet_id
creator {
id
label
image
}
# Transaction details
block_number
created_at
updated_at
transaction_hash
creator_id
# Vault details
term {
vaults(where: { curve_id: { _eq: "1" } }, order_by: { curve_id: asc }) {
position_count
total_shares
current_share_price
market_cap
positions_aggregate {
aggregate {
count
sum {
shares
}
}
}
positions {
id
account {
label
id
}
shares
}
}
}
# Value metadata
value {
person {
name
image
description
url
}
thing {
name
image
description
url
}
organization {
name
image
description
url
}
account {
id
label
image
}
}
}
}
GetAccounts
Query account information including balances and positions.
query GetAccounts($limit: Int, $offset: Int) {
accounts(limit: $limit, offset: $offset) {
id
label
image
positions {
id
shares
vault {
id
atom {
label
image
}
}
}
}
}
GetTriples
Fetch relationship triples between atoms.
query GetTriples(
$limit: Int
$offset: Int
$orderBy: [triples_order_by!]
$where: triples_bool_exp
) {
total: triples_aggregate(where: $where) {
aggregate {
count
}
}
triples(limit: $limit, offset: $offset, order_by: $orderBy, where: $where) {
term_id
counter_term_id
created_at
subject {
term_id
label
image
data
type
value {
thing {
description
url
}
person {
description
url
}
organization {
description
url
}
}
}
predicate {
term_id
label
image
data
type
}
object {
term_id
label
image
data
type
value {
thing {
description
url
}
person {
description
url
}
organization {
description
url
}
}
}
# Vault details for pro/counter positions
term {
vaults(where: { curve_id: { _eq: "2" } }) {
total_shares
current_share_price
market_cap
position_count
}
}
counter_term {
vaults(where: { curve_id: { _eq: "2" } }) {
total_shares
current_share_price
market_cap
position_count
}
}
}
}
GetPositions
Query user positions in atom vaults.
query GetPositions(
$limit: Int
$offset: Int
$orderBy: [positions_order_by!]
$where: positions_bool_exp
) {
total: positions_aggregate(where: $where) {
aggregate {
count
sum {
shares
}
}
}
positions(limit: $limit, offset: $offset, order_by: $orderBy, where: $where) {
id
created_at
updated_at
shares
account {
id
label
image
}
vault {
created_at
updated_at
term {
atom {
term_id
label
image
term {
vaults(where: { curve_id: { _eq: "1" } }) {
term_id
total_shares
current_share_price
position_count
}
}
}
triple {
term_id
subject {
term_id
label
image
}
predicate {
term_id
label
image
}
object {
term_id
label
image
}
term {
vaults(where: { curve_id: { _eq: "2" } }) {
market_cap
current_share_price
position_count
}
}
}
}
}
}
}
GetVaults
Fetch vault information including share prices and positions.
query GetVaults($limit: Int, $offset: Int) {
vaults(limit: $limit, offset: $offset) {
id
atom {
id
label
image
}
current_share_price
total_shares
position_count
positions_aggregate {
aggregate {
count
sum {
shares
}
}
}
}
}
Utilities
Search and Filtering
query SearchAtoms($query: String!, $filters: atoms_bool_exp) {
atoms(where: $filters) {
id
label
image
type
creator {
id
label
}
}
}
Pagination
query GetAtomsPaginated($first: Int, $after: String) {
atoms(first: $first, after: $after) {
edges {
node {
id
label
image
type
}
cursor
}
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
}
}
React Integration
Using the GraphQL SDK
import { useGetAtomsQuery } from '@0xintuition/graphql'
function AtomList() {
const { data, loading, error } = useGetAtomsQuery({
variables: {
limit: 10,
offset: 0
}
})
if (loading) return <div>Loading...</div>
if (error) return <div>Error: {error.message}</div>
return (
<div>
{data?.atoms.map(atom => (
<div key={atom.id}>
<h3>{atom.label}</h3>
<img src={atom.image} alt={atom.label} />
<p>Type: {atom.type}</p>
</div>
))}
</div>
)
}
Best Practices
- Use the SDK: Leverage our GraphQL SDK for type-safe queries
- Optimize Queries: Only request the fields you need
- Handle Loading States: Always show loading indicators
- Implement Error Boundaries: Catch and handle errors gracefully
- Use Pagination: Implement proper pagination for large datasets
- Cache Strategically: Use React Query's caching capabilities
For more examples and advanced patterns, check out our GraphQL SDK and Example Queries page.