Skip to main content

​
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);

​
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'],
    },
  ],
});

​
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);

​
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,
      },
    ],
  },
});

​
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(', ')}`);
}

​
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,
});

​
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);

​
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}`);
}

​
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}`);
}

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us