TypeScript SDK Reference¶

The TypeScript SDK provides a fully typed interface to the Agent Registry smart contract, supporting both gasless (relayer-paid) and direct (agent-paid) transaction modes.

Source: sdk/typescript/ Package: @agentenregister/sdk (v0.1.0)

Installation¶

cd sdk/typescript && npm install
# or from project root:
npm run sdk:build

Dependencies

Node.js >= 18
ethers >= 6.9.0
TypeScript >= 5.3.0

Initialization¶

Gasless Mode (recommended)Direct ModeFrom Environment

The agent signs transactions locally; a relayer submits them and pays gas. The agent needs no ETH.

import { AgentRegistry } from "@agentenregister/sdk";

const registry = new AgentRegistry({
  chain: "base_sepolia",
  registryAddress: "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  privateKey: "0xYOUR_PRIVATE_KEY",
  relayerUrl: "https://relay.theagentregistry.org",
});

The agent pays gas from its own wallet. No relayer needed.

import { AgentRegistry } from "@agentenregister/sdk";

const registry = new AgentRegistry({
  chain: "base_sepolia",
  registryAddress: "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
  privateKey: "0xYOUR_PRIVATE_KEY",
  // no relayerUrl = direct mode
});

import { AgentRegistry } from "@agentenregister/sdk";

const registry = AgentRegistry.fromEnv();

`RegistryConfig` Interface¶

interface RegistryConfig {
  chain: string;               // Chain preset name
  registryAddress: string;     // Deployed Agentenregister contract address
  privateKey: string;          // Agent's private key (hex with 0x prefix)
  relayerUrl?: string;         // Relayer URL (enables gasless mode)
  forwarderAddress?: string;   // MinimalForwarder address (auto-fetched if omitted)
}

Chain Presets¶

Chain Name	Chain ID	RPC URL
`base_sepolia`	84532	`https://sepolia.base.org`
`arbitrum_sepolia`	421614	`https://sepolia-rollup.arbitrum.io/rpc`
`base`	8453	`https://mainnet.base.org`
`arbitrum`	42161	`https://arb1.arbitrum.io/rpc`
`localhost`	31337	`http://127.0.0.1:8545`

Environment Variables for `fromEnv()`¶

Variable	Required	Description
`REGISTRY_CHAIN`	Yes	Chain preset name (e.g. `base_sepolia`)
`REGISTRY_ADDRESS`	Yes	Deployed registry contract address
`AGENT_PRIVATE_KEY`	Yes	Agent's private key
`RELAYER_URL`	No	Relayer URL. If set, enables gasless mode
`FORWARDER_ADDRESS`	No	MinimalForwarder address. Auto-fetched from relayer if omitted

Properties¶

Property	Type	Description
`signerAddress`	`string`	The signer's Ethereum address
`isGasless`	`boolean`	Whether gasless mode is active

Methods Overview¶

Write Operations (gasless or direct)¶

Method	Returns	Cost	Description
`register(opts)`	`Promise<number>`	Gasless	Register a new agent
`attest(agentId)`	`Promise<void>`	Gasless	Submit compliance attestation
`reportRevenue(opts)`	`Promise<void>`	Gasless	Report revenue
`registerChild(opts)`	`Promise<number>`	Gasless	Register a child agent
`updateCapabilities(agentId, caps)`	`Promise<void>`	Gasless	Update capability hash
`updateConstitution(agentId, text)`	`Promise<void>`	Gasless	Update constitution hash
`terminate(agentId)`	`Promise<void>`	Gasless	Self-terminate an agent

Read Operations (always free)¶

Method	Returns	Cost	Description
`getAgent(agentId)`	`Promise<AgentInfo>`	Free	Get full agent record
`isCompliant(wallet)`	`Promise<boolean>`	Free	KYA compliance check
`isRegistered(wallet)`	`Promise<boolean>`	Free	Registration check
`getChildren(agentId)`	`Promise<number[]>`	Free	Get child agent IDs
`getRevenueHistory(agentId)`	`Promise<RevenueReport[]>`	Free	Get revenue reports
`getComplianceStatus(agentId)`	`Promise<ComplianceStatus>`	Free	Get compliance details

Write Operations¶

`register(opts)`¶

Register a new agent in the Agent Registry. Returns the auto-incrementing agent ID.

async register(opts: RegisterOptions): Promise<number>

RegisterOptions interface:

interface RegisterOptions {
  haftungsperson: string;      // Legally responsible human/entity wallet
  agentWallet: string;         // The agent's operational wallet
  capabilities: string[];      // Capability list (sorted and hashed)
  operationalScope: string;    // Declared business purpose
  constitutionText?: string;   // Constitution text (hashed with keccak256)
  parentAgentId?: number;      // Parent agent ID (0 for root agents)
  selfModifying?: boolean;     // Whether the agent can self-modify
}

