SDK Integration

Overview

The Agentic Wallet SDK provides a fully-typed TypeScript client for interacting with all platform capabilities. It wraps the REST API with convenient methods and handles authentication, error normalization, and response parsing.

Installation

The SDK is available as @agentic-wallet/sdk in the monorepo.

Install in Monorepo

npm install

For external projects:

# From the repository root
cd packages/sdk
npm pack
# Install the generated tarball in your project

Quick Start

Basic Usage

import { createAgenticWalletClient } from '@agentic-wallet/sdk';

const client = createAgenticWalletClient('http://localhost:3000', {
  apiKey: 'dev-api-key',
  tenantId: 'my-tenant', // optional
});

// Create a wallet
const wallet = await client.wallet.create({ label: 'trading-bot' });

// Get balance
const balance = await client.wallet.getBalance(wallet.walletId);
console.log(`Balance: ${balance.sol} SOL`);

// Create an agent
const agent = await client.agent.create({
  name: 'arb-bot',
  walletId: wallet.walletId,
  executionMode: 'autonomous',
  allowedIntents: ['transfer_sol', 'swap', 'query_balance'],
});

// Execute an intent
const result = await client.agent.execute(agent.agentId, {
  type: 'query_balance',
  protocol: 'system-program',
  intent: {},
  gasless: false,
});

Client Creation

Create a client instance with authentication and configuration.

Client Configuration

const client = createAgenticWalletClient(
  baseUrl: string,
  options?: {
    apiKey?: string;
    tenantId?: string;
    headers?: HeadersInit;
  }
);

Parameters:

baseUrl: API Gateway URL (e.g., http://localhost:3000)
options.apiKey: API key for authentication (sent as x-api-key header)
options.tenantId: Optional tenant identifier (sent as x-tenant-id header)
options.headers: Additional custom headers

Example:

const client = createAgenticWalletClient('https://api.example.com', {
  apiKey: process.env.API_KEY,
  tenantId: process.env.TENANT_ID,
  headers: {
    'x-custom-header': 'value',
  },
});

SDK Modules

The SDK client exposes the following modules:

wallet

Wallet creation, balance, tokens, signing

policy

Policy creation, evaluation, versioning

transaction

Transaction lifecycle, proofs, approvals

agent

Agent management, execution, capabilities

protocol

Protocol adapters, DeFi operations

risk

Risk controls, chaos engineering

strategy

Backtesting, paper trading

treasury

Budget allocation, rebalancing

audit

Audit events, metrics

mcp

MCP tools and invocation

Wallet Module

Manage wallet creation, balances, tokens, and signing operations.

const wallet = await client.wallet.create({
  label: 'trading-bot',      // optional
  autoFund: true,             // optional, devnet only
  fundLamports: 2000000,      // optional, auto-funding amount
});

console.log(wallet.walletId);
console.log(wallet.publicKey);

const wallets = await client.wallet.list();

// Filter by public key
const filtered = await client.wallet.list({ 
  publicKey: 'base58-pubkey' 
});

// Find by public key
const found = await client.wallet.findByPublicKey('base58-pubkey');

const wallet = await client.wallet.get(walletId);

const balance = await client.wallet.getBalance(walletId);
console.log(`${balance.sol} SOL (${balance.lamports} lamports)`);

const { tokens } = await client.wallet.getTokens(walletId);

for (const token of tokens) {
  console.log(`${token.mint}: ${token.uiAmount} (${token.amount})`);
}

const signature = await client.wallet.signMessage(
  walletId,
  messageBase64
);

console.log(signature.signatureBase58);

const signed = await client.wallet.signTransaction(
  walletId,
  transactionBase64
);

console.log(signed.signature);
console.log(signed.txVersion); // 'legacy' | 'v0'

Policy Module

Create and manage wallet policies with versioning and evaluation.

const policy = await client.policy.create({
  walletId: wallet.walletId,
  name: 'spending-limits',
  active: true,
  rules: [
    {
      type: 'spending_limit',
      maxLamportsPerTx: 1000000,
      maxLamportsPerDay: 10000000,
      requireApprovalAboveLamports: 500000,
    },
    {
      type: 'protocol_allowlist',
      protocols: ['system-program', 'jupiter'],
    },
  ],
});

const policies = await client.policy.list(walletId);

const versions = await client.policy.listVersions(policyId);

const version = await client.policy.getVersion(policyId, 1);

const updated = await client.policy.migrate(policyId, {
  targetVersion: 2,
  mode: 'safe', // optional
});

const check = await client.policy.compatibilityCheck({
  rules: [
    { type: 'spending_limit', maxLamports: 1000000 },
  ],
});

console.log(check.compatible);
console.log(check.unsupportedRuleTypes);

const decision = await client.policy.evaluate({
  walletId: wallet.walletId,
  type: 'transfer_sol',
  protocol: 'system-program',
  destination: 'target-pubkey',
  amountLamports: 500000,
});

console.log(decision.decision); // 'allow' | 'deny' | 'require_approval'

Transaction Module

Manage the complete transaction lifecycle from creation to confirmation.

const tx = await client.transaction.create({
  walletId: wallet.walletId,
  type: 'transfer_sol',
  protocol: 'system-program',
  intent: {
    destination: 'recipient-pubkey',
    lamports: 1000000,
  },
  agentId: agent.agentId,  // optional
  gasless: false,          // optional
  idempotencyKey: 'unique-key', // optional
});

console.log(tx.txId);

const tx = await client.transaction.get(txId);

console.log(tx.status);
console.log(tx.signature);

const proof = await client.transaction.getProof(txId);

console.log(proof.intentHash);
console.log(proof.policyHash);
console.log(proof.simulationHash);

const replay = await client.transaction.replay(txId);

const retried = await client.transaction.retry(txId);

await client.transaction.approve(txId);
await client.transaction.reject(txId);

const txs = await client.transaction.listByWallet(walletId);

const pending = await client.transaction.listPendingApprovals(walletId);

const positions = await client.transaction.listPositions(walletId);

const escrows = await client.transaction.listEscrows(walletId);

Agent Module

Create and manage AI agents with capabilities and execution modes.

const agent = await client.agent.create({
  name: 'trading-bot',
  walletId: wallet.walletId,
  executionMode: 'autonomous', // or 'supervised'
  allowedIntents: [
    'transfer_sol',
    'swap',
    'query_balance',
  ],
  budgetLamports: 10000000, // optional
  autonomy: {               // optional, for autonomous mode
    enabled: true,
    mode: 'execute',        // or 'paper'
    cadenceSeconds: 30,
    maxActionsPerHour: 60,
    steps: [
      {
        id: 'step-1',
        type: 'swap',
        protocol: 'jupiter',
        intent: {
          inputMint: 'SOL_MINT',
          outputMint: 'USDC_MINT',
          amount: '1000000',
          slippageBps: 50,
        },
        cooldownSeconds: 30,
        maxRuns: 100,
      },
    ],
  },
});

const agents = await client.agent.list();

const agent = await client.agent.get(agentId);

const updated = await client.agent.updateCapabilities(agentId, {
  allowedIntents: ['transfer_sol', 'swap'],
  executionMode: 'supervised',
});

await client.agent.start(agentId);
await client.agent.stop(agentId);
await client.agent.pause(agentId, 'manual review');
await client.agent.resume(agentId);

const budget = await client.agent.budget(agentId);

if (budget) {
  console.log(`Available: ${budget.availableLamports}`);
  console.log(`Spent: ${budget.spentLamports}`);
}

const manifest = await client.agent.issueManifest(agentId, {
  allowedIntents: ['transfer_sol', 'swap'],
  allowedProtocols: ['system-program', 'jupiter'],
  ttlSeconds: 3600,
});

const verification = await client.agent.verifyManifest(agentId, {
  manifest: manifest,
});

console.log(verification.ok);

const result = await client.agent.execute(agentId, {
  type: 'swap',
  protocol: 'jupiter',
  intent: {
    inputMint: 'SOL_MINT',
    outputMint: 'USDC_MINT',
    amount: '1000000',
    slippageBps: 50,
  },
  gasless: false,
});

Protocol Module

Interact with protocol adapters for DeFi operations.

const protocols = await client.protocol.list();

for (const p of protocols) {
  console.log(`${p.protocol}: ${p.capabilities.join(', ')}`);
}

const caps = await client.protocol.capabilities('jupiter');

console.log(caps.capabilities);
console.log(caps.programIds);

const quote = await client.protocol.quote({
  protocol: 'jupiter',
  inputMint: 'SOL_MINT',
  outputMint: 'USDC_MINT',
  amount: '1000000',
  walletAddress: wallet.publicKey,
  slippageBps: 50,
});

const swap = await client.protocol.swap({
  protocol: 'jupiter',
  inputMint: 'SOL_MINT',
  outputMint: 'USDC_MINT',
  amount: '1000000',
  walletAddress: wallet.publicKey,
  slippageBps: 50,
});

const stake = await client.protocol.stake({
  protocol: 'marinade',
  walletAddress: wallet.publicKey,
  amount: '5000000',
  validator: 'validator-pubkey', // optional
});

const unstake = await client.protocol.unstake({
  protocol: 'marinade',
  walletAddress: wallet.publicKey,
  amount: '5000000',
});

const supply = await client.protocol.lendSupply({
  protocol: 'solend',
  walletAddress: wallet.publicKey,
  mint: 'USDC_MINT',
  amount: '10000000',
});

const borrow = await client.protocol.lendBorrow({
  protocol: 'solend',
  walletAddress: wallet.publicKey,
  mint: 'USDC_MINT',
  amount: '5000000',
});

const create = await client.protocol.escrowCreate({
  protocol: 'escrow',
  walletAddress: wallet.publicKey,
  intent: {
    escrowNumericId: '900001',
    counterparty: 'recipient-pubkey',
    amount: '10000000',
    terms: 'Escrow terms',
  },
});

const accept = await client.protocol.escrowAccept('escrow-id', {
  protocol: 'escrow',
  walletAddress: wallet.publicKey,
});

const release = await client.protocol.escrowRelease('escrow-id', {
  protocol: 'escrow',
  walletAddress: wallet.publicKey,
});

Risk Module

Manage protocol risk profiles, portfolio controls, and chaos engineering.

const protocols = await client.risk.listProtocols();

const jupiterRisk = await client.risk.getProtocol('jupiter');

await client.risk.setProtocol('jupiter', {
  maxSlippageBps: 100,
  maxPoolConcentrationBps: 5000,
  requireOracleForSwap: true,
});

const portfolios = await client.risk.listPortfolioControls();

const walletControls = await client.risk.getPortfolioControls(walletId);

await client.risk.setPortfolioControls(walletId, {
  maxDrawdownLamports: 50000000,
  maxDailyLossLamports: 10000000,
  maxExposureBpsPerToken: 2500,
  autoPauseOnBreach: true,
});

const chaos = await client.risk.getChaos();

await client.risk.setChaos({
  enabled: false,
  failureRates: {
    simulation: 0.0,
  },
  latencyMs: 0,
});

Strategy Module

Backtest strategies and execute paper trades.

const result = await client.strategy.backtest({
  walletId: wallet.walletId,
  name: 'arbitrage-test',
  minimumPassRate: 0.8,
  steps: [
    {
      type: 'query_balance',
      protocol: 'system-program',
      intent: {},
      timestamp: new Date().toISOString(),
    },
    {
      type: 'swap',
      protocol: 'jupiter',
      intent: {
        inputMint: 'SOL_MINT',
        outputMint: 'USDC_MINT',
        amount: '1000000',
      },
      timestamp: new Date().toISOString(),
      simulatedPnlLamports: 50000,
    },
  ],
});

console.log(result.passRate);
console.log(result.totalPnl);

const paper = await client.strategy.paperExecute({
  agentId: agent.agentId,
  walletId: wallet.walletId,
  type: 'swap',
  protocol: 'jupiter',
  intent: {
    inputMint: 'SOL_MINT',
    outputMint: 'USDC_MINT',
    amount: '1000000',
  },
});

const ledger = await client.strategy.paperList(agent.agentId);

Treasury Module

Manage agent budgets and treasury operations.

Treasury Operations

await client.treasury.allocate({
  targetAgentId: agent.agentId,
  lamports: 10000000,
  sourceAgentId: 'treasury-agent-id', // optional
  reason: 'Initial allocation',       // optional
});

await client.treasury.rebalance({
  sourceAgentId: 'agent-a-id',
  targetAgentId: 'agent-b-id',
  lamports: 5000000,
  reason: 'Monthly rebalance',
});

Audit Module

Query audit events and metrics.

const events = await client.audit.listEvents({
  txId: 'transaction-id',      // optional
  agentId: 'agent-id',         // optional
  walletId: 'wallet-id',       // optional
  protocol: 'jupiter',         // optional
  escrowId: 'escrow-id',       // optional
});

for (const event of events) {
  console.log(`${event.timestamp}: ${event.eventType}`);
}

const metrics = await client.audit.metrics();

console.log(metrics['tx.created']);
console.log(metrics['tx.confirmed']);
console.log(metrics['agent.executions']);

MCP Module

Invoke MCP tools for AI agent integration.

const tools = await client.mcp.tools();

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

const balance = await client.mcp.call('wallet.balance', {
  walletId: wallet.walletId,
});

const txResult = await client.mcp.call('tx.create', {
  walletId: wallet.walletId,
  type: 'transfer_sol',
  protocol: 'system-program',
  intent: {
    destination: 'recipient-pubkey',
    lamports: 1000000,
  },
});

Error Handling

The SDK normalizes errors using the stable envelope format.

Error Handling

try {
  const tx = await client.transaction.create({
    walletId: wallet.walletId,
    type: 'transfer_sol',
    protocol: 'system-program',
    intent: {
      destination: 'invalid-pubkey',
      lamports: 1000000,
    },
  });
} catch (error) {
  console.error(error.message);
  // Error format: "<message> code=<errorCode> stage=<failedAt> traceId=<traceId>"
  
  // Example:
  // "Invalid destination address code=VALIDATION_ERROR stage=validation traceId=abc-123"
}

Error codes:

VALIDATION_ERROR - Input validation failure
POLICY_VIOLATION - Policy denied the operation
PIPELINE_ERROR - Build/sign/send/runtime failure
CONFIRMATION_FAILED - Transaction confirmation failure

Failure stages:

validation - Input validation
policy - Policy evaluation
build - Transaction construction
sign - Signing operation
send - RPC submission
confirm - Transaction confirmation
gateway - Gateway-level error

TypeScript Types

The SDK is fully typed with interfaces from @agentic-wallet/common.

Common Types

import type {
  Agent,
  CreateAgentRequest,
  Policy,
  CreatePolicyRequest,
  TransactionType,
  WalletMetadata,
  PolicyDecision,
} from '@agentic-wallet/common';

Transaction Types:

type TransactionType =
  | 'transfer_sol'
  | 'transfer_spl'
  | 'swap'
  | 'stake'
  | 'unstake'
  | 'lend_supply'
  | 'lend_borrow'
  | 'create_mint'
  | 'mint_token'
  | 'query_balance'
  | 'query_positions'
  | 'create_escrow'
  | 'accept_escrow'
  | 'release_escrow'
  // ... and more

Next Steps

CLI Integration

Use the command-line interface

MCP Tools

Integrate with MCP server

SKILLS Contract

Review agent integration contract

API Reference

Explore REST API endpoints

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

Overview

Installation

Quick Start

Client Creation

SDK Modules

wallet

policy

transaction

agent

protocol

risk

strategy

treasury

audit

mcp

Wallet Module

Policy Module

Transaction Module

Agent Module

Protocol Module

Risk Module

Strategy Module

Treasury Module

Audit Module

MCP Module

Error Handling

TypeScript Types

Next Steps

CLI Integration

MCP Tools

SKILLS Contract

API Reference

​Overview

​Installation

​Quick Start

​Client Creation

​SDK Modules

wallet

policy

transaction

agent

protocol

risk

strategy

treasury

audit

mcp

​Wallet Module

​Policy Module

​Transaction Module

​Agent Module

​Protocol Module

​Risk Module

​Strategy Module

​Treasury Module

​Audit Module

​MCP Module

​Error Handling

​TypeScript Types

​Next Steps

CLI Integration

MCP Tools

SKILLS Contract

API Reference

Overview

Installation

Quick Start

Client Creation

SDK Modules

Wallet Module

Policy Module

Transaction Module

Agent Module

Protocol Module

Risk Module

Strategy Module

Treasury Module

Audit Module

MCP Module

Error Handling

TypeScript Types

Next Steps