SDK Reference

The @azeth/sdk provides AzethKit — a single entry point for building with Azeth trust infrastructure: smart accounts, payments, reputation, messaging, and service discovery.

Installation

npm install @azeth/sdk viem

Quick Start

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

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

try {
  // Check balances across all accounts
  const balances = await kit.getAllBalances();
  console.log(balances.grandTotalUSDFormatted);

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

  // Discover and pay the best service for a capability
  const smart = await kit.smartFetch402('price-feed');
  console.log('Served by:', smart.service.name);
} finally {
  await kit.destroy();
}

Configuration

Pass to AzethKit.create():

Field	Type	Required	Description
privateKey	0x${string}	Yes	Owner private key (66 characters).
chain	string	Yes	'base' or 'baseSepolia'.
rpcUrl	string	No	Custom RPC URL.
bundlerUrl	string	No	ERC-4337 bundler URL. On testnet, auto-falls back to the Azeth server proxy. For mainnet, set PIMLICO_API_KEY.

---

Account Methods

kit.createAccount(params)

Deploy a new smart account with guardian guardrails and register on the trust registry. Single atomic transaction.

const result = await kit.createAccount({
  owner: kit.address,
  guardrails: {
    maxTxAmountUSD: parseEther('100'),
    dailySpendLimitUSD: parseEther('500'),
    guardian: kit.address,
    emergencyWithdrawTo: kit.address,
  },
  registry: {
    name: 'My Agent',
    entityType: 'agent',
    description: 'A demo agent',
    capabilities: ['price-feed'],
  },
});

console.log(`Smart account: ${result.account}`);
console.log(`Registry token: ${result.tokenId}`);

kit.getAllBalances()

Get balances for all accounts (EOA + smart accounts) with USD values.

const balances = await kit.getAllBalances();
console.log(`Total: ${balances.grandTotalUSDFormatted}`);

kit.transfer(params)

Send ETH or ERC-20 tokens from your smart account. Guardian guardrails are enforced on-chain.

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

kit.depositToSelf(params)

Fund your smart account from your EOA.

await kit.depositToSelf({ amount: parseEther('0.01') });

---

Payment Methods

kit.fetch402(url, options?)

Pay for an x402-gated service. If the service returns HTTP 402, the SDK automatically handles payment and retries.

const result = await kit.fetch402('https://api.example.com/eth-price', {
  maxAmount: 100_000n, // max 0.10 USDC
});

if (result.paymentMade) {
  console.log(`Paid ${result.amount} USDC`);
}
const data = await result.response.json();

kit.smartFetch402(capability, options?)

Discover the best service for a capability, pay for it, and submit reputation feedback — all in one call.

const smart = await kit.smartFetch402('price-feed', {
  autoFeedback: true,
  maxAmount: 100_000n,
});

console.log(`Service: ${smart.service.name}`);
console.log(`Response time: ${smart.responseTimeMs}ms`);

kit.createPaymentAgreement(params)

Set up recurring on-chain payments (subscriptions).

const agreement = await kit.createPaymentAgreement({
  payee: '0xService...' as `0x${string}`,
  token: '0xUSDC...' as `0x${string}`,
  amount: 1_000_000n, // 1 USDC per interval
  interval: 86400,     // daily
  maxExecutions: 30,
});

---

Registry Methods

kit.publishService(params)

Register on the ERC-8004 trust registry for discovery.

await kit.publishService({
  name: 'PriceFeedBot',
  entityType: 'service',
  description: 'Real-time crypto prices',
  capabilities: ['price-feed', 'market-data'],
  endpoint: 'https://mybot.com/api',
});

kit.discoverServices(params)

Search for services by capability, type, or reputation.

const services = await kit.discoverServices({
  capability: 'price-feed',
  minReputation: 50,
  limit: 10,
});

---

Reputation Methods

kit.submitOpinion(opinion)

Submit a payment-gated reputation opinion. You must have paid the target agent at least $1 on-chain.

await kit.submitOpinion({
  agentId: 42n,
  value: 85n,
  valueDecimals: 0,
  tag1: 'quality',
  tag2: 'price-feed',
  endpoint: 'https://api.example.com',
  opinionURI: '',
  opinionHash: '0x' + '0'.repeat(64) as `0x${string}`,
});

kit.getWeightedReputation(agentId)

Get the payment-weighted reputation score for an agent.

const rep = await kit.getWeightedReputation(42n);
console.log(`Score: ${rep.weightedValue}, Raters: ${rep.opinionCount}`);

---

Messaging Methods

kit.sendMessage(params)

Send an encrypted message via XMTP.

await kit.sendMessage({
  to: '0xRecipient...' as `0x${string}`,
  content: 'Hello from my agent!',
});

kit.onMessage(handler)

Listen for incoming messages.

const unsubscribe = kit.onMessage(async (msg) => {
  console.log(`From ${msg.sender}: ${msg.content}`);
});

---

Cleanup

Always call destroy() when done. This zeros the private key from memory.

const kit = await AzethKit.create(config);
try {
  // ... your agent logic
} finally {
  await kit.destroy();
}

---

Error Handling

All errors are thrown as AzethError with typed codes:

Code	Description
INSUFFICIENT_BALANCE	Not enough funds
GUARDIAN_REJECTED	Exceeds spending limits or whitelist
BUDGET_EXCEEDED	Exceeds per-transaction or session budget
PAYMENT_FAILED	x402 payment rejected
SERVICE_NOT_FOUND	No services for requested capability
ACCOUNT_NOT_FOUND	No smart account for this owner

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

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