Skip to main content

Intuition SDK Guide

The Intuition SDK is your toolkit for building with the Intuition Protocol. Think of it as a friendly bridge between your application and Intuition's powerful knowledge graph system.

What does the SDK do?​

The SDK makes it easy to:

  • Create and manage semantic data - Build atoms (individual pieces of information) and triples (relationships between atoms)
  • Interact with the blockchain - Handle deposits, withdrawals, and smart contract interactions seamlessly
  • Query the knowledge graph - Search and retrieve data from Intuition's decentralized database
  • Build user-friendly apps - Focus on your app's features while the SDK handles the complex protocol interactions

Whether you're building a social platform, a data verification tool, or any application that needs to work with verifiable, decentralized information, the SDK provides the building blocks you need.

The Intuition SDK simplifies development with the Intuition backend systems, providing a clean TypeScript interface for creating and managing Atoms and Triples with ease.

Installation​

From NPM Registry​

Install the SDK using your preferred package manager:

npm install @0xintuition/sdk

Local Development​

For local development or testing with a custom build:

# Clone the repository
git clone https://github.com/0xIntuition/intuition-ts.git
cd intuition-ts/packages/sdk

# Install dependencies
npm install

# Build the package
npm run build

# Link locally
npm link

# In your project
npm link @0xintuition/sdk

Prerequisites​

The SDK requires viem@2.x.x to execute reads and writes. Make sure you have it installed:

npm install viem@^2.0.0

Setup​

Basic Client Configuration​

Set up your viem clients for interacting with the Intuition protocol:

import {
  getMultiVaultAddressFromChainId,
  intuitionTestnet,
} from '@0xintuition/protocol'

import {
  createPublicClient,
  createWalletClient,
  http,
  privateKeyToAccount,
} from 'viem'

export const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)

export const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: http(),
})

const account = privateKeyToAccount(
  '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
)
export const walletClient = createWalletClient({
  chain: intuitionTestnet,
  transport: http(),
  account: account,
})

Supported Networks​

The Intuition SDK supports multiple networks:

NetworkChain IDTypeStatus
Base Mainnet8453Mainnet✅ Production
Base Sepolia84532Testnet✅ Development
Ethereum Mainnet1Mainnet✅ Production
Sepolia11155111Testnet✅ Development
Arbitrum One42161Mainnet✅ Production
Arbitrum Sepolia421614Testnet✅ Development
Intuition L3 (Caldera)TBDL3 Rollup🚧 Development

The SDK automatically detects the network and uses the appropriate contract addresses via getEthMultiVaultAddressFromChainId().

Note: The Intuition L3 network (Caldera rollup) is currently in development. Access the Hub for L3 network development tools and testing.

Reading Data​

Fetching Atoms and Triples​

import { getAtomDetails, getTripleDetails } from '@0xintuition/sdk'

// Get atom data by ID
const atomData = await getAtomDetails(
  '0x57d94c116a33bb460428eced262b7ae2ec6f865e7aceef6357cec3d034e8ea21',
)

// Get triple data by ID
const tripleData = await getTripleDetails(
  '0x4957d3f442acc301ad71e73f26efd6af78647f57dacf2b3a686d91fa773fe0b6',
)

## Creating Triples

Triples connect three atoms in a subject-predicate-object relationship:

```typescript
import { createAtomFromString, createTripleStatement } from '@0xintuition/sdk'

// Create three atoms first
const atom1 = await createAtomFromString(
  { walletClient, publicClient, address },
  'atom1',
)
const atom2 = await createAtomFromString(
  { walletClient, publicClient, address },
  'atom2',
)
const atom3 = await createAtomFromString(
  { walletClient, publicClient, address },
  'atom3',
)

// Create a triple statement connecting the three atoms
const triple = await createTripleStatement(
  { walletClient, publicClient, address },
  {
    args: [atom1.state.termId, atom2.state.termId, atom3.state.termId],
    value: 1000000000000000000n, // 1 ETH in wei for deposit
  },
)

Creating Atoms​

Create Atom from String​

The simplest way to create an atom with a text label:

import { createAtomFromString } from '@0xintuition/sdk'

const data = await createAtomFromString(
  { walletClient, publicClient, address },
  'is great',
)

Create Atom from IPFS Upload​

Create an atom by uploading metadata to IPFS:

import { createAtomFromIpfsUpload } from '@0xintuition/sdk'

const data = await createAtomFromIpfsUpload(
  {
    walletClient,
    publicClient,
    address,
    pinataApiKey: 'your-pinata-api-key',
  },
  {
    url: 'https://www.intuition.systems/',
    name: 'Intuition',
    description: 'A decentralized trust protocol',
    image: 'https://example.com/image.png',
    tags: ['decentralized', 'trust', 'protocol'],
    twitter: 'https://twitter.com/intuition_systems',
    github: 'github.com/intuition-systems',
  },
)

Create a Thing​

Create an atom representing a structured object:

import { createAtomFromThing } from '@0xintuition/sdk'

const data = await createAtomFromThing(
  { walletClient, publicClient, address },
  {
    url: 'https://www.intuition.systems/',
    name: 'Intuition',
    description: 'A decentralized trust protocol',
    image: 'https://example.com/image.png',
  },
)

Create an Ethereum Account​

Create an atom representing an Ethereum account:

import { createAtomFromEthereumAccount } from '@0xintuition/sdk'

const data = await createAtomFromEthereumAccount(
  { walletClient, publicClient, address },
  {
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    chainId: 1, // Mainnet
  },
)

Batch Operations​

The SDK provides efficient batch operations for creating multiple atoms at once:

Batch Create Atoms from IPFS URIs​

import {
  batchCreateAtomsFromIpfsUris,
  getEthMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

const ethMultiVaultAddress = getEthMultiVaultAddressFromChainId(walletClient.chain.id)
const data = await batchCreateAtomsFromIpfsUris(
  { walletClient, publicClient, address: ethMultiVaultAddress },
  [
    'ipfs://bafkreib7534cszxn2c6qwoviv43sqh244yfrxomjbealjdwntd6a7atq6u',
    'ipfs://bafkreicq2d5q2d5q2d5q2d5q2d5q2d5q2d5q2d5q2d5q2d5q2d5q2d5q',
  ],
)

Batch Create Atoms from Smart Contracts​

import {
  batchCreateAtomsFromSmartContracts,
  getEthMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

const ethMultiVaultAddress = getEthMultiVaultAddressFromChainId(walletClient.chain.id)
const data = await batchCreateAtomsFromSmartContracts(
  { walletClient, publicClient, address: ethMultiVaultAddress },
  [
    '0xA0b86a33E6441b8c4C8C8C8C8C8C8C8C8C8C8C8C',
    '0xB1c97a44E7551b9d5C8C8C8C8C8C8C8C8C8C8C8C8C',
  ],
)

Batch Create Atoms from Ethereum Accounts​

import {
  batchCreateAtomsFromEthereumAccounts,
  getEthMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

const ethMultiVaultAddress = getEthMultiVaultAddressFromChainId(walletClient.chain.id)
const data = await batchCreateAtomsFromEthereumAccounts(
  { walletClient, publicClient, address: ethMultiVaultAddress },
  [
    { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', chainId: 1 },
    { address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6', chainId: 1 },
  ],
)

Batch Create Atoms from Things​

import {
  batchCreateAtomsFromThings,
  getEthMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

const ethMultiVaultAddress = getEthMultiVaultAddressFromChainId(walletClient.chain.id)
const data = await batchCreateAtomsFromThings(
  { walletClient, publicClient, address: ethMultiVaultAddress },
  [
    {
      url: 'https://www.intuition.systems/',
      name: 'Intuition',
      description: 'A decentralized trust protocol.',
      image: 'https://example.com/image.png',
    },
    {
      url: 'https://example.com/',
      name: 'Example',
      description: 'An example thing.',
      image: 'https://example.com/example.png',
    },
  ],
)

Batch Create Triple Statements​

import {
  batchCreateTripleStatements,
  getEthMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

const ethMultiVaultAddress = getEthMultiVaultAddressFromChainId(walletClient.chain.id)
const data = await batchCreateTripleStatements(
  { walletClient, publicClient, address: ethMultiVaultAddress },
  [
    { args: [atom1.state.vaultId, atom2.state.vaultId, atom3.state.vaultId] },
    { args: [atom4.state.vaultId, atom5.state.vaultId, atom6.state.vaultId] },
  ],
)

Response Data Structure​

After successfully creating a new Atom, the SDK returns a data object containing:

const data: {
    uri: string
    transactionHash: `0x${string}`;
    state: {
        creator: Address,
        termId: Hex,
        atomData: Hex,
        atomWallet: Address
    };
}

React Integration Example​

Here's a complete React component that creates an atom from structured metadata:

import * as React from 'react'

import {
  createAtomFromThing,
  getMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

import { useChainId, usePublicClient, useWalletClient } from 'wagmi'

type IntuitionButton = React.HTMLAttributes<HTMLElement>

const IntuitionButton = ({ children, className }: IntuitionButton) => {
  const chainId = useChainId()
  const publicClient = usePublicClient()
  const { data: walletClient } = useWalletClient()

  const handleClick = async () => {
    const multiVaultAddress = getMultiVaultAddressFromChainId(chainId)
    const data = await createAtomFromThing(
      { walletClient, publicClient, address: multiVaultAddress },
      {
        url: 'https://www.intuition.systems/',
        name: 'Intuition',
        description: 'A decentralized trust protocol.',
        image: 'https://example.com/image.png',
      },
    )
  }

  return <button onClick={handleClick}>Create Thing</button>
}

export { IntuitionButton }

Development​

Building the SDK​

npm run build

Running Tests​

npm test

Resources​

Contributing​

Contributions are welcome! Please see the main repository for more information on how to contribute.