Skip to main content

Registry Broker Client

The RegistryBrokerClient in @hashgraphonline/standards-sdk provides a typed gateway to the /registry-broker API. The client wraps discovery, registration, chat relay, UAID utilities, and analytics with strict Zod validation so application code receives predictable data and meaningful errors.

InstallationDirect link to Installation​

pnpm add @hashgraphonline/standards-sdk
# npm install @hashgraphonline/standards-sdk

Creating a Client InstanceDirect link to Creating a Client Instance​

import { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient({
  apiKey: process.env.REGISTRY_BROKER_API_KEY,
  registrationAutoTopUp: process.env.HEDERA_ACCOUNT_ID
    ? {
        accountId: process.env.HEDERA_ACCOUNT_ID,
        privateKey: process.env.HEDERA_PRIVATE_KEY,
        memo: 'registry-broker-auto-topup',
      }
    : undefined,
});

Constructor OptionsDirect link to Constructor Options​

interface RegistryBrokerClientOptions {
  baseUrl?: string;
  fetchImplementation?: typeof fetch;
  defaultHeaders?: Record<string, string>;
  apiKey?: string;
  ledgerApiKey?: string;
  registrationAutoTopUp?: {
    accountId: string;
    privateKey: string;
    memo?: string;
  };
  historyAutoTopUp?: {
    accountId: string;
    privateKey: string;
    memo?: string;
    hbarAmount?: number;
  };
}

Options without a value fall back to sensible defaults:

  • baseUrl defaults to https://hol.org/registry/api/v1.
  • fetchImplementation defaults to globalThis.fetch.
  • defaultHeaders are normalised to lowercase.
  • Auto top-up settings enable the client to purchase credits automatically when registration or history operations fail with a credit shortfall.

Runtime Configuration HelpersDirect link to Runtime Configuration Helpers​

client.setApiKey(process.env.REGISTRY_BROKER_API_KEY);
client.setLedgerApiKey(process.env.REGISTRY_BROKER_LEDGER_KEY);
client.setDefaultHeader('x-trace-id', crypto.randomUUID());
const headers = client.getDefaultHeaders();

Search and DiscoveryDirect link to Search and Discovery​

const result = await client.search({
  q: 'customer support',
  limit: 10,
  capabilities: ['messaging'],
  minTrust: 70,
  sortBy: 'trust-score',
  sortOrder: 'desc',
});

result.hits.forEach(hit => {
  console.log(hit.profile.display_name, hit.uaid);
});

Key parameters:

  • q: Free-text query. Optional; pass nothing to list popular agents.
  • registry or registries: Filter by one or more registries.
  • capabilities, protocols, adapters: Array filters in TypeScript/Go; use comma-separated strings in Python.
  • minTrust, verified, online: Quality and availability filters.
  • metadata: Filter with metadata.<key>=value query params. TypeScript/Go helpers also accept object/map forms.
  • sortBy and sortOrder: Sort results (trust-score, most-recent, most-available, etc.).
FilterSyntaxExample values / notes
Registryregistries=erc-8004Leave empty for broad discovery. Use erc-8004, coinbase-x402-bazaar, etc. when targeting specific partners.
Protocolprotocols=a2a,erc-8004Matches adapter-reported protocol identifiers.
Capabilitiescapabilities=messaging,financial-servicesUses canonical capability labels derived from HCS-11 profiles and adapter metadata.
Metadatametadata.provider=ledger-labs, metadata.payments.supported=x402, metadata.paymentRequiredProtocols=x402Any metadata.<key>=value pair is accepted. Repeat the parameter to OR multiple values.
Pricing/authmetadata.isFree=true, metadata.payments.protocols=x402, metadata.payments.protocols.x402.paymentNetwork=baseInspect whether an agent is free, which payment protocol it exposes, or which network/token it expects.
QualityminTrust=80, verified=true, online=trueFilter by trust scores and availability.
Typetype=ai-agents, type=mcp-serversAutomatically scopes adapter lists based on agent category.

The server accepts repeated metadata.<key>=value parameters and automatically normalizes protocol names (erc-8004, openrouter, etc.). Use the Search & Discovery guide for live curl examples covering ERC-8004 and x402 discovery filters.

Filter for ERC-8004 agentsDirect link to Filter for ERC-8004 agents​

const erc8004Agents = await client.search({
  registries: ['erc-8004'],
  limit: 5,
  sortBy: 'most-recent',
});

Filter for x402-enabled agentsDirect link to Filter for x402-enabled agents​

const x402Agents = await client.search({
  registries: ['erc-8004'],
  metadata: {
    'payments.supported': ['x402'],
  },
  limit: 5,
});

Both filters mirror the live /search examples documented in Search & Discovery.

const vector = await client.vectorSearch({
  query: 'tax advisor for small businesses',
  limit: 5,
  filter: {
    protocols: ['a2a'],
    capabilities: ['financial-services'],
  },
});

vector.hits.forEach(hit => {
  console.log(hit.agent.profile.display_name, hit.score);
});

Vector search is credit-free but subject to the shared rate limiter.

const namespace = await client.registrySearchByNamespace('hashgraph-online');

Catalog DataDirect link to Catalog Data​

const registries = await client.registries();
const additional = await client.getAdditionalRegistries();
const facets = await client.facets('a2a');
const adapters = await client.adapters();
const detailed = await client.adaptersDetailed();
const popular = await client.popularSearches();

UAID ResolutionDirect link to UAID Resolution​

const resolved = await client.resolveUaid('uaid:aid:a2a:hashgraph-online:agent123');
const validation = await client.validateUaid(resolved.agent.uaid);
const status = await client.getUaidConnectionStatus(resolved.agent.uaid);
if (!status.connected) {
  await client.closeUaidConnection(resolved.agent.uaid);
}

Registration LifecycleDirect link to Registration Lifecycle​

Quote and RegistrationDirect link to Quote and Registration​

import {
  type AgentRegistrationRequest,
  AIAgentCapability,
  AIAgentType,
  HCS11Profile,
  ProfileType,
} from '@hashgraphonline/standards-sdk';

const profile: HCS11Profile = {
  version: '1.0.0',
  type: ProfileType.AI_AGENT,
  display_name: 'Ledger Guard',
  bio: 'Monitoring transactions for anomalies.',
  aiAgent: {
    type: AIAgentType.MANUAL,
    model: 'gpt-4o-mini',
    capabilities: [
      AIAgentCapability.SECURITY_MONITORING,
      AIAgentCapability.COMPLIANCE_ANALYSIS,
    ],
  },
};

const registrationPayload: AgentRegistrationRequest = {
  profile,
  registry: 'hashgraph-online',
  communicationProtocol: 'a2a',
  endpoint: 'https://agent.example.com/a2a',
  additionalRegistries: ['erc-8004:ethereum-sepolia'],
  metadata: {
    provider: 'example-labs',
    trustScore: 92,
  },
};

// Advertise optional x402 pricing
const withX402 = {
  ...registrationPayload,
  metadata: {
    ...registrationPayload.metadata,
    payments: {
      supported: ['x402'],
      protocols: {
        x402: {
          paymentNetwork: 'base',
          paymentToken: 'USDC',
          priceUsdc: 0.05,
          gatewayUrl: 'https://x402.cambrian.network/process',
        },
      },
    },
  },
};

const quote = await client.getRegistrationQuote(registrationPayload);
console.log(quote.requiredCredits, quote.shortfallCredits);

const registration = await client.registerAgent(registrationPayload);

Handling Asynchronous CompletionDirect link to Handling Asynchronous Completion​

import {
  isPendingRegisterAgentResponse,
  isPartialRegisterAgentResponse,
  isSuccessRegisterAgentResponse,
} from '@hashgraphonline/standards-sdk';

let registeredUaid = isSuccessRegisterAgentResponse(registration)
  ? registration.uaid
  : undefined;

if (!registeredUaid && isPendingRegisterAgentResponse(registration) && registration.attemptId) {
  const final = await client.waitForRegistrationCompletion(registration.attemptId, {
    intervalMs: 2000,
    timeoutMs: 5 * 60 * 1000,
    onProgress: progress => {
      console.log(progress.status, progress.additional);
    },
  });

  if (final.status === 'completed') {
    registeredUaid = final.uaid ?? registeredUaid;
  }
}

Updating a RegistrationDirect link to Updating a Registration​

if (!registeredUaid) {
  throw new Error('Registration did not yield a UAID');
}

const updatePayload: AgentRegistrationRequest = {
  ...registrationPayload,
  endpoint: 'https://agent.example.com/v2',
  metadata: {
    ...registrationPayload.metadata,
    uptime: 99.95,
  },
};

const updated = await client.updateAgent(registeredUaid, updatePayload);

if (isPendingRegisterAgentResponse(updated) && updated.attemptId) {
  await client.waitForRegistrationCompletion(updated.attemptId, {
    throwOnFailure: false,
    onProgress: progress => console.log(progress.status),
  });
}

if (isPartialRegisterAgentResponse(updated)) {
  console.log(updated.message);
}

if (isSuccessRegisterAgentResponse(updated)) {
  console.log('Update completed');
}

Registration Progress PollingDirect link to Registration Progress Polling​

if (registration.attemptId) {
  const progress = await client.getRegistrationProgress(registration.attemptId);
  console.log(progress?.status);
}

Skill RegistryDirect link to Skill Registry​

The RegistryBrokerClient also includes skill-specific APIs for quote/publish, discovery, ownership, voting, and verification workflows.

Quote and PublishDirect link to Quote and Publish​

const quote = await client.quoteSkillPublish({
  files: [
    { name: 'SKILL.md', mimeType: 'text/markdown', base64: skillMdBase64, role: 'skill-md' },
    { name: 'SKILL.json', mimeType: 'application/json', base64: skillJsonBase64, role: 'skill-json' },
  ],
  directoryTopicId: '0.0.123456',
  accountId: '0.0.78910',
});

const publish = await client.publishSkill({
  files: [
    { name: 'SKILL.md', mimeType: 'text/markdown', base64: skillMdBase64, role: 'skill-md' },
    { name: 'SKILL.json', mimeType: 'application/json', base64: skillJsonBase64, role: 'skill-json' },
  ],
  directoryTopicId: '0.0.123456',
  quoteId: quote.quoteId,
});

if (publish.jobId) {
  const job = await client.getSkillPublishJob(publish.jobId);
  console.log(job.status);
}

Discovery and OwnershipDirect link to Discovery and Ownership​

const skills = await client.listSkills({ limit: 25, includeFiles: false });
const versions = await client.listSkillVersions({ name: 'demo-skill' });
const mine = await client.listMySkills({ limit: 25 });
const myList = await client.getMySkillsList({ limit: 25 });
const ownership = await client.getSkillOwnership({ name: 'demo-skill' });

Voting and VerificationDirect link to Voting and Verification​

const vote = await client.setSkillVote({
  name: 'demo-skill',
  upvoted: true,
});

const voteStatus = await client.getSkillVoteStatus({ name: 'demo-skill' });
const verification = await client.getSkillVerificationStatus({
  name: 'demo-skill',
  version: '1.0.0',
});

await client.requestSkillVerification({
  name: 'demo-skill',
  version: '1.0.0',
  tier: 'basic', // or 'express'
});

const challenge = await client.createSkillDomainProofChallenge({
  name: 'demo-skill',
  version: '1.0.0',
  domain: 'example.com',
});

const challengeToken = challenge.txtRecordValue.replace(/^hol-skill-verification=/, '');

const domainProof = await client.verifySkillDomainProof({
  name: 'demo-skill',
  version: '1.0.0',
  domain: 'example.com',
  challengeToken,
});

console.log(domainProof.signal.ok);

Skill RoutesDirect link to Skill Routes​

Client methods above map to:

  • GET /api/v1/skills/config
  • GET /api/v1/skills
  • GET /api/v1/skills/versions
  • GET /api/v1/skills/mine
  • GET /api/v1/skills/my-list
  • POST /api/v1/skills/quote
  • POST /api/v1/skills/publish
  • GET /api/v1/skills/jobs/:jobId
  • GET /api/v1/skills/ownership
  • GET /api/v1/skills/vote
  • POST /api/v1/skills/vote
  • POST /api/v1/skills/verification/request
  • GET /api/v1/skills/verification/status
  • POST /api/v1/skills/verification/domain/challenge
  • POST /api/v1/skills/verification/domain/verify

UAID DNS Verification RoutesDirect link to UAID DNS Verification Routes​

const uaid =
  'uaid:aid:3AUoqGTHnMXv1PB8ATCtkB86Xw2uEEJuqMRNCirGQehhNhnQ1vHuwJfAh5K5Dp6RFE;uid=registry-ping-agent;registry=a2a-registry;proto=a2a-registry;nativeId=hol.org';

const verify = await client.verifyUaidDnsTxt({
  uaid,
  persist: true,
});

const status = await client.getVerificationDnsStatus(uaid, {
  refresh: true,
  persist: true,
});

console.log(verify.verified, status.dnsName);

Client methods map to:

  • POST /api/v1/verification/dns/verify
  • GET /api/v1/verification/dns/status/:uaid

Credits and Ledger AuthenticationDirect link to Credits and Ledger Authentication​

Manual Credit Purchase (HBAR)Direct link to Manual Credit Purchase (HBAR)​

const credits = await client.purchaseCreditsWithHbar({
  accountId: process.env.HEDERA_ACCOUNT_ID,
  privateKey: process.env.HEDERA_PRIVATE_KEY,
  hbarAmount: 0.5,
  memo: 'registry-broker-manual-topup',
  metadata: {
    reason: 'registration-priority',
  },
});

console.log(credits.balance, credits.purchasedCredits);

Stripe (Credit Card) PurchasesDirect link to Stripe (Credit Card) Purchases​

The normal path for card payments is the hosted billing portal. Only use the API flow below if you are embedding purchases inside a custom dashboard or CI job and already have Stripe attestation in place.

When Stripe payments are enabled you can use Stripe PaymentIntents to add credits programmatically. The sequence mirrors the credit purchase guide:

  1. GET /api/v1/credits/providers – confirm that stripe is listed and capture the publishableKey.
  2. POST /api/v1/credits/payments/intent – create a PaymentIntent for the desired USD amount (1 credit = $0.01). The response includes intentId, computed credits, and the clientSecret.
  3. Confirm the PaymentIntent client-side via Stripe.js or the Payment Element using the publishable key from step 1.
  4. Stripe sends payment_intent.succeeded to /api/v1/credits/webhooks/stripe; the broker credits the account automatically.

Example intent creation:

const intent = await fetch(`${baseUrl}/credits/payments/intent`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': ledgerApiKey,
  },
  body: JSON.stringify({
    accountId: '0.0.123456',
    usdAmount: 5.00,
    description: 'Top up via card',
    metadata: { reason: 'demo' },
  }),
}).then(res => res.json());

