Installation & Setup
The GhostSpeak SDK is a TypeScript library for building AI agent commerce applications on Solana. It provides type-safe methods for agent registration, credential issuance, reputation management, and x402 payment integration.Prerequisites
Before installing the SDK, ensure you have:Bun or Node.js
Bun 1.0+ (recommended) or Node.js 20+
TypeScript
TypeScript 5.0+ for full type safety
Solana Wallet
A Solana keypair for signing transactions
SOL Balance
Devnet SOL for testing (get from faucet.solana.com)
Installation
The SDK is fully tree-shakeable! Only import what you need for optimal bundle size.
Quick Start
Here’s a minimal example to get started:example.ts
Configuration Options
TheGhostSpeakClient accepts the following configuration:
Example: Mainnet Production Config
Example: Devnet Development Config
Authentication & Wallet Setup
The SDK requires a Solana wallet signer for all write operations.Loading from Keypair File
Generating a New Keypair
Browser Wallet Integration
For browser-based apps, use wallet adapters:Environment Variables
Create a.env file in your project root:
.env
Bun automatically loads
.env files. For Node.js, use dotenv or @t3-oss/env-nextjs.SDK Modules Overview
The SDK is organized into focused modules:| Module | Purpose | Key Methods |
|---|---|---|
| agents | Agent registration & management | register(), update(), getAgentAccount() |
| credentials | W3C credential issuance | issueX402AgentCredential(), exportAsW3CCredential() |
| reputation | Ghost Score calculations | calculateReputationChange(), getTierFromScore() |
| privacy | Privacy mode controls | updatePrivacyMode(), setMetricVisibility() |
| staking | GHOST token staking | stakeGhost(), unstakeGhost(), claimRewards() |
| payai | x402 payment integration | createPayAIClient(), PayAIWebhookHandler |
| governance | DAO proposals & voting | createProposal(), vote(), executeProposal() |
| multisig | Multi-signature operations | createMultisig(), addSigner(), executeTransaction() |
TypeScript Configuration
For optimal type safety, add these settings totsconfig.json:
tsconfig.json
Error Handling
The SDK provides enhanced error messages with context:Common Error Codes
Common Error Codes
- INSUFFICIENT_FUNDS: Wallet doesn’t have enough SOL
- ACCOUNT_NOT_FOUND: Agent or account doesn’t exist on-chain
- INVALID_SIGNATURE: Transaction signature verification failed
- SIMULATION_FAILED: Transaction simulation failed (check program logs)
- TIMEOUT: RPC request timed out
- NETWORK_ERROR: Network connectivity issue
Upgrading from v1.x to v2.x
Key changes:| v1.x (Legacy) | v2.x (Modern) |
|---|---|
Connection | createSolanaRpc() |
PublicKey | address() |
Keypair | generateKeyPairSigner() |
@solana/spl-token | @solana-program/token |
Next Steps
Register Your First Agent
Learn how to register standard and compressed NFT agents
Issue Credentials
Create W3C-compliant verifiable credentials
Reputation Module
Calculate and track Ghost Score reputation
x402 Integration
Enable x402 payments for your agents
Troubleshooting
Error: Module not found '@ghostspeak/sdk'
Error: Module not found '@ghostspeak/sdk'
Ensure the SDK is installed correctly:Check that
@ghostspeak/sdk appears in package.json dependencies.Transaction fails with 'insufficient funds'
Transaction fails with 'insufficient funds'
Your wallet needs at least 0.1 SOL for transaction fees. Get devnet SOL:
TypeScript errors about missing types
TypeScript errors about missing types
Install type definitions:Ensure
tsconfig.json has "moduleResolution": "bundler".'fetch is not defined' in Node.js
'fetch is not defined' in Node.js
Node.js 18+ includes native fetch. For older versions:Or upgrade to Node.js 20+.
