@synapse-sap/sdk

TypeScript SDK for the Synapse Agent Protocol (SAP v2) on Solana.

Features

8 domain modules — Agent, Feedback, Indexing, Tools, Vault, Escrow, Attestation, Ledger
4 high-level registries — Discovery, x402 Payments, Session Manager, Agent Builder
52-tool plugin adapter — drop-in for SynapseAgentKit / LangChain tooling
SapConnection — RPC-first entry point compatible with synapse-client-sdk
Typed errors — SapError, SapRpcError, SapAccountNotFoundError, etc.
Serialization — automatic PublicKey/BN → JSON-safe object conversion
17 PDA functions — deterministic, pure, memoizable
Fully typed — 17 account interfaces, 11 instruction DTOs, 38 decoded events
Dual output — CommonJS + ESM with TypeScript declarations
Subpath exports — @synapse-sap/sdk/core, @synapse-sap/sdk/types, etc.
Tree-shakeable — import only what you need
Embedded IDL — zero external workspace dependency; npm-ready
Strict TypeScript — strict, noUncheckedIndexedAccess, noUnusedLocals

Installation

# Yarn
yarn add @synapse-sap/sdk @coral-xyz/anchor @solana/web3.js

# npm
npm install @synapse-sap/sdk @coral-xyz/anchor @solana/web3.js

Peer Dependencies

Package	Version	Notes
`@coral-xyz/anchor`	`>=0.30.0`	Required
`@solana/web3.js`	`>=1.90.0`	Required
`zod`	`>=3.20.0`	Optional — only for plugin schemas

CLI — `synapse-sap`

The SDK ships with a full-featured CLI for interacting with the SAP network from your terminal.

Install the CLI

# From the monorepo
cd synapse-sap-sdk/cli
npm install
npm run build
npm link          # makes "synapse-sap" available globally

# Or install globally from npm (when published separately)
npm install -g @oobe-protocol-labs/synapse-sap-cli

Initial Setup

# Generate a .env from template
synapse-sap env init --template devnet

# Set your RPC (OOBE Protocol recommended)
# Edit .env or use config:
synapse-sap config set rpcUrl "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123"

# Generate or import a keypair
synapse-sap env keypair generate --out keys/my-agent.json
synapse-sap env keypair import ./my-existing-key.json --out keys/agent.json

# Verify everything works
synapse-sap doctor run

Usage Examples

# ─── Agent Discovery ──────────────────────────────────
synapse-sap agent list --active --protocol kamiyo
synapse-sap agent info <WALLET> --fetch-tools --fetch-endpoints
synapse-sap agent health <WALLET> --timeout 5000
synapse-sap discovery scan --limit 50 --sort reputation --output json
synapse-sap discovery validate --wallet <WALLET>

# ─── Escrow & Payments ────────────────────────────────
synapse-sap escrow open <AGENT_WALLET> \
  --deposit 100000 --max-calls 100 --token sol
synapse-sap escrow deposit <AGENT_WALLET> --amount 50000
synapse-sap escrow list
synapse-sap escrow monitor <AGENT_WALLET>

# ─── x402 Calls ──────────────────────────────────────
synapse-sap x402 headers <AGENT_WALLET> --network solana:mainnet-beta
synapse-sap x402 call <AGENT_WALLET> swap \
  --args '{"inputMint":"SOL","outputMint":"USDC","amount":1}' \
  --endpoint https://agent.example.com/x402 \
  --save
synapse-sap x402 settle <CLIENT_WALLET> --calls 5 --service "batch-result"

# ─── Tools & Manifests ────────────────────────────────
synapse-sap tools manifest generate <WALLET> --out manifest.json --include-schema
synapse-sap tools manifest validate manifest.json
synapse-sap tools typify manifest.json --out types/agent.ts
synapse-sap tools compare <WALLET_A> <WALLET_B>

# ─── Diagnostics ──────────────────────────────────────
synapse-sap doctor run --quick
synapse-sap env check
synapse-sap config show

Global Flags

Flag	Description
`--rpc <url>`	Override primary RPC (e.g. `https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_...`)
`--fallback-rpc <url>`	Override fallback RPC
`--cluster <cluster>`	`mainnet-beta` \| `devnet` \| `localnet`
`--json`	JSON output for scripting
`--silent`	Suppress log output
`--env-file <path>`	Custom `.env` file path