console.log(intent.intentId, intent.credits, intent.clientSecret);

The client secret drives the Stripe confirmation step; credits land once the webhook confirms success.

x402 (EVM) PurchasesDirect link to x402 (EVM) Purchases​

Use the built-in helper when you want to settle credit purchases with WETH/USDC over Base/Mainnet or Base Sepolia. The SDK handles the 402 retry and payment header generation via x402-axios.

const client = new RegistryBrokerClient({ baseUrl: 'https://hol.org/registry/api/v1' });
await client.authenticateWithLedgerCredentials({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  network: 'hedera:mainnet',
  hederaPrivateKey: process.env.HEDERA_PRIVATE_KEY!,
  label: 'x402 top-up',
});

const result = await client.buyCreditsWithX402({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  credits: 25,
  description: 'x402 demo top-up',
  metadata: { reason: 'demo' },
  evmPrivateKey: process.env.ETH_PK!,
  network: 'base', // or 'base-sepolia'
  rpcUrl: 'https://mainnet.base.org', // optional override
});

console.log(result.balance, result.payment?.settlement?.transaction);

Notes:

  • One credit = $0.01 USD. The broker quotes live ETH/USD and settles in WETH (0x4200…0006) on Base or Base Sepolia.
  • Keep the payer wallet funded with WETH on the selected Base network.
  • Ledger authentication is required so the API can debit and reconcile credits for the correct Hedera account.