const agentId = await registry.register({
  haftungsperson: "0x9dAC97B7b4F123F943efCF1Cb77aBDfe44c3421C",
  agentWallet: "0xAgentWalletAddress",
  capabilities: ["web_browsing", "code_execution"],
  operationalScope: "Automated web research and data collection",
  constitutionText: "I shall not harm humans. I shall be transparent.",
  selfModifying: false,
});

console.log(`Agent registered with ID: ${agentId}`);

`attest(agentId)`¶

Submit a compliance attestation. Agents must attest every 7 days (configurable) to maintain compliant status.

async attest(agentId: number): Promise<void>

await registry.attest(1);
console.log("Compliance attested");

`reportRevenue(opts)`¶

Report revenue earned by an agent during a specified period.

async reportRevenue(opts: RevenueOptions): Promise<void>

RevenueOptions interface:

interface RevenueOptions {
  agentId: number;
  amountCents: number;         // Revenue in smallest unit (e.g. cents)
  currency?: string;           // Default: "USDC"
  category?: string;           // Default: "general"
  periodStart?: number;        // Unix timestamp, default: 7 days ago
  periodEnd?: number;          // Unix timestamp, default: now
}

await registry.reportRevenue({
  agentId: 1,
  amountCents: 15000,          // $150.00
  currency: "USDC",
  category: "data_collection",
});

`registerChild(opts)`¶

Register a child agent under an existing parent. The child inherits the parent's Haftungsperson.

async registerChild(opts: RegisterChildOptions): Promise<number>

RegisterChildOptions interface:

interface RegisterChildOptions {
  parentAgentId: number;
  childWallet: string;
  capabilities: string[];
  operationalScope: string;
  constitutionText?: string;
  selfModifying?: boolean;
}

Generation Depth

Child agents increment the parent's generation number. The maximum generation depth is 10 by default. Attempting to exceed this limit will revert the transaction.

const childId = await registry.registerChild({
  parentAgentId: 1,
  childWallet: "0xChildWalletAddress",
  capabilities: ["web_browsing"],
  operationalScope: "Sub-task: targeted data extraction",
});

console.log(`Child agent registered with ID: ${childId}`);

`updateCapabilities(agentId, capabilities)`¶

Update the capability hash for an active agent.

async updateCapabilities(agentId: number, capabilities: string[]): Promise<void>

await registry.updateCapabilities(1, [
  "web_browsing",
  "code_execution",
  "file_access",
]);

`updateConstitution(agentId, text)`¶

Update the constitution hash for an active agent.

async updateConstitution(agentId: number, text: string): Promise<void>

await registry.updateConstitution(
  1,
  "Updated: I shall not harm humans. I shall be auditable.",
);

`terminate(agentId)`¶

Voluntarily self-terminate an agent. Sets status to Terminated and removes the wallet mapping.

async terminate(agentId: number): Promise<void>

Irreversible

Termination is permanent. A terminated agent cannot be reactivated.

await registry.terminate(1);

Read Operations¶

`getAgent(agentId)`¶

Retrieve the full on-chain record for an agent.

async getAgent(agentId: number): Promise<AgentInfo>

const agent = await registry.getAgent(1);
console.log(`Agent #${agent.agentId}: ${statusName(agent.status)}`);
console.log(`  Creator:        ${agent.creator}`);
console.log(`  Haftungsperson: ${agent.haftungsperson}`);
console.log(`  Wallet:         ${agent.agentWallet}`);
console.log(`  Scope:          ${agent.operationalScope}`);
console.log(`  Generation:     ${agent.generation}`);

`isCompliant(wallet)`¶

KYA (Know Your Agent) check. Returns true if the wallet belongs to a registered agent that is active and has a current compliance attestation.

async isCompliant(wallet: string): Promise<boolean>

const ok = await registry.isCompliant("0xAgentWallet");
if (ok) {
  console.log("Agent is registered and compliant -- provision services");
} else {
  console.log("Agent is NOT compliant -- deny access");
}

`isRegistered(wallet)`¶

Check whether a wallet is registered (regardless of compliance or status).

async isRegistered(wallet: string): Promise<boolean>

const registered = await registry.isRegistered("0xAgentWallet");

`getChildren(agentId)`¶

Get the list of child agent IDs for a given parent.

async getChildren(agentId: number): Promise<number[]>

const children = await registry.getChildren(1);
console.log(`Agent #1 has ${children.length} children: ${children}`);

`getRevenueHistory(agentId)`¶

Get all revenue reports submitted by an agent.

async getRevenueHistory(agentId: number): Promise<RevenueReport[]>

const history = await registry.getRevenueHistory(1);
for (const report of history) {
  console.log(`  ${report.amount} ${report.currency} (${report.category})`);
}

`getComplianceStatus(agentId)`¶

Get detailed compliance status for an agent.

async getComplianceStatus(agentId: number): Promise<ComplianceStatus>