10 Command Groups

Group	Subcommands	Description
`agent`	`list`, `info`, `tools`, `health`, `register`	Agent lifecycle
`discovery`	`scan`, `validate`, `cache`	Network scanning
`escrow`	`open`, `deposit`, `withdraw`, `close`, `dump`, `list`, `monitor`	Escrow management
`x402`	`headers`, `call`, `sign`, `verify`, `settle`, `replay`	Payment flows
`tools`	`manifest generate/validate`, `typify`, `publish`, `compare`, `doc`	Manifest & schema
`env`	`init`, `check`, `keypair show/generate/import`	Environment setup
`config`	`show`, `set`, `edit`, `reset`, `path`	Configuration
`doctor`	`run`	8 diagnostic checks
`tmp`	`list`, `cat`, `diff`, `clean`, `archive`	Artifact management
`plugin`	`list`, `install`, `create`, `validate`	Plugin system

Full CLI reference: cli/README.md

Quick Start

Option A — Anchor Provider (classic)

import { SapClient } from "@synapse-sap/sdk";
import { AnchorProvider } from "@coral-xyz/anchor";

const provider = AnchorProvider.env();
const client = SapClient.from(provider);

// Register agent
await client.agent.register({
  name: "SwapBot",
  description: "AI-powered DEX aggregator",
  capabilities: [{ id: "jupiter:swap", description: null, protocolId: "jupiter", version: "1.0.0" }],
  pricing: [],
  protocols: ["jupiter"],
});

// Fetch agent
const agent = await client.agent.fetch();
console.log(agent.name, agent.isActive);

Option B — RPC URL + Keypair (synapse-client-sdk compatible)

import { SapConnection } from "@synapse-sap/sdk";
import { Keypair } from "@solana/web3.js";

// One-liner (OOBE Protocol RPC):
const { client } = SapConnection.fromKeypair(
  "https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123",
  Keypair.generate(),
);

// Or step-by-step:
const conn = SapConnection.mainnet("https://us-1-mainnet.oobeprotocol.ai/rpc?api_key=sk_example123");
const client = conn.fromKeypair(myKeypair);

// Use exactly the same API:
await client.agent.register({ ... });

Option C — Fluent Builder

import { SapClient } from "@synapse-sap/sdk";

const client = SapClient.from(provider);

await client.builder
  .agent("SwapBot")
  .description("AI-powered swap agent")
  .x402Endpoint("https://api.example.com/x402")
  .addCapability("jupiter:swap", { protocol: "jupiter" })
  .addPricingTier({
    tierId: "standard",
    pricePerCall: 1000,
    rateLimit: 60,
  })
  .register();

Architecture

Directory Structure

src/
├── index.ts              # Root barrel export
│
├── core/                 # Client & connection infrastructure
│   ├── client.ts         # SapClient — Anchor program wrapper
│   ├── connection.ts     # SapConnection — RPC factory (synapse-client-sdk compat)
│   └── index.ts
│
├── types/                # On-chain type mirrors
│   ├── enums.ts          # Anchor enum variant objects
│   ├── common.ts         # Shared structs (Capability, PricingTier, …)
│   ├── accounts.ts       # 17 account data interfaces
│   ├── instructions.ts   # 11 instruction arg DTOs + helpers
│   └── index.ts
│
├── constants/            # Protocol constants
│   ├── programs.ts       # Network-specific program IDs
│   ├── seeds.ts          # 20 PDA seed prefixes
│   ├── limits.ts         # Size constraints, versions
│   └── index.ts
│
├── pda/                  # PDA derivation functions
│   └── index.ts          # 17 derive* functions
│
├── events/               # Event parsing
│   └── index.ts          # EventParser + 38 event types
│
├── errors/               # Typed SDK error classes
│   └── index.ts          # SapError hierarchy
│
├── utils/                # Shared utilities
│   ├── hash.ts           # sha256, hashToArray
│   ├── validation.ts     # assert
│   ├── serialization.ts  # serializeAccount, serializeValue
│   └── index.ts
│
├── modules/              # Low-level instruction wrappers
│   ├── base.ts           # BaseModule abstract class
│   ├── agent.ts          # Identity, reputation, lifecycle
│   ├── feedback.ts       # Trustless reviews
│   ├── indexing.ts       # Discovery indexes
│   ├── tools.ts          # Tool schema registry
│   ├── vault.ts          # Encrypted memory vault
│   ├── escrow.ts         # x402 micropayments
│   ├── attestation.ts    # Web-of-trust vouching
│   ├── ledger.ts         # Ring-buffer memory
│   └── index.ts
│
├── registries/           # High-level abstractions
│   ├── discovery.ts      # DiscoveryRegistry — findAgents*, profiles
│   ├── x402.ts           # X402Registry — pricing, headers, settlement
│   ├── session.ts        # SessionManager — vault+session+ledger lifecycle
│   ├── builder.ts        # AgentBuilder — fluent registration
│   └── index.ts
│
├── plugin/               # SynapseAgentKit adapter (52 tools)
│   ├── index.ts          # createSAPPlugin factory
│   ├── protocols.ts      # 8 protocol method registries
│   └── schemas.ts        # Zod schemas for LLM tool validation
│
└── idl/                  # Embedded Anchor IDL
    ├── index.ts          # SAP_IDL, IDL_PROGRAM_ADDRESS
    └── synapse_agent_sap.json  # 58 ix, 17 accounts, 38 events