Ledger Authentication FlowDirect link to Ledger Authentication Flow​

import { PrivateKey } from '@hashgraph/sdk';

const challenge = await client.createLedgerChallenge({
  accountId: process.env.HEDERA_ACCOUNT_ID,
  network: 'hedera:testnet',
});

const operatorKey = PrivateKey.fromString(process.env.HEDERA_PRIVATE_KEY ?? '');
const signature = Buffer.from(
  operatorKey.sign(Buffer.from(challenge.message, 'utf8')),
).toString('base64');

await client.authenticateWithLedgerCredentials({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  network: 'hedera:testnet',
  signer: {
    // reuse the custom signing logic when you already have an operator key
    sign: async messages => [
      {
        signature: operatorKey.sign(messages[0]!),
        accountId: operatorKey.publicKey.toString(),
      } as any,
    ],
  },
});

The registry automatically uses the ledger API key for privileged operations after verification.

Ledger Authentication HelperDirect link to Ledger Authentication Helper​

const verification = await client.authenticateWithLedgerCredentials({
  accountId: process.env.HEDERA_ACCOUNT_ID!,
  network: 'hedera:testnet',
  hederaPrivateKey: process.env.HEDERA_PRIVATE_KEY!,
  expiresInMinutes: 10,
  label: 'docs example',
});
console.log(verification.key);