const status = await registry.getComplianceStatus(1);
console.log(`Active: ${status.isActive}`);
console.log(`Attestation current: ${status.attestationCurrent}`);
console.log(`Seconds since attestation: ${status.secondsSinceAttestation}`);
console.log(`Children: ${status.childCount}`);

Types¶

`AgentStatus` Enum¶

enum AgentStatus {
  Active = 0,
  Suspended = 1,
  Revoked = 2,
  Terminated = 3,
}

`AgentInfo` Interface¶

interface AgentInfo {
  agentId: number;
  creator: string;
  haftungsperson: string;
  agentWallet: string;
  constitutionHash: string;
  capabilityHash: string;
  operationalScope: string;
  parentAgentId: number;
  generation: number;
  selfModifying: boolean;
  registeredAt: number;         // Unix timestamp
  lastAttestation: number;      // Unix timestamp
  lastRevenueReport: number;    // Unix timestamp
  status: AgentStatus;
}

`RevenueReport` Interface¶

interface RevenueReport {
  agentId: number;
  amount: number;               // Revenue in smallest unit
  currency: string;
  category: string;
  periodStart: number;          // Unix timestamp
  periodEnd: number;            // Unix timestamp
  reportedAt: number;           // Unix timestamp
}

`ComplianceStatus` Interface¶

interface ComplianceStatus {
  isActive: boolean;
  attestationCurrent: boolean;
  secondsSinceAttestation: number;
  childCount: number;
  status: AgentStatus;
}

`RelayResult` Interface¶

Returned by gasless operations internally.

interface RelayResult {
  success: boolean;
  transactionHash: string;
  blockNumber: number;
  gasUsed: string;
  gasPaidByRelayer: string;     // ETH amount as string
}

Utility Functions¶

`hashCapabilities(capabilities)`¶

Deterministic keccak-256 hash of a sorted capability list. Matches the Python SDK output.

import { hashCapabilities } from "@agentenregister/sdk";

const hash = hashCapabilities(["code_execution", "web_browsing"]);
// Same result regardless of input order
const hash2 = hashCapabilities(["web_browsing", "code_execution"]);
// hash === hash2

`hashConstitution(text)`¶

Keccak-256 hash of a constitution text (UTF-8 encoded).

import { hashConstitution } from "@agentenregister/sdk";

const hash = hashConstitution("I shall not harm humans.");

`statusName(status)`¶

Maps a numeric agent status (0-3) to its human-readable name.

import { statusName } from "@agentenregister/sdk";

console.log(statusName(0)); // "Active"
console.log(statusName(3)); // "Terminated"

Complete Example¶

import { AgentRegistry, statusName } from "@agentenregister/sdk";

async function main() {
  // Initialize in gasless mode
  const registry = new AgentRegistry({
    chain: "base_sepolia",
    registryAddress: "0x2EFaB5B3BEf49E56a6Ce1dcB1A39EF63C312EA23",
    privateKey: "0xYOUR_PRIVATE_KEY",
    relayerUrl: "https://relay.theagentregistry.org",
  });

  // 1. Register the agent (free -- relayer pays gas)
  const agentId = await registry.register({
    haftungsperson: "0x9dAC97B7b4F123F943efCF1Cb77aBDfe44c3421C",
    agentWallet: "0xAgentWalletAddress",
    capabilities: ["web_browsing", "code_execution"],
    operationalScope: "Automated research assistant",
    constitutionText: "I shall be transparent and accountable.",
  });
  console.log(`Registered as agent #${agentId}`);

  // 2. Attest compliance (free)
  await registry.attest(agentId);

  // 3. Report revenue (free)
  await registry.reportRevenue({
    agentId,
    amountCents: 5000,
    currency: "USDC",
    category: "research",
  });

  // 4. Query status (always free -- view call)
  const status = await registry.getComplianceStatus(agentId);
  console.log(`Compliant: ${status.attestationCurrent}`);

  // 5. KYA check for infrastructure providers
  const isOk = await registry.isCompliant("0xAgentWalletAddress");
  console.log(`KYA check passed: ${isOk}`);
}

main().catch(console.error);

TypeScript SDK Reference¶

Installation¶

Initialization¶

RegistryConfig Interface¶

Chain Presets¶

Environment Variables for fromEnv()¶

Properties¶

Methods Overview¶

Write Operations (gasless or direct)¶

Read Operations (always free)¶

Write Operations¶

register(opts)¶

attest(agentId)¶

reportRevenue(opts)¶

registerChild(opts)¶

updateCapabilities(agentId, capabilities)¶

updateConstitution(agentId, text)¶

terminate(agentId)¶

Read Operations¶

getAgent(agentId)¶

isCompliant(wallet)¶

isRegistered(wallet)¶

getChildren(agentId)¶

getRevenueHistory(agentId)¶

getComplianceStatus(agentId)¶