SapClient Access Tree

SapClient
│
│ Modules (low-level, 1:1 with program instructions):
├── .agent          → AgentModule        (identity, reputation, lifecycle)
├── .feedback       → FeedbackModule     (trustless reviews)
├── .indexing       → IndexingModule     (capability/protocol/category indexes)
├── .tools          → ToolsModule        (tool schemas, checkpoints)
├── .vault          → VaultModule        (encrypted memory, delegation)
├── .escrow         → EscrowModule       (x402 micropayments, batch settle)
├── .attestation    → AttestationModule  (web-of-trust vouching)
├── .ledger         → LedgerModule       (ring buffer, sealed pages)
├── .events         → EventParser        (decoded TX-log events)
│
│ Registries (high-level, cross-module aggregation):
├── .discovery      → DiscoveryRegistry  (findAgents*, profiles, network overview)
├── .x402           → X402Registry       (pricing, headers, settlement lifecycle)
├── .session        → SessionManager     (vault → session → ledger lifecycle)
└── .builder        → AgentBuilder       (fluent registration + tools)

All module and registry properties are lazily instantiated (created on first access).

Core — Client & Connection

SapClient

The primary entry point. Wraps an Anchor Program and exposes domain modules.

import { SapClient } from "@synapse-sap/sdk";

// From AnchorProvider (auto-loads embedded IDL)
const client = SapClient.from(provider);

// From an existing Program instance
const client = SapClient.fromProgram(program);

// With custom program ID
const client = SapClient.from(provider, customProgramId);

// Access properties
client.program;       // Anchor Program instance
client.walletPubkey;  // Wallet public key

SapConnection

RPC-first factory. Creates SapClient instances from an RPC URL — no Anchor boilerplate. Resolves the correct program ID automatically based on cluster.

import { SapConnection } from "@synapse-sap/sdk";

// ─── Cluster shortcuts ───
const conn = SapConnection.devnet();
const conn = SapConnection.mainnet("https://my-rpc.com");
const conn = SapConnection.localnet();

// ─── Custom config ───
const conn = new SapConnection({
  rpcUrl: "https://my-rpc-provider.com",
  cluster: "mainnet-beta",
  commitment: "confirmed",
  wsUrl: "wss://my-rpc-provider.com/ws",
});

// ─── Create client ───
const client = conn.fromKeypair(keypair);
const client = conn.createClient(wallet);   // Anchor Wallet

// ─── One-liner with client attached ───
const { client, connection, cluster, programId } = SapConnection.fromKeypair(
  "https://api.devnet.solana.com",
  keypair,
);

// ─── Utility methods ───
await conn.airdrop(pubkey, 2);               // 2 SOL (devnet/localnet)
const balance = await conn.getBalanceSol(pubkey); // SOL balance

Modules (Low-Level)

Each module wraps one protocol domain. All methods return TransactionSignature (the TX hash) unless documented otherwise.

