@x84-ai/sdk package provides TypeScript bindings for every instruction, account type, and utility in the x84 Solana program. It handles PDA derivation, instruction building, account fetching, event parsing, and error handling.
Installation
pnpm add @x84-ai/sdk
# Peer dependencies
pnpm add @coral-xyz/anchor @solana/web3.js @solana/spl-token
npm install @x84-ai/sdk
# Peer dependencies
npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token
yarn add @x84-ai/sdk
# Peer dependencies
yarn add @coral-xyz/anchor @solana/web3.js @solana/spl-token
pnpm add @lightprotocol/stateless.js
Entry points
The SDK has two entry points to keep the core bundle small.| Import | Purpose |
|---|---|
@x84-ai/sdk | Core SDK — instructions, types, PDA helpers, account fetchers, events, errors |
@x84-ai/sdk/settlement | Settlement — Light Protocol integration, compressed receipts, ALT management |
import { ... } from "@x84-ai/sdk"; // Core SDK
import { ... } from "@x84-ai/sdk/settlement"; // Settlement (Light Protocol)
Quick start
import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import { AnchorProvider, Program } from "@coral-xyz/anchor";
import {
X84_PROGRAM_ID,
getNetworkConfig,
findConfigPda,
findAgentPda,
registerAgent,
fetchAgentIdentity,
ServiceType,
hashTag,
} from "@x84-ai/sdk";
// 1. Setup
const connection = new Connection("https://api.devnet.solana.com");
const wallet = new NodeWallet(ownerKeypair);
const provider = new AnchorProvider(connection, wallet);
const program = new Program(idl, provider);
const config = getNetworkConfig("devnet");
// 2. Register an agent (mints an NFT)
const { instruction, asset, agentPda } = await registerAgent(program, {
owner: ownerKeypair.publicKey,
configAuthority: ownerKeypair.publicKey,
metadataUri: "https://example.com/agent.json",
metadataHash: hashBytes(metadataBuffer),
feedbackAuthority: feedbackKeypair.publicKey,
tags: ["ai-assistant", "code-review"], // auto-hashed
collection: config.collection!,
feeTreasury: config.feeTreasury!,
});
// Sign with: [ownerKeypair, asset]
// 3. Read the agent back
const agent = await fetchAgentIdentity(program, asset.publicKey);
console.log(agent.metadataUri, agent.owner.toBase58());
Constants and network config
import {
X84_PROGRAM_ID, // Program ID: X84XHMKT7xvjgVUXFNQLZLSdCEEZu2wAPrAeP4M9Hhi
MPL_CORE_PROGRAM_ID, // Metaplex Core: CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
SEEDS, // PDA seed prefixes
NETWORKS, // Per-network deployment addresses
getNetworkConfig, // Get typed config for "devnet" | "mainnet"
DEFAULT_REGISTRATION_FEE, // 50_000_000 lamports (0.05 SOL)
DEFAULT_SETTLEMENT_FEE_BPS, // 300 (3%)
MAX_SETTLEMENT_FEE_BPS, // 1000 (10%)
} from "@x84-ai/sdk";
NetworkConfig
Each deployed network exposes a typed config object viagetNetworkConfig("devnet") or getNetworkConfig("mainnet").
| Field | Description |
|---|---|
programId | x84 program address |
collection | Metaplex Core collection NFT mint |
feeTreasury | Treasury wallet for protocol fees |
tokenMint | Payment token (USDC on devnet) |
treasuryTokenAccount | Treasury’s ATA for the token mint |
facilitator | Facilitator signer for delegated settlement |
lightAlt | Settlement ALT (16 static accounts) |
PDA derivation
All PDA functions return[PublicKey, number]. The default programId is X84_PROGRAM_ID.
import {
findConfigPda, // ["config"]
findAgentPda, // ["agent", nftMint]
findServicePda, // ["service", nftMint, serviceTypeSeed]
findFeedbackPda, // ["feedback", nftMint, reviewer, nonce(8)]
findValidationRequestPda, // ["val_request", nftMint, validator, hash[0..8]]
findValidationResponsePda, // ["val_response", nftMint, validator, hash[0..8]]
findDelegationPda, // ["delegation", delegator, delegate, id(8)]
findPaymentReqPda, // ["payment_req", nftMint, serviceTypeSeed]
findReceiptPda, // ["receipt", paymentId]
findCpiAuthorityPda, // ["cpi_authority"]
} from "@x84-ai/sdk";
// Example
const [agentPda] = findAgentPda(nftMint);
const [servicePda] = findServicePda(nftMint, "a2a");
| Function | Seeds |
|---|---|
findConfigPda | "config" |
findAgentPda | "agent" + nftMint |
findServicePda | "service" + nftMint + serviceTypeSeed |
findFeedbackPda | "feedback" + nftMint + reviewer + nonce (8 bytes) |
findValidationRequestPda | "val_request" + nftMint + validator + hash first 8 bytes |
findValidationResponsePda | "val_response" + nftMint + validator + hash first 8 bytes |
findDelegationPda | "delegation" + delegator + delegate + id (8 bytes) |
findPaymentReqPda | "payment_req" + nftMint + serviceTypeSeed |
findReceiptPda | "receipt" + paymentId |
findCpiAuthorityPda | "cpi_authority" |
Account fetchers
Single account
import {
fetchProtocolConfig,
fetchAgentIdentity,
fetchAgentIdentityOrNull, // returns null if not found
fetchService,
fetchFeedbackEntry,
fetchDelegation,
fetchDelegationByPda,
fetchPaymentRequirement,
} from "@x84-ai/sdk";
const config = await fetchProtocolConfig(program);
const agent = await fetchAgentIdentity(program, nftMint);
const service = await fetchService(program, nftMint, ServiceType.A2A);
Batch fetchers
These usegetProgramAccounts with filters for efficient bulk queries.
import {
fetchAllAgents,
fetchAgentsByOwner,
fetchServicesByAgent,
fetchDelegationsByDelegate,
fetchDelegationsByAgent,
} from "@x84-ai/sdk";
const myAgents = await fetchAgentsByOwner(program, myPubkey);
const services = await fetchServicesByAgent(program, nftMint);
const delegations = await fetchDelegationsByDelegate(program, myPubkey);
Utilities
import {
hashTag, // string -> 32-byte SHA-256 hash
hashBytes, // Uint8Array -> 32-byte SHA-256 hash
stringToBytes32, // string -> 32-byte zero-padded array
zeroBytes32, // 32 zero bytes
zeroBytes64, // 64 zero bytes
randomPaymentId, // random 32-byte payment ID
randomSignature, // random 64-byte signature placeholder
} from "@x84-ai/sdk";
Error handling
The SDK provides structured error parsing for all 49 program error codes (6000-6048).import { parseX84Error, X84Error, X84ErrorCode } from "@x84-ai/sdk";
try {
await program.methods.registerAgent(...).rpc();
} catch (err) {
const x84err = parseX84Error(err);
if (x84err) {
console.log(x84err.code, x84err.message);
// e.g. 6036, "Insufficient registration fee"
}
}
Key error codes
| Code | Name | Description |
|---|---|---|
| 6005 | InvalidFeedbackScore | Must be 0-100 |
| 6010 | AgentInactive | Agent is deactivated |
| 6012 | Unauthorized | Not owner, no valid delegation |
| 6016 | DelegationExpired | Delegation past expiry |
| 6018 | InsufficientPermission | Delegation lacks required permission |
| 6028 | InsufficientPayment | Payment amount too low |
| 6029 | PaymentReplay | Payment ID already used |
| 6034 | ModulePaused | Protocol module is paused |
| 6036 | InsufficientRegistrationFee | Not enough SOL for registration |
| 6038 | FacilitatorRequired | Attestation mode needs facilitator |