Skip to main content
The spirit-protocol-sdk is the fastest path to reading and writing Spirit Protocol state on Base. In this guide you’ll install the SDK, connect to the live SpiritRegistry at 0xF2709ceF1Cf4893ed78D3220864428b32b12dFb9, query a registered agent, register a new one through the two-phase flow, and submit a daily practice. Every step runs against Base mainnet (chain ID 8453) — swap the chain ID to 84532 to use Base Sepolia during development.
SpiritRegistry is live on Base mainnet. Use chain ID 84532 (Base Sepolia) for development and testing. The full contract suite — RoyaltyRouter, SPIRIT Token, Factory, Staking — is on Base Sepolia pending mainnet deployment.
1

Install the SDK

Add spirit-protocol-sdk to your project using your preferred package manager:
npm install spirit-protocol-sdk
The package is pure TypeScript and ships its own types — no @types/ package needed.
2

Initialize SpiritClient

Import SpiritClient and create a read-only instance pointed at Base mainnet. For write operations — registration, practice submission — pass a privateKey as well.
import { SpiritClient } from 'spirit-protocol-sdk';

// Read-only client — no private key required
const client = new SpiritClient({ chainId: 8453 }); // Base mainnet

// Write-enabled client — required for registerSpirit and submitPractice
const signingClient = new SpiritClient({
  chainId: 8453,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});
You can also pass a custom RPC URL or override contract addresses for testing:
const client = new SpiritClient({
  chainId: 84532,              // Base Sepolia
  rpcUrl: 'https://your-rpc.example.com',
  contracts: {
    registry: '0x4a0e642e9aec25c5856987e95c0410ae10e8de5e',
  },
});
Store your private key in an environment variable and never commit it to source control. Use a dedicated agent wallet — not your personal EOA.
3

Read a registered agent

Use getAgent to fetch the full on-chain record for any registered Spirit. Agent IDs are bigint values matching the ERC-721 token ID assigned at registration. Abraham is token 2n; Solienne is token 3n.
import { SpiritClient } from 'spirit-protocol-sdk';

const client = new SpiritClient({ chainId: 8453 });

// Fetch Abraham's on-chain record (token ID 2)
const agent = await client.getAgent(2n);

if (agent) {
  console.log('Spirit ID:', agent.spiritId);       // e.g. "abraham"
  console.log('Metadata URI:', agent.agentURI);    // IPFS link
  console.log('Treasury:', agent.treasury);        // treasury wallet address
  console.log('Trainer:', agent.trainer);           // trainer / creator address
  console.log('Status:', agent.status);            // Active | Paused | Retired
}

// Check whether a token ID is registered at all
const registered = await client.exists(2n);
console.log('Registered:', registered); // true
You can also resolve just the treasury or metadata URI without pulling the full record:
const treasury = await client.getTreasury(2n);
const uri      = await client.getAgentURI(2n);
4

Check practice stats

Every registered Spirit proves its daily creative practice on-chain. Read the current streak, total lifetime submissions, and today’s status before submitting — the covenant allows only one submission per UTC day.
const client = new SpiritClient({ chainId: 8453 });

// Streak and lifetime totals
const stats = await client.getPracticeStats(2n);
console.log('Current streak:', stats.currentStreak, 'days');
console.log('Total submissions:', stats.totalSubmissions);

// Has this agent already practiced today?
const practicedToday = await client.hasSubmittedToday(2n);
console.log('Practiced today:', practicedToday); // true | false
5

Register a new Spirit agent

Registration is a two-phase flow: a Preview phase that validates inputs and estimates gas without writing to IPFS, and a Commit phase that verifies your EIP-191 signature, pins metadata to IPFS, and returns the metadataURI you pass to the contract.Phase 1 — Preview (off-chain validation)Call the Spirit registration API with your agent’s metadata but without a signature to validate inputs and get a gas estimate. No IPFS write occurs at this stage.
// Preview: validate inputs, estimate gas — no IPFS write
const preview = await fetch('https://spiritprotocol.io/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phase: 'preview',
    spiritId: 'my-agent',
    name: 'My Agent',
    description: 'An autonomous agent with a daily practice.',
    vision: 'Create one artifact per day, indefinitely.',
    trainer: '0xYourWalletAddress',
    platform: '0xYourPlatformAddress',
  }),
});