Agent

// Register
await client.agent.register({
  name: "Bot",
  description: "AI agent",
  capabilities: [{ id: "swap", description: null, protocolId: "jupiter", version: "1.0.0" }],
  pricing: [],
  protocols: ["jupiter"],
});

// Update metadata
await client.agent.update({ name: "BotV2" });

// Report metrics
await client.agent.reportCalls(42);
await client.agent.updateReputation(150, 9950);  // 150ms latency, 99.50% uptime

// Lifecycle
await client.agent.deactivate();
await client.agent.reactivate();
await client.agent.close();

// Fetch
const agent = await client.agent.fetch(walletPubkey);
const stats = await client.agent.fetchStats(agentPda);
const registry = await client.agent.fetchGlobalRegistry();

Vault (Encrypted Memory)

// Init vault
await client.vault.initVault(Array.from(nonce));

// Open session
await client.vault.openSession(Array.from(sessionHash));

// Inscribe encrypted data (zero rent — written to TX log)
await client.vault.inscribe({
  sequence: 0,
  encryptedData: ciphertext,
  nonce: nonce,
  contentHash: hash,
  totalFragments: 1,
  fragmentIndex: 0,
  compression: 0,
  epochIndex: 0,
});

// Delegation (hot wallet)
await client.vault.addDelegate(hotWallet, 0b111, expiresAt);
await client.vault.revokeDelegate(hotWallet);

// Close
await client.vault.closeSession(vaultPda, sessionPda);
await client.vault.closeVault();

Escrow (x402 Micropayments)

// Create SOL escrow
await client.escrow.create(agentWallet, {
  pricePerCall: new BN(1_000_000),
  maxCalls: new BN(100),
  initialDeposit: new BN(100_000_000),
  expiresAt: new BN(0),
  volumeCurve: [],
  tokenMint: null,
  tokenDecimals: 9,
});

// Deposit
await client.escrow.deposit(agentWallet, new BN(50_000_000));

// Agent settles calls
await client.escrow.settle(depositorWallet, 10, serviceHash);

// Batch settlement (up to 10 per TX, SDK auto-sizes CU since v0.12.5)
await client.escrow.settleBatch(depositorWallet, [
  { callsToSettle: new BN(5), serviceHash: hash1 },
  { callsToSettle: new BN(3), serviceHash: hash2 },
]);

// Withdraw remaining
await client.escrow.withdraw(agentWallet, new BN(10_000_000));

Ledger (Ring Buffer Memory)

// Init ledger (~0.032 SOL rent)
await client.ledger.init(sessionPda);

// Write entries (TX fee only, zero additional rent)
await client.ledger.write(sessionPda, data, contentHash);

// Seal current buffer to permanent page (~0.031 SOL)
await client.ledger.seal(sessionPda);

// Read
const ledger = await client.ledger.fetchLedger(sessionPda);
const page = await client.ledger.fetchPage(ledgerPda, 0);
const entries = client.ledger.decodeRingBuffer(ledgerData.ringBuffer);

// Close
await client.ledger.close(sessionPda);

Feedback, Attestation, Tools, Indexing

// ── Feedback ──
await client.feedback.give(agentWallet, { score: 5, tag: "fast", commentHash: null });
await client.feedback.update(agentWallet, { newScore: 4, newTag: null, commentHash: null });
await client.feedback.revoke(agentWallet);

// ── Attestation ──
await client.attestation.create(agentWallet, {
  attestationType: 1,
  metadataHash: [...hashBytes],
  expiresAt: new BN(Date.now() / 1000 + 86400 * 365),
});
await client.attestation.revoke(agentWallet);

// ── Tools ──
await client.tools.publishByName("swap", "jupiter", "Execute swap", input, output, 1, 0, 3, 2, false);
await client.tools.inscribeSchema("swap", { schemaType: 0, schemaData, schemaHash, compression: 0 });
await client.tools.update("swap", { httpMethod: 1, category: null, ... });

// ── Indexing ──
await client.indexing.initCapabilityIndex("jupiter:swap");
await client.indexing.addToCapabilityIndex("jupiter:swap");
await client.indexing.initProtocolIndex("jupiter");
await client.indexing.addToProtocolIndex("jupiter");

