Skip to main content

Installation & Setup

The Intuition SDK is a comprehensive TypeScript library for building applications on the Intuition protocol. This guide covers installation, configuration, and getting your development environment ready.

Prerequisites​

  • Node.js: Version 18.x or higher
  • Package Manager: npm, pnpm, yarn, or bun
  • TypeScript (recommended): Version 5.x or higher

Auto-Generated Package Documentation​

For a complete list of 0xintuition/sdk functions and interfaces, see the Intuition SDK documentation.

For a complete list of 0xintuition/protocol functions and interfaces, see the Intuition Protocol documentation.

For a complete list of 0xintuition/graphql functions and interfaces, see the Intuition Protocol documentation.

Installation​

Install the SDK using your preferred package manager:

npm install @0xintuition/sdk viem@^2.0.0
note

The SDK requires viem@2.x as a peer dependency. Viem is a lightweight, type-safe Ethereum library that powers all blockchain operations.

Verify Installation​

Create a test file to verify everything is working:

test-install.ts
import {
  intuitionTestnet,
  getMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'

console.log('Network:', intuitionTestnet.name)
console.log('Chain ID:', intuitionTestnet.id)
console.log('MultiVault:', getMultiVaultAddressFromChainId(intuitionTestnet.id))

Run it with npx tsx test-install.ts or your preferred TypeScript runner.

Client Configuration​

The SDK uses Viem clients for blockchain interactions. You need two types:

Client TypePurposeRequired For
Public ClientRead-only operationsQuerying data, checking balances
Wallet ClientWrite operationsCreating atoms, triples, deposits

Basic Setup​

import {
  intuitionTestnet,
  getMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'
import { createPublicClient, createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

// 1. Create account from private key
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')

// 2. Create public client (for reading data)
const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: http(),
})

// 3. Create wallet client (for transactions)
const walletClient = createWalletClient({
  chain: intuitionTestnet,
  transport: http(),
  account,
})

// 4. Get contract address
const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)

Configuration Object​

Most SDK functions accept a configuration object:

import type { WriteConfig } from '@0xintuition/sdk'

const config: WriteConfig = {
  address,        // MultiVault contract address
  publicClient,   // For reading blockchain data
  walletClient,   // For sending transactions
}

Network Configuration​

The SDK supports multiple networks with built-in chain definitions.

Supported Networks​

NetworkChain IDTypeStatus
Intuition Mainnet1155Productionβœ… Active
Intuition Testnet13579Developmentβœ… Active
Base Mainnet8453Productionβœ… Active
Base Sepolia84532Developmentβœ… Active

Testnet Configuration​

import { intuitionTestnet } from '@0xintuition/sdk'
import { createPublicClient, http } from 'viem'

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

// Network details available:
// Chain ID: 13579
// Currency: tTRUST
// RPC: https://testnet.rpc.intuition.systems/http
// Explorer: https://testnet.explorer.intuition.systems

Mainnet Configuration​

import { intuitionMainnet } from '@0xintuition/sdk'
import { createPublicClient, http } from 'viem'

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

// Network details available:
// Chain ID: 1155
// Currency: TRUST
// RPC: https://rpc.intuition.systems/http
// Explorer: https://explorer.intuition.systems

Contract Addresses​

The SDK provides utilities to get contract addresses for any supported network:

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

// Get MultiVault address (most commonly used)
const multiVaultAddress = getMultiVaultAddressFromChainId(chainId)

// Get other contract addresses
const trustBonding = getContractAddressFromChainId('TrustBonding', chainId)
const wrappedTrust = getContractAddressFromChainId('WrappedTrust', chainId)

Account Options​

Private Key​

import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')

Mnemonic Phrase​

import { mnemonicToAccount } from 'viem/accounts'

const account = mnemonicToAccount(
  'your twelve word mnemonic phrase goes here'
)

Browser Wallet (MetaMask, etc.)​

import { createWalletClient, custom } from 'viem'
import { intuitionTestnet } from '@0xintuition/sdk'

const walletClient = createWalletClient({
  chain: intuitionTestnet,
  transport: custom(window.ethereum),
})

Environment Variables​

Store sensitive data in environment variables:

.env
PRIVATE_KEY=0xYOUR_PRIVATE_KEY
PINATA_API_JWT=your-pinata-jwt-token
config.ts
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const pinataApiJWT = process.env.PINATA_API_JWT

TypeScript Configuration​

For optimal TypeScript support:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"],
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Advanced Configuration​

Custom RPC Endpoint​

const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: http('https://your-custom-rpc-endpoint.com'),
})

Fallback Transports​

Configure backup RPC endpoints for reliability:

import { fallback, http } from 'viem'

const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: fallback([
    http('https://testnet.rpc.intuition.systems/http'),
    http('https://backup-rpc.example.com'),
  ]),
})

Batch Requests (Multicall)​

Enable batching for multiple read operations:

const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: http(),
  batch: {
    multicall: true,
  },
})

Complete Configuration Example​

intuition-client.ts
import {
  intuitionTestnet,
  getMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'
import type { WriteConfig } from '@0xintuition/sdk'
import {
  createPublicClient,
  createWalletClient,
  http,
  fallback,
} from 'viem'
import { privateKeyToAccount } from 'viem/accounts'

// Account
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

// Public client with fallback and batching
const publicClient = createPublicClient({
  chain: intuitionTestnet,
  transport: fallback([
    http('https://testnet.rpc.intuition.systems/http'),
    http('https://backup-rpc.example.com'),
  ]),
  batch: {
    multicall: true,
  },
})

// Wallet client
const walletClient = createWalletClient({
  chain: intuitionTestnet,
  transport: http('https://testnet.rpc.intuition.systems/http'),
  account,
})

// Contract address
const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)

// Export configuration
export const config: WriteConfig = {
  address,
  publicClient,
  walletClient,
  pinataApiJWT: process.env.PINATA_API_JWT,
}

Optional: Pinata for IPFS​

For IPFS operations (uploading metadata), you'll need a Pinata API token:

  1. Sign up at pinata.cloud
  2. Create an API key and get your JWT token
  3. Pass it in the config when using IPFS upload functions
import { createAtomFromIpfsUpload } from '@0xintuition/sdk'

const atom = await createAtomFromIpfsUpload(
  {
    walletClient,
    publicClient,
    address,
    pinataApiJWT: 'your-pinata-jwt-token',
  },
  {
    name: 'My Project',
    description: 'A blockchain project',
  }
)

Local Development​

For contributing or testing with a custom build:

git clone https://github.com/0xIntuition/intuition-ts.git
cd intuition-ts/packages/sdk
npm install
npm run build
npm link

# In your project
npm link @0xintuition/sdk

Troubleshooting​

Module Resolution Errors​

  1. Ensure viem is version ^2.0.0 or higher
  2. Check your tsconfig.json module resolution settings
  3. Clear cache and reinstall:
rm -rf node_modules package-lock.json
npm install

Type Errors​

  1. Ensure TypeScript version is 5.x or higher
  2. Update @types/node to the latest version
  3. Run npx tsc --noEmit to check for type errors

Package Information​

Next Steps​

See Also​