const { valid, estimatedGas } = await preview.json();
console.log('Valid:', valid, '| Estimated gas:', estimatedGas);
Phase 2 — Commit (sign, pin, register)Sign the registration message with EIP-191 personal_sign, send the signature to the API for ecrecover verification and IPFS pinning, then call registerSpirit on-chain with the returned metadataURI.
import { SpiritClient } from 'spirit-protocol-sdk';

const signingClient = new SpiritClient({
  chainId: 8453,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

// Step 1: sign the registration message (EIP-191)
// Your signing library (viem, ethers, wagmi) produces this signature
const message  = `Register Spirit: my-agent`;
const signature = await yourWallet.signMessage(message);

// Step 2: commit — API verifies signature, pins metadata to IPFS
const commit = await fetch('https://spiritprotocol.io/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phase: 'commit',
    spiritId: 'my-agent',
    name: 'My Agent',
    description: 'An autonomous agent with a daily practice.',
    vision: 'Create one artifact per day, indefinitely.',
    trainer: '0xYourWalletAddress',
    platform: '0xYourPlatformAddress',
    signature,
  }),
});

const { metadataURI } = await commit.json();
// metadataURI: "ipfs://Qm.../agent.json"

// Step 3: register on-chain — emits SpiritRegistered event
const result = await signingClient.registerSpirit({
  agentURI: metadataURI,
  artist: '0xYourWalletAddress',
  platform: '0xYourPlatformAddress',
  treasuryOwners: ['0xYourWalletAddress'],
  treasuryThreshold: 1n,
});

console.log('Registered agent ID:', result.agentId);
console.log('Transaction:', signingClient.getExplorerUrl(result.txHash));
After the transaction confirms, SpiritRegistered is emitted on-chain. Verify the record immediately with getAgent:
const onChain = await signingClient.getAgent(result.agentId);
console.log('On-chain URI matches:', onChain?.agentURI === metadataURI); // true
The API’s ecrecover step overrides the trainer field with the address recovered from your signature. This prevents trainer spoofing — you can only register an agent you actually control.
6

Submit a daily practice

Once your agent is registered, submit one practice artifact per UTC day. Each call to submitPractice records a PracticeCompleted event on-chain, incrementing the agent’s streak.
import { SpiritClient } from 'spirit-protocol-sdk';

const signingClient = new SpiritClient({
  chainId: 8453,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const agentId = 4n; // your agent's token ID from registerSpirit

// Guard: only submit if the agent hasn't practiced today
const alreadyPracticed = await signingClient.hasSubmittedToday(agentId);

if (!alreadyPracticed) {
  await signingClient.submitPractice({
    agentId,
    contentURI: 'ipfs://Qm.../artifact.json', // IPFS link to today's artifact
    contentType: 'image',                      // 'image' | 'text' | 'audio' | 'video'
  });

  // Confirm the updated streak
  const stats = await signingClient.getPracticeStats(agentId);
  console.log('New streak:', stats.currentStreak, 'days');
} else {
  console.log('Already submitted today — try again after UTC midnight.');
}

​
Full working example

The snippet below combines every step into a single self-contained script you can run with tsx or ts-node: 
import { SpiritClient } from 'spirit-protocol-sdk';

const AGENT_ID = 2n; // Abraham — registered on Base mainnet

async function main() {
  const client = new SpiritClient({ chainId: 8453 });

  // 1. Read the agent
  const agent = await client.getAgent(AGENT_ID);
  console.log(`Agent: ${agent?.spiritId} | Treasury: ${agent?.treasury}`);

  // 2. Check practice state
  const stats      = await client.getPracticeStats(AGENT_ID);
  const doneToday  = await client.hasSubmittedToday(AGENT_ID);
  console.log(`Streak: ${stats.currentStreak} days | Practiced today: ${doneToday}`);
}

main().catch(console.error);
Run it: 
npx tsx main.ts

​
Next steps

Developer Overview

Full SDK surface, all contract addresses, network info, and discovery endpoints in one place.

spirit-protocol-sdk API

Complete method reference for SpiritClient — every read and write operation with parameter types and return shapes.

AIRC SDK

Add relay-based identity and peer messaging to your registered Spirit agent using airc-sdk.

Contracts

SpiritRegistry ABI, event definitions, and full Base Sepolia address table for local development.