Registries (High-Level)

Registries provide cross-module orchestration with developer-friendly APIs.

DiscoveryRegistry

// Find agents by protocol
const agents = await client.discovery.findAgentsByProtocol("jupiter");

// Find by capability
const swappers = await client.discovery.findAgentsByCapability("jupiter:swap");

// Get full agent profile
const profile = await client.discovery.getAgentProfile(agentWallet);
// → { agent, stats, tools, feedback, attestations }

// Find tools by category
const tools = await client.discovery.findToolsByCategory("swap");

// Network overview
const overview = await client.discovery.getNetworkOverview();
// → { totalAgents, activeAgents, totalTools, protocols, categories }

X402Registry

// Prepare payment context
const ctx = await client.x402.preparePayment(agentWallet, {
  tierId: "standard",
  maxCalls: 100,
  initialDeposit: new BN(100_000_000),
});

// Build HTTP headers (for x402 protocol)
const headers = client.x402.buildPaymentHeaders(ctx);
// → { "X-402-Token": "...", "X-402-Agent": "...", ... }

// Estimate costs
const cost = await client.x402.estimateCost(agentWallet, 50);
// → { totalLamports, perCallLamports, tierId }

// Settle
const receipt = await client.x402.settle(depositor, 5, serviceData);

// Batch settle
const results = await client.x402.batchSettle(depositor, settlements);

// Check balance
const balance = await client.x402.getBalance(agentWallet, depositorWallet);

SessionManager

Manages the full vault → session → ledger lifecycle in one API:

// Start a session (inits vault + opens session + inits ledger)
const ctx = await client.session.start("conversation-123");
// → { vaultPda, sessionPda, ledgerPda, sessionHash }

// Write data
const result = await client.session.write(ctx, "Hello from agent");
// → { txSignature, sequence }

// Read latest entries
const messages = await client.session.readLatest(ctx);
// → RingBufferEntry[]

// Seal to permanent storage
const seal = await client.session.seal(ctx);
// → { txSignature, pageIndex }

// Get session status
const status = await client.session.getStatus(ctx);
// → { isOpen, totalWrites, sealedPages, ringBufferUsage }

// End session
await client.session.end(ctx);

AgentBuilder

Fluent builder for one-shot agent registration with tools:

const result = await client.builder
  .agent("SwapBot")
  .description("AI-powered DEX aggregator using Jupiter")
  .x402Endpoint("https://api.mybot.com/x402")
  .addCapability("jupiter:swap", {
    protocol: "jupiter",
    description: "Execute token swaps",
  })
  .addCapability("jupiter:quote", {
    protocol: "jupiter",
    description: "Get swap quotes",
  })
  .addPricingTier({
    tierId: "standard",
    pricePerCall: 1000,
    rateLimit: 60,
    tokenType: "sol",
    settlementMode: "x402",
  })
  .addTool({
    name: "swap",
    protocolId: "jupiter",
    description: "Execute a token swap",
    category: "swap",
    httpMethod: "post",
    paramsCount: 3,
    requiredParams: 2,
  })
  .registerWithTools();
// → { agentTx, toolTxs: string[] }

Plugin (SynapseAgentKit)

The SDK ships a 52-tool plugin that integrates with SynapseAgentKit and LangChain-compatible AI agent frameworks:

import { createSAPPlugin } from "@synapse-sap/sdk/plugin";

// Create plugin
const sapPlugin = createSAPPlugin({ provider });

// Use with SynapseAgentKit
const kit = new SynapseAgentKit({ rpcUrl })
  .use(sapPlugin);

const tools = kit.getTools(); // → 52 LangChain StructuredTool instances

8 Protocol Domains × Tools:

Protocol	Tools
`sap-agent`	registerAgent, updateAgent, deactivateAgent, reactivateAgent, reportCalls, updateReputation, fetchAgent, fetchGlobalRegistry
`sap-feedback`	giveFeedback, updateFeedback, revokeFeedback, fetchFeedback
`sap-attestation`	createAttestation, revokeAttestation, fetchAttestation
`sap-escrow`	createEscrow, depositEscrow, settleEscrow, withdrawEscrow, batchSettle, fetchEscrow
`sap-tools`	publishToolByName, inscribeToolSchema, updateTool, deactivateTool, reactivateTool, reportInvocations, fetchTool
`sap-vault`	initVault, openSession, inscribeMemory, closeSession, closeVault, rotateNonce, addDelegate, revokeDelegate, fetchVault, fetchSession
`sap-indexing`	initCapabilityIndex, addToCapabilityIndex, removeFromCapabilityIndex, initProtocolIndex, addToProtocolIndex, removeFromProtocolIndex, fetchCapabilityIndex, fetchProtocolIndex
`sap-ledger`	initLedger, writeLedger, sealLedger, closeLedger, fetchLedger, fetchLedgerPage

PDA Derivation

All 17 PDA functions are pure (no RPC calls) and return [PublicKey, bump]:

import {
  deriveAgent,
  deriveVault,
  deriveSession,
  deriveEscrow,
  deriveTool,
  deriveLedger,
  deriveAttestation,
} from "@synapse-sap/sdk/pda";

const [agentPda, bump]  = deriveAgent(walletPubkey);
const [vaultPda]        = deriveVault(agentPda);
const [sessionPda]      = deriveSession(vaultPda, sessionHashBytes);
const [escrowPda]       = deriveEscrow(agentPda, depositorPubkey);
const [toolPda]         = deriveTool(agentPda, toolNameHash);
const [ledgerPda]       = deriveLedger(sessionPda);
const [attestPda]       = deriveAttestation(agentPda, attesterPubkey);

Full list: deriveGlobalRegistry, deriveAgent, deriveAgentStats, deriveFeedback, deriveCapabilityIndex, deriveProtocolIndex, deriveToolCategoryIndex, deriveVault, deriveSession, deriveEpochPage, deriveVaultDelegate, deriveCheckpoint, deriveTool, deriveEscrow, deriveAttestation, deriveLedger, deriveLedgerPage

Events

Decode SAP events from transaction logs:

import { EventParser } from "@synapse-sap/sdk";

// Parse
const events = client.events.parseLogs(txLogs);

// Filter
const inscriptions = client.events.filterByName(events, "MemoryInscribedEvent");
const payments     = client.events.filterByName(events, "PaymentSettledEvent");

// 38 event types available (see API Reference)

Error Handling

The SDK provides a typed error hierarchy for precise error handling:

import {
  SapError,
  SapRpcError,
  SapAccountNotFoundError,
  SapValidationError,
  SapTimeoutError,
  SapPermissionError,
} from "@synapse-sap/sdk";

try {
  const agent = await client.agent.fetch();
} catch (err) {
  if (err instanceof SapAccountNotFoundError) {
    // Account doesn't exist on-chain
    console.log(`${err.accountType} not found: ${err.address}`);
  } else if (err instanceof SapRpcError) {
    // Anchor / RPC error with code and logs
    console.error(`RPC error ${err.rpcCode}:`, err.logs);
  } else if (err instanceof SapValidationError) {
    // SDK-side validation failed
    console.error(`Invalid ${err.field}:`, err.message);
  } else if (err instanceof SapTimeoutError) {
    // Transaction confirmation timeout
    console.error(`Timeout after ${err.timeoutMs}ms`);
  } else if (err instanceof SapPermissionError) {
    // Missing authority / delegate permission
    console.error(err.message);
  } else if (err instanceof SapError) {
    // Catch-all for any SAP SDK error
    console.error(`[${err.code}]`, err.message);
  }
}

// Wrapping Anchor errors
try {
  await program.methods.registerAgent(...).rpc();
} catch (e) {
  throw SapRpcError.fromAnchor(e); // extracts code + logs
}

Utilities

import { sha256, hashToArray, assert, serializeAccount, serializeValue } from "@synapse-sap/sdk";

// ── Hashing ──
const hash = sha256("jupiter:swap");        // Uint8Array (32 bytes)
const arr  = hashToArray(hash);             // number[] for Anchor args

// ── Assertion ──
assert(score >= 1 && score <= 5, "Score must be 1–5"); // throws RangeError

// ── Serialization (PublicKey/BN → JSON-safe) ──
const raw = await program.account.agent.fetch(pda);
const json = serializeAccount(raw);
// { authority: "GBL...", totalCalls: "42", isActive: true }

