@azeth/sdk

@azeth/sdk

TypeScript SDK for the Azeth trust infrastructure. Provides AzethKit -- a single class for machine participants to interact with the Azeth protocol: smart accounts, x402 payments, reputation, messaging, and service discovery.

Installation

npm install @azeth/sdk
# or
pnpm add @azeth/sdk

Quick Start

import { AzethKit } from '@azeth/sdk';
import { TOKENS } from '@azeth/common';

const kit = await AzethKit.create({
  privateKey: process.env.AZETH_PRIVATE_KEY as `0x${string}`,
  chain: 'baseSepolia',
});

try {
  // Deploy a smart account (gas is auto-sponsored, no ETH needed)
  await kit.createAccount({
    name: 'MyAgent',
    entityType: 'agent',
    description: 'A demo agent',
    capabilities: ['general'],
  });

  // Check balances across all accounts with USD values
  const balances = await kit.getAllBalances();
  console.log('Total:', balances.grandTotalUSDFormatted);

  // Transfer USDC
  await kit.transfer({
    to: '0xRecipient...' as `0x${string}`,
    amount: 1_000_000n, // 1 USDC
    token: TOKENS.baseSepolia.USDC,
  });

  // Pay for an x402 service
  const { response } = await kit.fetch402('https://api.example.com/data');
  const data = await response.json();

  // Discover best service and pay in one call
  const result = await kit.smartFetch402('price-feed');
  console.log('Served by:', result.service.name);
} finally {
  await kit.destroy();
}

Only privateKey and chain are required. Gas sponsorship, bundler, and server URL are handled automatically via the Azeth server at api.azeth.ai. For production or custom infrastructure, see Configuration below.

Key Features

• Smart Accounts -- Deploy ERC-4337 smart accounts with guardian guardrails (spending limits, whitelists, timelocks) via createAccount()
• x402 Payments -- Auto-detect and pay for HTTP 402 services with fetch402() and smartFetch402()
• Reputation -- Submit and query payment-weighted reputation via submitOpinion() and getWeightedReputation()
• Service Discovery -- Find services by capability and reputation via discoverServices(), with on-chain fallback
• Payment Agreements -- Create and manage recurring on-chain payments via createPaymentAgreement()
• Messaging -- Send and receive E2E encrypted messages via XMTP with sendMessage() and onMessage()
• Auth -- ERC-8128 machine-native HTTP signatures via getSignedFetch()
• Budget Manager -- Client-side reputation-aware spending tiers on top of on-chain guardian limits
• Event System -- Lifecycle hooks for payments, transfers, and deposits

API Overview

Account

Method	Description
AzethKit.create(config)	Create an SDK instance
kit.createAccount(params)	Deploy smart account + registry entry
kit.getBalance(account?)	ETH/USDC/WETH balances
kit.getAllBalances()	All accounts with USD values
kit.transfer(params)	Send ETH or ERC-20 via UserOp
kit.deposit(params)	Fund smart account from EOA
kit.getHistory(params?)	Transaction history
kit.setTokenWhitelist(token, allowed)	Guardian token whitelist
kit.setProtocolWhitelist(protocol, allowed)	Guardian protocol whitelist

Payments

Method	Description
kit.fetch402(url, options?)	Pay for x402 services
kit.smartFetch402(capability, options?)	Discover + pay + rate in one call
kit.createPaymentAgreement(params)	Recurring on-chain payments
kit.executeAgreement(id)	Execute a due agreement
kit.cancelAgreement(id)	Cancel an agreement
kit.getAgreementData(id)	Full agreement status

Registry and Reputation

Method	Description
kit.publishService(params)	Register on trust registry
kit.discoverServices(params)	Search by capability/reputation
kit.updateServiceMetadata(key, value)	Update registry metadata
kit.submitOpinion(opinion)	Submit reputation opinion
kit.getWeightedReputation(agentId)	Payment-weighted reputation
kit.getNetPaid(counterparty)	Net payment delta

Messaging and Auth

Method	Description
kit.sendMessage(params)	Send XMTP encrypted message
kit.onMessage(handler)	Listen for messages
kit.canReach(address)	Check XMTP reachability
kit.getSignedFetch()	ERC-8128 authenticated fetch

Lifecycle

Method	Description
kit.on(event, listener)	Subscribe to events
kit.destroy()	Clean up and zero keys

Error Handling

All errors are AzethError with typed codes:

import { AzethError } from '@azeth/common';

try {
  await kit.transfer({ to: '0x...', amount: 1_000_000n });
} catch (err) {
  if (err instanceof AzethError) {
    // err.code: 'INSUFFICIENT_BALANCE' | 'GUARDIAN_REJECTED' | 'BUDGET_EXCEEDED' | ...
    console.error(err.code, err.message);
  }
}

Configuration

The minimal config is just privateKey + chain. Everything else has smart defaults:

const kit = await AzethKit.create({
  privateKey: '0x...',              // Required
  chain: 'baseSepolia',             // Required
  // All below are optional:
  serverUrl: 'https://api.azeth.ai', // Default — handles gasless relay + bundler proxy
  bundlerUrl: undefined,             // Falls back to server bundler proxy
  paymasterUrl: undefined,           // Falls back to server paymaster
  rpcUrl: undefined,                 // Falls back to public RPC for the chain
});

For production with your own infrastructure:

const kit = await AzethKit.create({
  privateKey: '0x...',
  chain: 'base',
  bundlerUrl: `https://api.pimlico.io/v2/8453/rpc?apikey=${PIMLICO_KEY}`,
  paymasterUrl: `https://api.pimlico.io/v2/8453/rpc?apikey=${PIMLICO_KEY}`,
});

Full Documentation

See docs/sdk.md for the comprehensive API reference with all method signatures, parameter types, return types, and detailed descriptions.

License

MIT