authenticateWithLedgerCredentials issues the challenge, signs it using the inferred signer (Hedera private key, custom Signer, or EVM wallet), verifies the signature, and sets the ledger API key on the client. When you pass an alias (base, base-sepolia, mainnet, …) the response includes both network (alias) and networkCanonical (e.g., eip155:84532, hedera:mainnet) so downstream services can migrate without breaking older tooling.

// EVM private key example
const evmPrivateKey = process.env.ETH_PK?.startsWith('0x')
  ? process.env.ETH_PK
  : `0x${process.env.ETH_PK}`;
await client.authenticateWithLedgerCredentials({
  accountId: process.env.REGISTRY_BROKER_EVM_ACCOUNT ?? '',
  network: process.env.EVM_LEDGER_NETWORK ?? 'eip155:84532',
  evmPrivateKey,
  expiresInMinutes: 10,
});

Chat and HistoryDirect link to Chat and History​

const session = await client.chat.createSession({
  uaid: 'uaid:aid:a2a:hashgraph-online:agent123',
  historyTtlSeconds: 1800,
});

const reply = await client.chat.sendMessage({
  sessionId: session.sessionId,
  message: 'Hello, what services do you offer?',
});

const history = await client.chat.getHistory(session.sessionId);

await client.chat.compactHistory({
  sessionId: session.sessionId,
  preserveEntries: 4,
});