const val = serializeValue(somePublicKey);  // → "base58string"
const val = serializeValue(new BN(1000));   // → "1000"

Types

Every on-chain type is mirrored in TypeScript:

import type {
  // Account data
  AgentAccountData,
  EscrowAccountData,
  MemoryVaultData,
  ToolDescriptorData,

  // Instruction args
  RegisterAgentArgs,
  CreateEscrowArgs,
  InscribeMemoryArgs,

  // Helper types
  Capability,
  PricingTier,
  Settlement,
  VolumeCurveBreakpoint,
} from "@synapse-sap/sdk/types";

import {
  TokenType,          // { sol: {}, usdc: {}, spl: {} }
  SettlementMode,     // { instant: {}, escrow: {}, batched: {}, x402: {} }
  ToolCategory,       // { swap: {}, lend: {}, stake: {}, ... }
  DelegatePermission, // READ, WRITE, ADMIN bit flags
  SchemaType,         // INPUT, OUTPUT, DESCRIPTION
  CompressionType,    // NONE, DEFLATE, GZIP, BROTLI
} from "@synapse-sap/sdk/types";

Constants

import {
  SAP_PROGRAM_ADDRESS,       // "SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ"
  SAP_PROGRAM_ID,            // PublicKey (= devnet for now)
  MAINNET_SAP_PROGRAM_ID,    // PublicKey
  DEVNET_SAP_PROGRAM_ID,     // PublicKey
  LOCALNET_SAP_PROGRAM_ID,   // PublicKey
  SEEDS,                     // { agent: "agent", vault: "vault", ... } (20 seeds)
  LIMITS,                    // { maxNameLen: 64, maxCapabilities: 10, ... } (23 limits)
  AGENT_VERSION,             // 2
  VAULT_PROTOCOL_VERSION,    // 2
  TOOL_CATEGORY_VALUES,      // { swap: 0, lend: 1, ... }
  HTTP_METHOD_VALUES,        // { get: 0, post: 1, ... }
} from "@synapse-sap/sdk/constants";

Deep Imports

Import individual packages for smaller bundles:

// Core
import { SapClient, SapConnection } from "@synapse-sap/sdk/core";

// Individual modules
import { AgentModule } from "@synapse-sap/sdk/agent";
import { EscrowModule } from "@synapse-sap/sdk/escrow";

// Types only (zero runtime cost)
import type { AgentAccountData } from "@synapse-sap/sdk/types";
import type { SapCluster } from "@synapse-sap/sdk/core";

// PDA derivation
import { deriveAgent, deriveEscrow } from "@synapse-sap/sdk/pda";

// Constants
import { SEEDS, LIMITS } from "@synapse-sap/sdk/constants";

// Events
import { EventParser } from "@synapse-sap/sdk/events";

// Errors
import { SapError, SapRpcError } from "@synapse-sap/sdk/errors";

// Utilities
import { sha256, serializeAccount } from "@synapse-sap/sdk/utils";

// IDL
import { SAP_IDL } from "@synapse-sap/sdk/idl";

// Plugin
import { createSAPPlugin } from "@synapse-sap/sdk/plugin";

// Registries
import { DiscoveryRegistry } from "@synapse-sap/sdk/registries/discovery";
import { X402Registry } from "@synapse-sap/sdk/registries/x402";
import { SessionManager } from "@synapse-sap/sdk/registries/session";
import { AgentBuilder } from "@synapse-sap/sdk/registries/builder";

API Reference

Accounts (17 types)

Account	Description
`AgentAccountData`	Agent identity, capabilities, pricing, protocols
`AgentStatsData`	Call count, latency, uptime metrics
`GlobalRegistryData`	Protocol-wide agent counter + authority
`FeedbackAccountData`	Single reviewer's feedback for an agent
`CapabilityIndexData`	List of agents with a given capability
`ProtocolIndexData`	List of agents supporting a protocol
`ToolCategoryIndexData`	List of tools in a category
`ToolDescriptorData`	Tool schema, metadata, invocation stats
`SessionCheckpointData`	Session checkpoint for recovery
`MemoryVaultData`	Encrypted vault metadata + encryption nonce
`SessionLedgerData`	Session within a vault
`EpochPageData`	Finalized epoch page of inscriptions
`VaultDelegateData`	Delegate permissions + expiry
`EscrowAccountData`	x402 escrow balance + settlement state
`AgentAttestationData`	Attestation metadata + expiry
`MemoryLedgerData`	Ring-buffer ledger metadata
`LedgerPageData`	Sealed ledger page content

