TypeScript SDK for 8004 Agent Registry on Solana.
Autonomous Agents (Clawbot, Moltbot, etc.): See
skill.mdfor the complete SDK reference designed for autonomous AI agent consumption.New here? Follow the Quickstart Guide to register your first agent in 5 minutes.
- Collect requester-driven verified feedback with
ProofPass - Register agents as NFTs on Solana blockchain
- Manage agent metadata and endpoints (MCP, A2A)
- Submit and query reputation feedback with SEAL v1 integrity verification
- Sign & verify with agent operational wallets
- OASF taxonomies support (skills & domains)
npm install 8004-solanadevnet: fully configured by default.mainnet-beta: fully configured by default.localnet: supported; set local deployedprogramIds.- See the Indexer section for the combined network + indexer config snippet.
import {
SolanaSDK,
IPFSClient,
buildRegistrationFileJson,
ServiceType,
Tag,
} from '8004-solana';
import { Keypair } from '@solana/web3.js';
const signer = Keypair.fromSecretKey(/* your key */);
const pinataJwt = 'your-pinata-jwt';
const ipfs = pinataJwt
? new IPFSClient({ pinataEnabled: true, pinataJwt })
: new IPFSClient({ url: 'http://localhost:5001' });
const sdk = new SolanaSDK({ cluster: 'mainnet-beta', signer, ipfsClient: ipfs });
// 1. Create complete collection metadata + upload (off-chain)
const collectionInput = {
name: 'CasterCorp Agents',
symbol: 'CAST',
description: 'Main collection for CasterCorp agents',
image: 'ipfs://QmCollectionImage...',
banner_image: 'ipfs://QmCollectionBanner...',
socials: {
website: 'https://castercorp.ai',
x: 'https://x.com/castercorp',
discord: 'https://discord.gg/castercorp',
},
};
const collection = await sdk.createCollection(collectionInput);
console.log('Collection CID:', collection.cid); // <- reuse this in your asset workflow
console.log('Collection URI:', collection.uri); // ipfs://<cid>
console.log('Collection Pointer:', collection.pointer); // c1:b...
// 2. Build agent metadata
const agentMeta = buildRegistrationFileJson({
name: 'My AI Agent',
description: 'Autonomous agent for task automation',
image: 'ipfs://QmAgentAvatar...',
services: [
{ type: ServiceType.MCP, value: 'https://api.example.com/mcp' },
{ type: ServiceType.A2A, value: 'https://api.example.com/a2a' },
{ type: ServiceType.OASF, value: 'https://api.example.com/oasf' },
{ type: ServiceType.SNS, value: 'castercorp.sol' },
],
skills: ['natural_language_processing/natural_language_generation/text_completion'],
domains: ['technology/software_engineering/software_engineering'],
});
// 3. Upload and register (ATOM is off by default; pass atomEnabled: true to opt in now)
const metadataUri = `ipfs://${await ipfs.addJson(agentMeta)}`;
const agent = await sdk.registerAgent(metadataUri, { collectionPointer: collection.pointer! });
console.log('Agent:', agent.asset.toBase58());
// 4. Set operational wallet
const opWallet = Keypair.generate();
await sdk.setAgentWallet(agent.asset, opWallet);
// 5. Give feedback - accepts decimal strings or raw values
await sdk.giveFeedback(agent.asset, {
value: '99.77', // Decimal string -> auto-encoded to 9977, decimals=2
tag1: Tag.uptime, // 8004 standardized tag (or free text)
tag2: Tag.day, // Time period
feedbackUri: 'ipfs://QmFeedback...',
});
// 6. Check reputation
const summary = await sdk.getSummary(agent.asset);
console.log(`Score: ${summary.averageScore}, Feedbacks: ${summary.totalFeedbacks}`);const collectionInput = {
name: 'My Collection',
symbol: 'MYCOL',
description: 'Collection metadata stored on IPFS',
image: 'ipfs://QmCollectionImage...',
banner_image: 'ipfs://QmCollectionBanner...',
socials: {
website: 'https://example.com',
x: 'https://x.com/example',
discord: 'https://discord.gg/example',
},
};
const collectionUpload = await sdk.createCollection(collectionInput);
// Returned by createCollection()
const cid = collectionUpload.cid; // e.g. Qm...
const uri = collectionUpload.uri; // ipfs://Qm...
const pointer = collectionUpload.pointer; // c1:b...
// Use `cid` / `uri` in your asset creation pipeline.Collection and parent association rules are documented in docs/COLLECTION.md.
Advanced end-to-end usage is shown in examples/collection-flow.ts.
// For setAgentWallet with browser wallets
const prepared = await sdk.prepareSetAgentWallet(agent.asset, walletPubkey);
const signature = await wallet.signMessage(prepared.message);
await prepared.complete(signature);// Sign any data with agent's operational wallet
const signed = sdk.sign(agent.asset, {
action: 'authorize',
user: 'alice',
permissions: ['read', 'write'],
});
// Returns canonical JSON:
// {
// "alg": "ed25519",
// "asset": "AgentAssetPubkey...",
// "data": { "action": "authorize", "permissions": ["read","write"], "user": "alice" },
// "issuedAt": 1705512345,
// "nonce": "randomBase58String",
// "sig": "base58Ed25519Signature...",
// "v": 1
// }
// Verify (fetches agent wallet from chain)
const isValid = await sdk.verify(signed, agent.asset);
// Verify with known public key (no RPC)
const isValid2 = await sdk.verify(signed, agent.asset, opWallet.publicKey);// Ping agent endpoints
const report = await sdk.isItAlive(agent.asset);
console.log(report.status); // 'live' | 'partially' | 'not_live'
console.log(report.liveServices, report.deadServices);import { PublicKey } from '@solana/web3.js';
const sdk = new SolanaSDK({ cluster: 'devnet' }); // No signer = read-only
const asset = new PublicKey('YourAgentAssetPubkey...');
const agent = await sdk.loadAgent(asset);
const summary = await sdk.getSummary(asset);ProofPass is the requester-driven verified feedback flow for 8004-solana.
A service opens a feedback request, then the reviewer finalizes a real giveFeedback() later.
The final feedback is still attributed to the reviewer, not to the ProofPass program.
creator must be the immutable creator recorded in the target agent's 8004 AgentAccount.
It is not just any service wallet or the current live owner after a transfer.
import { openProofPass, giveFeedbackWithProof } from '8004-solana';
const flow = await openProofPass({
connection,
creator: serviceWallet.publicKey,
reviewer: customerWallet.publicKey,
targetAgent: agent.asset,
contextRef: `request:${requestId}`,
});
const finalizeIx = await giveFeedbackWithProof({
connection,
session: flow.sessionPda,
reviewer: customerWallet.publicKey,
feedback: {
value: '42',
tag1: 'quality',
},
});See the public examples:
The feedback system supports rich metrics with 8004 standardized tags. value is required, score is optional.
// Basic feedback (feedbackUri optional, defaults to '')
await sdk.giveFeedback(agent.asset, {
value: '85',
tag1: 'starred',
});
// Revenue tracking with decimals
await sdk.giveFeedback(agent.asset, {
value: '150.00', // $150.00 -> auto-encoded to 15000, decimals=2
tag1: 'revenues',
tag2: 'week',
feedbackUri: 'ipfs://QmRevenue...',
});
// Uptime tracking
await sdk.giveFeedback(agent.asset, {
value: '99.50', // 99.50% -> auto-encoded to 9950, decimals=2
tag1: 'uptime',
tag2: 'day',
feedbackUri: 'ipfs://QmUptime...',
});revokeFeedback() now does indexer preflight by default:
- Uses signer (or
options.signer) as the feedback client. - Refuses revoke when feedback is missing for that client or already revoked.
- Auto-resolves
sealHashwhen omitted; if provided, it must match indexedsealHash.
await sdk.revokeFeedback(agent.asset, 12n); // preflight + auto sealHash
await sdk.revokeFeedback(agent.asset, 12n, sealHash, {
verifyFeedbackClient: false, // intentionally skip ownership preflight
waitForIndexerSync: false, // skip indexer sync wait
});See FEEDBACK.md for all 8004 tags and patterns.
Use Tag helpers for standard tags, or pass custom strings (max 32 bytes):
import { Tag } from '8004-solana';
// Using Tag helper
await sdk.giveFeedback(asset, {
value: '99.77',
tag1: Tag.uptime, // 'uptime'
tag2: Tag.day, // 'day'
feedbackUri: 'ipfs://QmFeedback...',
});
// Custom tags (free text)
await sdk.giveFeedback(asset, {
value: '42.5',
tag1: 'my-custom-metric',
tag2: 'hourly',
feedbackUri: 'ipfs://QmFeedback...',
});See FEEDBACK.md for the complete tag reference.
By default, registerAgent() does not initialize ATOM stats (atomEnabled: false). ATOM provides:
- Trust Tiers: Bronze → Silver → Gold → Platinum
- Quality Score: Weighted average with decay
- Sybil Detection: HyperLogLog client tracking
// Enable ATOM during registration
await sdk.registerAgent('ipfs://...', { atomEnabled: true });Or enable later after registration:
await sdk.enableAtom(asset);
await sdk.initializeAtomStats(asset);enableAtom() is one-way/irreversible for that agent (cannot be disabled later).
To permanently remove an agent Core asset:
await sdk.burnAgent(asset); // irreversible burnburnAgent() burns the Core asset only (it does not close the on-chain AgentAccount PDA).
SEAL helper methods and examples are documented in docs/METHODS.md#seal-v1-methods.
Default Solana devnet RPC works for basic operations. For production or advanced queries (getAllAgents, getAgentsByOwner), use a custom RPC.
| Provider | Free Tier | Signup |
|---|---|---|
| Helius | 100k req/month | helius.dev |
| QuickNode | 10M credits/month | quicknode.com |
| Alchemy | 300M CU/month | alchemy.com |
const sdk = new SolanaSDK({
rpcUrl: 'https://your-helius-rpc.helius.dev',
signer: yourKeypair,
});| Example | Description |
|---|---|
quick-start.ts |
Basic read/write with IPFS upload |
collection-flow.ts |
Full collection metadata + create 20 associated agent assets |
feedback-usage.ts |
Submit and read feedback |
agent-update.ts |
On-chain metadata & URI update |
transfer-agent.ts |
Transfer agent ownership (also possible via standard token wallet transfer) |
server-mode.ts |
Server/client architecture with skipSend |
proofpass.md |
Generic requester-driven ProofPass flow |
proofpass-x402.md |
Compact x402-compatible ProofPass flow |
The SDK uses the indexer for search, collection reads, sequential ids, and large reads. Default backend is GraphQL v2.
const indexed = await sdk.getAgentByAgentId(42);Built-in public endpoints:
mainnet-beta:https://8004-indexer-main.qnt.shdevnet/testnet:https://8004-indexer-dev.qnt.sh
Self-hosting:
If you upgrade a self-hosted indexer with a persisted DB, apply the pending DB migrations before restart.
- API Reference - All methods with examples
- Feedback Guide - Tags, value/decimals, advanced patterns
- ProofPass Example - Generic requester-driven verified feedback flow
- ProofPass + x402 Example - Compact x402-compatible flow
- Collection Guide - Collection pointer and parent association rules
- Quickstart - Step-by-step guide
- Costs - Transaction costs
- OASF Taxonomies - Skills & domains reference
- AI Agent Skill - SDK reference for AI agents (MCP/LLM)
- Telegram: t.me/sol8004
- X (Twitter): x.com/Quantu_AI
- 8004 Standard: eips.ethereum.org/EIPS/eip-8004
MIT