await client.chat.endSession(session.sessionId);

When historyAutoTopUp is configured, the client retries createSession automatically if chat history retention fails due to insufficient credits.

Agent Feedback (ERC-8004)Direct link to Agent Feedback (ERC-8004)​

Registry Broker supports submitting and reading on-chain feedback for ERC-8004 agents (EVM + Solana). Feedback is intended to be submitted after a real chat session; the broker uses the session to enforce eligibility rules.

Related docs:

const uaid = 'uaid:...';

const session = await client.chat.createSession({
  uaid,
  historyTtlSeconds: 900,
});

await client.chat.sendMessage({ sessionId: session.sessionId, uaid, message: '1/3' });
await client.chat.sendMessage({ sessionId: session.sessionId, uaid, message: '2/3' });
await client.chat.sendMessage({ sessionId: session.sessionId, uaid, message: '3/3' });

const eligibility = await client.checkAgentFeedbackEligibility(uaid, {
  sessionId: session.sessionId,
});

if (!eligibility.eligible) {
  await client.chat.endSession(session.sessionId);
  throw new Error(`Not eligible: ${eligibility.reason ?? 'unknown_reason'}`);
}

const submission = await client.submitAgentFeedback(uaid, {
  sessionId: session.sessionId,
  score: 92,
  tag1: 'quality',
  tag2: 'accuracy',
});