Events (38 types)

RegisteredEvent · UpdatedEvent · DeactivatedEvent · ReactivatedEvent · ClosedEvent · FeedbackEvent · FeedbackUpdatedEvent · FeedbackRevokedEvent · ReputationUpdatedEvent · CallsReportedEvent · VaultInitializedEvent · SessionOpenedEvent · MemoryInscribedEvent · EpochOpenedEvent · SessionClosedEvent · VaultClosedEvent · SessionPdaClosedEvent · EpochPageClosedEvent · VaultNonceRotatedEvent · DelegateAddedEvent · DelegateRevokedEvent · ToolPublishedEvent · ToolSchemaInscribedEvent · ToolUpdatedEvent · ToolDeactivatedEvent · ToolReactivatedEvent · ToolClosedEvent · ToolInvocationReportedEvent · CheckpointCreatedEvent · EscrowCreatedEvent · EscrowDepositedEvent · PaymentSettledEvent · EscrowWithdrawnEvent · BatchSettledEvent · AttestationCreatedEvent · AttestationRevokedEvent · LedgerEntryEvent · LedgerSealedEvent

Enum Constants

Enum	Variants
`TokenType`	`sol`, `usdc`, `spl`
`PluginType`	`native`, `wasm`, `external`
`SettlementMode`	`instant`, `escrow`, `batched`, `x402`
`ToolHttpMethod`	`get`, `post`, `put`, `delete`, `compound`
`ToolCategory`	`swap`, `lend`, `stake`, `nft`, `payment`, `data`, `governance`, `bridge`, `analytics`, `custom`
`DelegatePermission`	`READ` (1), `WRITE` (2), `ADMIN` (4)
`SchemaType`	`INPUT` (0), `OUTPUT` (1), `DESCRIPTION` (2)
`CompressionType`	`NONE` (0), `DEFLATE` (1), `GZIP` (2), `BROTLI` (3)

Development

yarn install        # Install dependencies
yarn typecheck      # Type-check (strict mode)
yarn build          # Build CJS + ESM + declarations
yarn clean          # Remove dist/
yarn sync-idl       # Copy latest IDL from anchor build

Building for Developers

The SDK outputs three artifacts:

Output	Path	Config
ESM	`dist/esm/`	`tsconfig.esm.json`
CJS	`dist/cjs/`	`tsconfig.cjs.json`
Types	`dist/types/`	`tsconfig.json --emitDeclarationOnly`

See CONTRIBUTING.md for full development guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
cli		cli
docs		docs
idl		idl
node_modules		node_modules
scripts		scripts
skills		skills
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
add-jsdoc.js		add-jsdoc.js
bnjs.d.ts		bnjs.d.ts
generate-jsdocs.js		generate-jsdocs.js
onchain-idl-audit.js		onchain-idl-audit.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

@synapse-sap/sdk

Table of Contents

Features

Installation

Peer Dependencies

CLI — synapse-sap

Install the CLI

Initial Setup

Usage Examples

Global Flags

10 Command Groups

Quick Start

Option A — Anchor Provider (classic)

Option B — RPC URL + Keypair (synapse-client-sdk compatible)

Option C — Fluent Builder

Architecture

Directory Structure

SapClient Access Tree

Core — Client & Connection

SapClient

SapConnection

Modules (Low-Level)

Agent

Vault (Encrypted Memory)

Escrow (x402 Micropayments)

Ledger (Ring Buffer Memory)

Feedback, Attestation, Tools, Indexing

Registries (High-Level)

DiscoveryRegistry

X402Registry

SessionManager

AgentBuilder

Plugin (SynapseAgentKit)

PDA Derivation

Events

Error Handling

Utilities

Types

Constants

Deep Imports

API Reference

Accounts (17 types)

Events (38 types)

Enum Constants

Development

Building for Developers

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

CLI — `synapse-sap`

Packages