Schema Reference

The Intuition GraphQL API is powered by Hasura, providing a rich set of features for querying and manipulating data.

Getting the Schema

Generate the GraphQL schema via introspection:

# Mainnet
npx get-graphql-schema https://mainnet.intuition.sh/v1/graphql > schema.graphql

# Testnet
npx get-graphql-schema https://testnet.intuition.sh/v1/graphql > schema.graphql

This schema file can be used with code generation tools to create type-safe clients.

Filtering with `where` Clauses

Use boolean expressions to filter query results:

query GetRecentPersonAtoms {
  atoms(
    where: {
      created_at: { _gte: "2024-01-01" }
      type: { _eq: Person }
    }
    limit: 10
  ) {
    term_id
    label
    created_at
  }
}

Available Operators

Equality:

_eq - Equal to
_neq - Not equal to

Comparisons:

_gt - Greater than
_gte - Greater than or equal to
_lt - Less than
_lte - Less than or equal to

Array Operations:

_in - Value in array
_nin - Value not in array

Pattern Matching:

_like - Pattern match (case-sensitive)
_ilike - Pattern match (case-insensitive)

Null Checks:

_is_null - Check if null

Boolean Logic:

_and - Logical AND
_or - Logical OR
_not - Logical NOT

Combining Filters

query ComplexFilter {
  atoms(
    where: {
      _and: [
        { type: { _eq: Person } }
        {
          _or: [
            { label: { _ilike: "%ethereum%" } }
            { label: { _ilike: "%bitcoin%" } }
          ]
        }
      ]
    }
  ) {
    term_id
    label
  }
}

Sorting with `order_by`

Sort results by one or more fields:

query GetTopAtoms {
  atoms(
    order_by: [
      { term: { total_market_cap: desc } }
      { created_at: desc }
    ]
    limit: 10
  ) {
    term_id
    label
    created_at
  }
}

Sort directions:

asc - Ascending order
desc - Descending order
asc_nulls_first - Ascending, nulls first
asc_nulls_last - Ascending, nulls last
desc_nulls_first - Descending, nulls first
desc_nulls_last - Descending, nulls last

Pagination

Offset-Based Pagination

Use limit and offset for offset-based pagination:

query GetAtomsPage($limit: Int!, $offset: Int!) {
  atoms(
    limit: $limit
    offset: $offset
    order_by: { created_at: desc }
  ) {
    term_id
    label
    created_at
  }

  atoms_aggregate {
    aggregate {
      count
    }
  }
}

Variables:

{
  "limit": 20,
  "offset": 40
}

This fetches page 3 (items 41-60) when using 20 items per page.

Best practices:

Always include order_by for consistent pagination
Fetch total count using _aggregate for pagination UI
Use reasonable limits (10-100 items per page)

Aggregations

Compute statistics without fetching all nodes:

query GetPositionStats($accountId: String!) {
  positions_aggregate(where: { account_id: { _eq: $accountId } }) {
    aggregate {
      count
      sum {
        shares
      }
      avg {
        shares
      }
      min {
        shares
      }
      max {
        shares
      }
      stddev {
        shares
      }
      variance {
        shares
      }
    }
  }
}

Available Aggregate Functions

Count Operations:

count - Total number of rows

Numeric Aggregations:

sum - Sum of values
avg - Average value
min - Minimum value
max - Maximum value

Statistical Functions:

stddev - Standard deviation
stddev_pop - Population standard deviation
stddev_samp - Sample standard deviation
variance - Variance
var_pop - Population variance
var_samp - Sample variance

Combining Aggregates with Nodes

query GetPositionsWithStats($accountId: String!, $limit: Int!) {
  stats: positions_aggregate(where: { account_id: { _eq: $accountId } }) {
    aggregate {
      count
      sum { shares }
    }
  }

  positions(
    where: { account_id: { _eq: $accountId } }
    limit: $limit
    order_by: { shares: desc }
  ) {
    id
    shares
  }
}

Relationships

Navigate the knowledge graph through nested queries:

query GetAtomWithCreator($id: String!) {
  atom(term_id: $id) {
    term_id
    label
    creator {
      id
      label
      image
    }
    term {
      vaults(where: { curve_id: { _eq: "1" } }) {
        total_shares
        current_share_price
      }
    }
  }
}

Key relationships:

Atoms → Creator (account)
Atoms → Term → Vaults
Triples → Subject/Predicate/Object (atoms)
Triples → Term → Vaults
Vaults → Positions
Positions → Account
Positions → Vault

Primary Key Lookups

Direct lookups by primary key are the most efficient:

query GetAtom($id: String!) {
  atom(term_id: $id) {  # Direct lookup by primary key
    term_id
    label
  }
}

Primary keys by entity:

atom(term_id: String!) - Single atom
triple(term_id: String!) - Single triple
account(id: String!) - Single account
vault(term_id: String!, curve_id: numeric!) - Single vault (composite key)
position(id: String!) - Single position

Distinct Values

Get distinct values for a field:

query GetDistinctAtomTypes {
  atoms(distinct_on: [type]) {
    type
  }
}

Fragments

Reuse field selections across queries:

fragment AtomBasics on atoms {
  term_id
  label
  image
  type
  creator {
    id
    label
  }
}

query GetTriple($id: String!) {
  triple(term_id: $id) {
    term_id
    subject {
      ...AtomBasics
    }
    predicate {
      ...AtomBasics
    }
    object {
      ...AtomBasics
    }
  }
}

Variables

Always use variables for dynamic values:

query GetAtomsByType($type: atom_type!, $limit: Int!) {
  atoms(
    where: { type: { _eq: $type } }
    limit: $limit
  ) {
    term_id
    label
  }
}

Variables:

{
  "type": "Person",
  "limit": 20
}

Schema Introspection

Query the schema itself:

query IntrospectTypes {
  __schema {
    types {
      name
      kind
      description
    }
  }
}

query IntrospectAtomType {
  __type(name: "atoms") {
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

Code Generation

Use the schema with code generation tools:

JavaScript/TypeScript:

GraphQL Code Generator - Generate TypeScript types and hooks
Apollo CLI - Generate types for Apollo Client

Python:

Ariadne Codegen - Generate Python types
sgqlc - Generate Python client code

Go:

gqlgen - Generate Go server and client code
genqlient - Generate Go client code

Rust:

graphql-client - Typed queries in Rust
cynic - Type-safe GraphQL client

Complete Entity Reference

The Intuition GraphQL API exposes 142 root query fields. Every table/view supports standard Hasura operations: list queries with where/order_by/limit/offset, _aggregate queries, and _stream subscriptions.

Core Entities

Entity	Primary Key	Description	Docs
`atoms`	`term_id`	Fundamental units of knowledge	Queries
`triples`	`term_id`	Subject-predicate-object relationships	Queries
`accounts`	`id`	User accounts and wallets	Queries
`terms`	`id`	Shared term data for atoms and triples (holds `total_assets`, `total_market_cap`, `type`)
`vaults`	`term_id`, `curve_id`	Bonding curve vaults for staking	Queries
`positions`	`id`	User stakes in vaults	Queries

Atom Value Types

Entity	Primary Key	Description
`atom_values`	`id`	Union of all atom value types
`persons`	`id`	Person atom values
`things`	`id`	Thing atom values
`organizations`	`id`	Organization atom values
`text_objects`	`id`	Text atom values
`json_objects`	`id`	JSON atom values
`byte_object`	`id`	Byte/binary atom values

Activity Entities

Entity	Primary Key	Description	Docs
`signals`	—	Enriched deposit/redemption events	Queries
`events`	`id`	Raw blockchain events	Queries
`deposits`	`id`	Deposit transactions	Queries
`redemptions`	`id`	Redemption transactions	Queries

Position Tracking Views

Entity	Primary Key	Description	Docs
`positions_with_value`	—	Positions enriched with PnL, redeemable value	Queries
`position_changes`	`id`	Individual position change events	Queries
`position_change_daily`	—	Daily aggregated position changes	Queries
`position_change_hourly`	—	Hourly aggregated position changes	Queries

Graph Structure Views

Entity	Primary Key	Description	Docs
`subject_predicates`	`subject_id`, `predicate_id`	Subject-predicate pair aggregates	Queries
`predicate_objects`	`predicate_id`, `object_id`	Predicate-object pair aggregates	Queries
`triple_term`	`term_id`	Triple-term aggregate stats	Queries
`triple_vault`	`term_id`, `curve_id`	Triple vault-level data	Queries

Statistics & Fees

Entity	Primary Key	Description	Docs
`stats`	`id`	Protocol-wide statistics	Queries
`statHours`	`id`	Hourly protocol stats snapshots
`fee_transfers`	`id`	Protocol fee transfer events	Queries
`protocol_fee_accruals`	`id`	Fee accruals by epoch	Queries

PnL & Leaderboard

Entity	Primary Key	Description	Docs
`pnl_leaderboard_entry`	—	Leaderboard rows (34 fields)	Queries
`pnl_leaderboard_stats`	—	Aggregate leaderboard stats	Queries
`account_pnl_rank`	—	Individual account rank/percentile	Queries

Time-Series (Continuous Aggregates)

Pre-computed at hourly, daily, weekly, and monthly granularities.

Base Entity	Intervals	Description	Docs
`share_price_change_stats_*`	hourly, daily, weekly, monthly	Share price OHLC-style stats	Queries
`signal_stats_*`	hourly, daily, weekly, monthly	Signal count and volume	Queries
`term_total_state_change_stats_*`	hourly, daily, weekly, monthly	Term market cap changes	Queries
`term_total_state_changes`	—	Raw state change events	Queries

Entity	Primary Key	Description	Docs
`share_price_changes`	—	Vault share price history	Queries
`chainlink_prices`	`id`	Chainlink oracle price data

Entity	Primary Key	Description	Docs
`books`	`id`	Book entities
`cached_images`	`url`	Cached image data with moderation scores

Cross-Chain

Entity	Primary Key	Description
`caip10`	`id`	CAIP-10 cross-chain identifier mapping

Database Functions (SQL Functions Exposed as Queries)

These functions take an args parameter with function-specific inputs and return standard Hasura-filterable results.

Function	Args	Returns	Description	Docs
`search_term`	`search: String`	`atoms[]`	Full-text search for atoms	Queries
`search_term_from_following`	`address: String`, `search: String`	`atoms[]`	Search within followed accounts	Queries
`search_term_tsvector`	`search: String`	`atoms[]`	Full-text search (tsvector variant)
`search_positions_on_subject`	`addresses: _text`, `search_fields: jsonb`	`positions[]`	Find positions on a subject	Queries
`following`	`address: String`	`accounts[]`	Accounts followed by address	Queries
`signals_from_following`	`address: String`	`signals[]`	Signals from followed accounts	Queries
`positions_from_following`	`address: String`	`positions[]`	Positions from followed accounts	Queries
`get_pnl_leaderboard`	`p_limit`, `p_offset`, `p_sort_by`, ...	`pnl_leaderboard_entry[]`	PnL leaderboard	Queries
`get_pnl_leaderboard_period`	`p_start_date`, `p_end_date`, ...	`pnl_leaderboard_entry[]`	Period-scoped leaderboard	Queries
`get_pnl_leaderboard_stats`	`p_term_id`, `p_time_filter`	`pnl_leaderboard_stats[]`	Leaderboard aggregate stats	Queries
`get_vault_leaderboard`	`p_term_id`, `p_curve_id`, ...	`pnl_leaderboard_entry[]`	Vault leaderboard	Queries
`get_vault_leaderboard_period`	`p_start_date`, `p_end_date`, ...	`pnl_leaderboard_entry[]`	Period-scoped vault leaderboard	Queries
`get_account_pnl_rank`	`p_account_id`, `p_sort_by`, ...	`account_pnl_rank[]`	Account rank + percentile	Queries

Custom Operations (Hasura Actions)

These are backed by external services (chart-api, IPFS gateway). They use camelCase naming and take a single typed input or named argument.

Operation	Type	Description	Docs
`getAccountPnlCurrent`	Query	Current account PnL snapshot	Queries
`getAccountPnlChart`	Query	Account PnL over time	Queries
`getAccountPnlRealized`	Query	Realized PnL breakdown	Queries
`getPositionPnlChart`	Query	Position-level PnL chart	Queries
`getChartJson`	Query	Chart data as JSON	Queries
`getChartRawJson`	Query	Raw chart data as JSON	Queries
`getChartSvg`	Query	Chart rendered as SVG	Queries
`getChartRawSvg`	Query	Minimal raw SVG chart	Queries
`pinThing`	Mutation	Pin Thing metadata to IPFS	Mutations
`pinPerson`	Mutation	Pin Person metadata to IPFS	Mutations
`pinOrganization`	Mutation	Pin Organization metadata to IPFS	Mutations
`uploadImage`	Mutation	Upload image (base64)	Mutations
`uploadImageFromUrl`	Mutation	Upload image from URL	Mutations
`uploadJsonToIpfs`	Mutation	Upload JSON to IPFS	Mutations

Next Steps

Query Atoms - Learn atom query patterns
Query Triples - Learn triple query patterns
Query Signals - Learn signal query patterns
Query Accounts - Learn account query patterns
PnL Queries - Track profit and loss
Leaderboard - PnL and vault leaderboards
Charts - Chart data and SVG rendering
Time-Series - Pre-computed analytics
Best Practices - Optimize your queries

Getting the Schema​

Filtering with where Clauses​

Available Operators​

Combining Filters​

Sorting with order_by​

Pagination​

Offset-Based Pagination​

Aggregations​

Available Aggregate Functions​

Combining Aggregates with Nodes​

Relationships​

Primary Key Lookups​

Distinct Values​

Fragments​

Variables​

Schema Introspection​

Code Generation​

Complete Entity Reference​

Core Entities​

Atom Value Types​

Activity Entities​

Position Tracking Views​

Graph Structure Views​

Statistics & Fees​

PnL & Leaderboard​

Time-Series (Continuous Aggregates)​

Price & Share Data​

Social​

Cross-Chain​

Database Functions (SQL Functions Exposed as Queries)​

Custom Operations (Hasura Actions)​

Next Steps​