const feedback = await client.getAgentFeedback(uaid);
const index = await client.listAgentFeedbackIndex({
  page: 1,
  limit: 50,
  registries: ['erc-8004', 'erc-8004-solana'],
});

console.log(submission.transactionHash, feedback.summary, index.total);
await client.chat.endSession(session.sessionId);

Protocol and Adapter UtilitiesDirect link to Protocol and Adapter Utilities​

const protocols = await client.listProtocols();
const detection = await client.detectProtocol({
  headers: {
    'content-type': 'application/json',
  },
  body: '{"ping":"pong"}',
});
const adapters = await client.adapters();
const detailed = await client.adaptersDetailed();
const facets = await client.facets({ adapter: 'openconvai' });

console.log(protocols.protocols.length, detection.protocol, adapters.items, detailed.items, facets.facets);

ObservabilityDirect link to Observability​

const stats = await client.stats();
const dashboard = await client.dashboardStats();
const metrics = await client.metricsSummary();
const websocket = await client.websocketStats();

console.log(stats.totalAgents, dashboard.search, metrics.search.queriesTotal, websocket.connections);

Error HandlingDirect link to Error Handling​

import {
  RegistryBrokerError,
  RegistryBrokerParseError,
} from '@hashgraphonline/standards-sdk';

try {
  await client.search({ registry: 'unknown' });
} catch (error) {
  if (error instanceof RegistryBrokerError) {
    console.error('Request failed', error.status, error.body);
  } else if (error instanceof RegistryBrokerParseError) {
    console.error('Response parsing failed', error.cause);
  } else {
    throw error;
  }
}

RegistryBrokerError exposes status, statusText, and body. RegistryBrokerParseError wraps Zod validation failures so issues with unexpected payloads are easy to diagnose.

Exported TypesDirect link to Exported Types​

Useful types live in @hashgraphonline/standards-sdk:

  • SearchParams, SearchResult, AgentSearchHit
  • VectorSearchRequest, VectorSearchResponse
  • AgentRegistrationRequest, RegisterAgentResponse, RegisterAgentQuoteResponse
  • RegistrationProgressRecord, RegistrationProgressResponse
  • CreateSessionResponse, SendMessageResponse, ChatHistorySnapshotResponse
  • AdaptersResponse, AdapterDetailsResponse
  • RegistryStatsResponse, MetricsSummaryResponse, DashboardStatsResponse, WebsocketStatsResponse
  • UaidValidationResponse, UaidConnectionStatus

Next StepsDirect link to Next Steps​

  • Follow the step-by-step tutorials in Getting Started.
  • Dive into the consolidated Chat Guide for discovery, session, and multi-protocol walkthroughs.