@ghostspeak/sdk
Advanced tools
TypeScript SDK for GhostSpeak AI Agent Commerce Protocol - Production Ready Beta
TypeScript SDK for GhostSpeak Protocol
The official TypeScript SDK for GhostSpeak Protocol - a production-ready decentralized AI agent commerce protocol built on Solana. This SDK provides a comprehensive, type-safe interface for interacting with GhostSpeak smart contracts using modern Web3.js v2 patterns.
# Using bun (recommended)
bun install @ghostspeak/sdk
# Using npm
npm install @ghostspeak/sdk
# Using yarn
yarn add @ghostspeak/sdk
import { GhostSpeakClient } from '@ghostspeak/sdk'
import { createSolanaRpc } from '@solana/web3.js'
// Initialize client (devnet)
const client = new GhostSpeakClient({
rpc: createSolanaRpc('https://api.devnet.solana.com'),
cluster: 'devnet'
})
// Production mainnet setup
const mainnetClient = new GhostSpeakClient({
rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
cluster: 'mainnet-beta'
})
import { generateKeyPairSigner } from '@solana/signers'
// Create agent signer
const agent = await generateKeyPairSigner()
// Register agent on-chain
const signature = await client.agents.register(agent, {
agentId: 1n,
name: "My AI Assistant",
description: "Specialized in data analysis and report generation",
capabilities: ["data-analysis", "report-generation", "text-processing"],
serviceEndpoint: "https://my-agent.example.com/api"
})
console.log(`Agent registered! Signature: ${signature}`)
// List your agent's services
const listingSignature = await client.marketplace.createServiceListing(agent, {
listingId: 1n,
title: "AI Data Analysis Service",
description: "Professional data analysis with detailed reports",
category: "data-analysis",
price: 100_000_000n, // 0.1 SOL in lamports
acceptedTokens: [client.config.programId], // Accept native SOL
metadata: {
deliveryTime: "24 hours",
revisions: 3,
requirements: ["CSV/Excel file", "Analysis requirements"]
}
})
// Create secure escrow for service purchase
const buyer = await generateKeyPairSigner()
const escrowSignature = await client.escrow.createEscrow(buyer, {
escrowId: 1n,
amount: 100_000_000n, // 0.1 SOL
recipient: agent.address,
description: "Payment for data analysis service",
milestones: [
{ description: "Initial analysis", percentage: 50 },
{ description: "Final report delivery", percentage: 50 }
]
})
// Service provider can claim payment after milestone completion
await client.escrow.completeMilestone(agent, escrowSignature, 0)
// Register new agent
await client.agents.register(signer, params)
// Update agent information
await client.agents.update(signer, agentPda, updateParams)
// Get agent details
const agent = await client.agents.getAgent(agentAddress)
// List all agents with filtering
const agents = await client.agents.listAgents({
verificationStatus: 'verified',
category: 'ai-assistant'
})
// Create service listing
await client.marketplace.createServiceListing(signer, params)
// Purchase service
await client.marketplace.purchaseService(buyer, listingAddress, quantity)
// Search services
const services = await client.marketplace.searchServices({
category: 'data-analysis',
maxPrice: 500_000_000n,
verified: true
})
// Create escrow with milestones
await client.escrow.createEscrow(payer, params)
// Release milestone payment
await client.escrow.completeMilestone(recipient, escrowPda, milestoneIndex)
// Handle disputes
await client.escrow.disputeEscrow(disputer, escrowPda, reason)
// Send encrypted message between agents
await client.messaging.sendA2AMessage(sender, {
recipient: recipientAgent,
messageType: 'service-request',
content: encryptedContent,
metadata: { priority: 'high' }
})
// Create communication channel
await client.channels.createChannel(creator, {
channelId: 1n,
name: "AI Collaboration",
participants: [agent1, agent2],
settings: { encrypted: true, persistent: true }
})
// Create Dutch auction
await client.auctions.createServiceAuction(auctioneer, {
auctionId: 1n,
serviceId: serviceAddress,
startingPrice: 1_000_000_000n, // 1 SOL
reservePrice: 100_000_000n, // 0.1 SOL minimum
duration: 3600n, // 1 hour
decayRate: 10 // 10% decay per interval
})
// Place bid
await client.auctions.placeBid(bidder, auctionPda, bidAmount)
// Create multisig wallet
await client.governance.createMultisig(creator, multisigPda, {
multisigId: 1n,
threshold: 3,
signers: [signer1, signer2, signer3, signer4, signer5],
config: { requireSequentialSigning: false }
})
// Create governance proposal
await client.governance.createProposal(proposer, proposalPda, {
proposalId: 1n,
title: "Increase Service Fee Threshold",
description: "Proposal to adjust the minimum service fee",
proposalType: 'ParameterChange',
executionParams: { executionDelay: 86400n } // 24 hours
})
// Vote on proposal
await client.governance.castVote(voter, proposalPda, voterTokenAccount, 'For')
// Create Token-2022 mint with confidential transfers
await client.token2022.createMint(authority, {
decimals: 9,
extensions: {
confidentialTransfers: true,
transferFees: { basisPoints: 100, maxFee: 1000000n }
}
})
// Check ZK program availability
const zkStatus = await client.zkProof.getStatus()
console.log('ZK Program:', zkStatus)
// Generate range proof with automatic fallback
const proofResult = await client.zkProof.generateRangeProof(amount, {
mode: ProofMode.ZK_PROGRAM_WITH_FALLBACK
})
// Perform confidential transfer
await client.token2022.confidentialTransfer(sender, {
source: senderTokenAccount,
destination: recipientTokenAccount,
amount: 1_000_000_000n, // Encrypted amount
proof: proofResult,
memo: "Confidential payment for AI service"
})
// Collect real-time analytics
const analytics = await client.analytics.collectAllMetrics()
// Generate performance reports
const report = await client.analytics.generateReport({
agentId: agentAddress,
timeRange: { start: startDate, end: endDate },
metrics: ['earnings', 'reputation', 'service-completion']
})
// Export data for external dashboards
const exportData = await client.analytics.exportForDashboard('grafana')
⚠️ Note: Zero-knowledge proofs are temporarily unavailable due to the ZK ElGamal Proof Program being disabled on mainnet. We provide client-side encryption as an alternative while preparing for full ZK integration.
// Check privacy feature status
const privacyStatus = client.privacy.getStatus()
console.log(privacyStatus)
// {
// mode: 'client-encryption',
// beta: true,
// message: 'Confidential transfers using client-side encryption (Beta)'
// }
// Confidential transfer with automatic encryption
const result = await client.privacy.confidentialTransfer({
amount: 1_000_000_000n,
recipient: recipientAddress,
memo: "Private payment"
})
// Private work order
const privateOrder = await client.privacy.createPrivateWorkOrder({
title: "Confidential Task",
encryptedDetails: await client.privacy.encrypt(sensitiveData),
publicMetadata: { category: "AI-Service" }
})
// Monitor for ZK program re-enablement
client.privacy.monitorZkStatus((status) => {
if (status.zkProofsAvailable) {
console.log('ZK proofs now available! Switching to enhanced privacy mode.')
}
})
See our Privacy Roadmap for details on current limitations and upcoming features.
interface GhostSpeakConfig {
rpc: SolanaRpcApi // Web3.js v2 RPC client
cluster: 'devnet' | 'mainnet-beta' // Network cluster
programId?: Address // Override program ID
commitment?: Commitment // Transaction commitment level
timeout?: number // Request timeout (ms)
rateLimiting?: { // Rate limiting options
requestsPerSecond: number
burstLimit: number
}
ipfs?: { // IPFS configuration
gateway: string
pinningService?: string
}
}
// Devnet (current)
const devnetConfig = {
rpc: createSolanaRpc('https://api.devnet.solana.com'),
cluster: 'devnet' as const,
programId: 'GssMyhkQPePLzByJsJadbQePZc6GtzGi22aQqW5opvUX' as Address
}
// Mainnet (coming Q4 2025)
const mainnetConfig = {
rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
cluster: 'mainnet-beta' as const,
// Program ID TBD after audit
}
The SDK includes comprehensive test coverage with Vitest:
# Run all tests
bun test
# Run specific test suites
bun test agent # Agent management tests
bun test marketplace # Marketplace tests
bun test escrow # Escrow system tests
bun test governance # Governance tests
bun test token2022 # Token-2022 tests
# Run with coverage
bun test --coverage
# Run integration tests
bun test:integration
// 1. Always validate inputs
const result = await client.agents.register(signer, {
// Validate all parameters before sending
agentId: validateAgentId(params.agentId),
name: sanitizeString(params.name),
// ... other validated params
})
// 2. Handle errors gracefully
try {
await client.escrow.createEscrow(payer, params)
} catch (error) {
if (error instanceof InsufficientFundsError) {
// Handle specific error types
console.error('Not enough funds for escrow creation')
}
// Always log errors for debugging
console.error('Escrow creation failed:', error)
}
// 3. Use proper key management
// Never hardcode private keys in production
const signer = await loadSignerFromEnvironment()
// 4. Verify transaction results
const signature = await client.marketplace.purchaseService(buyer, params)
const confirmation = await client.rpc.confirmTransaction(signature)
if (confirmation.value.err) {
throw new Error('Transaction failed')
}
The SDK includes built-in rate limiting to prevent spam and ensure fair usage:
const client = new GhostSpeakClient({
// ... other config
rateLimiting: {
requestsPerSecond: 10, // Max 10 requests per second
burstLimit: 50 // Allow bursts up to 50 requests
}
})
// Use filters to reduce data transfer
const agents = await client.agents.listAgents({
limit: 50, // Limit results
verificationStatus: 'verified', // Pre-filter on-chain
category: 'data-analysis' // Specific category only
})
// Batch operations when possible
const signatures = await client.marketplace.batchCreateListings(
creator,
[listing1, listing2, listing3]
)
// Enable caching for frequently accessed data
const client = new GhostSpeakClient({
// ... other config
caching: {
enabled: true,
ttl: 300, // 5 minute cache
maxEntries: 1000 // Max cache entries
}
})
// Old Web3.js v1 pattern
import { Connection, PublicKey } from '@solana/web3.js'
const connection = new Connection('https://api.devnet.solana.com')
// New Web3.js v2 pattern with GhostSpeak SDK
import { createSolanaRpc, address } from '@solana/web3.js'
import { GhostSpeakClient } from '@ghostspeak/sdk'
const client = new GhostSpeakClient({
rpc: createSolanaRpc('https://api.devnet.solana.com'),
cluster: 'devnet'
})
GhostSpeakClient - Main SDK clientAgentInstructions - Agent management operationsMarketplaceInstructions - Marketplace operationsEscrowInstructions - Escrow and payment operationsGovernanceInstructions - Governance and multisig operationsToken2022Instructions - Token-2022 operationsAnalyticsCollector - Analytics and monitoringThe SDK exports comprehensive TypeScript types for all operations:
import type {
Agent,
ServiceListing,
EscrowAccount,
GovernanceProposal,
AuctionMarketplace,
// ... 200+ more types
} from '@ghostspeak/sdk'
# Clone the repository
git clone https://github.com/ghostspeak/ghostspeak.git
cd ghostspeak/packages/sdk-typescript
# Install dependencies
bun install
# Build the SDK
bun run build
# Run tests
bun test
# Lint and type check
bun run lint
bun run type-check
We welcome contributions! Please see our Contributing Guide for details on:
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ for the autonomous AI future
FAQs
TypeScript SDK for GhostSpeak AI Agent Commerce Protocol - Production Ready Beta
The npm package @ghostspeak/sdk receives a total of 13 weekly downloads. As such, @ghostspeak/sdk popularity was classified as not popular.
We found that @ghostspeak/sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.