Standards SDK Registry Broker Client

The Registry Broker client in @hashgraphonline/standards-sdk provides a typed, batteries-included wrapper around the Hashgraph Online Registry Broker. It covers discovery, registration, chat relay, UAID utilities, metrics, and protocol detection in a single interface with rich Zod-backed response validation.

Getting Started

Installation

Installation

pnpm

bash

1pnpm add @hashgraphonline/standards-sdk

Credentials & Credits

The production broker is pay-as-you-go. Before invoking any authenticated endpoints you must top up credits for your account at https://hol.org/registry/billing. Without credits, registration, chat relays, UAID utilities, and other metered APIs will fail with 402 responses.

Keyword and vector search remain credit-free but they are governed by a shared rate limiter.

Once credits are loaded you can generate an API key (or use session tokens) and create a client:

💡 The Registry Broker production API is available at https://hol.org/registry/api/v1. Override baseUrl only if you’ve been provisioned a private deployment.

Creating a client

Initialization

TypeScript

typescript

1import { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';
2
3const client = new RegistryBrokerClient({
4// Optional: supply an API key issued by your Registry Broker instance
5apiKey: process.env.REGISTRY_BROKER_API_KEY,
6});

TypeScript custom fetch override

const client = new RegistryBrokerClient({
  fetchImplementation: (input, init) => myInstrumentationFetch(input, init),
  defaultHeaders: {
    'x-trace-id': crypto.randomUUID(),
  },
});

• baseUrl – defaults to the production broker (https://hol.org/registry/api/v1). Trailing slashes and missing /api/v1 segments are normalized automatically.
• apiKey – when provided, the client sets an x-api-key header on every request. You can update it later with client.setApiKey(newKey).
• defaultHeaders – use client.setDefaultHeader(name, value) to add or remove headers after instantiation (values are trimmed; falsy values remove the header).
• fetchImplementation – pass a custom fetch (for Cloudflare Workers, Node polyfills, testing, etc.).

Quickstart: OpenRouter chat relay

Quickstart

TypeScript

typescript

1import { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';
2
3const client = new RegistryBrokerClient({
4apiKey: process.env.REGISTRY_BROKER_API_KEY,
5});
6
7const session = await client.chat.createSession({
8uaid: 'uaid:aid:2bnewJwP95isoCUkT5mee5gm212WS76tphHwBQvbWoquRa9kt89UanrBqHXpaSh4AN;uid=anthropic/claude-3.5-sonnet;registry=openrouter;proto=openrouter;nativeId=anthropic/claude-3.5-sonnet',
9});
10
11const reply = await client.chat.sendMessage({
12sessionId: session.sessionId,
13message: 'Give me a one-line summary of your pricing.',
14});
15
16console.log(reply.message);

For the hosted Registry Broker, the OpenRouter adapter is configured with its own API key and uses your credit balance, so you do not need to pass an OpenRouter token from the client for standard flows. You only need the auth block for custom deployments or when you explicitly proxy end‑user credentials through the broker.

Architecture Overview

The SDK mediates every request, ensuring headers and schemas are applied consistently.

✅ Free discovery: keyword search, vector search, adapter catalog, and public stats are available to everyone without credits or authentication (subject to the rate limit described above).

Use the billing portal only when you need metered functionality such as agent registration, chat relay, UAID inscription, or history compaction. These endpoints require an active credit balance; otherwise the broker returns 402 responses.

Searching the Registry

Discovery APIs

Keyword Search

typescript

1import type { SearchResult } from '@hashgraphonline/standards-sdk';
2
3const result: SearchResult = await client.search({
4q: 'custody agent',
5registry: 'hashgraph-online',
6capabilities: ['messaging'],
7minTrust: 70,
8page: 1,
9limit: 25,
10});
11
12console.log(`Found ${result.total} agents`);
13for (const hit of result.hits) {
14console.log(hit.name, hit.registry, hit.capabilities);
15}

SearchParams supports q, page, limit, registry, minTrust, and capability filtering (capabilities can be AIAgentCapability enum values or arbitrary strings).

⚠️ Vector search obeys the broker’s rate limiter. Each response includes x-rate-limit-limit and x-rate-limit-remaining headers plus Retry-After on 429s. Provide an API key to move the limiter from a shared IP bucket to a per-key bucket.

Discovery Insights

Metadata APIs

Registries

typescript

1const registries = await client.registries();     // { registries: string[] }
2const popular = await client.popularSearches();  // { searches: string[] }

These responses are strongly typed and validated, making them safe to expose in dashboards without additional schema definitions.

Working With UAIDs

UAID Utilities

uaid.ts

typescript

1const resolved = await client.resolveUaid('uaid:aid:123...');
2console.log(resolved.agent.name);
3
4const validation = await client.validateUaid('uaid:aid:123...');
5console.log(validation.valid, validation.formats);
6
7const status = await client.getUaidConnectionStatus('uaid:aid:123...');
8if (!status.connected) {
9console.log('Agent offline');
10}
11
12await client.closeUaidConnection('uaid:aid:123...');

Each method returns the appropriate schema-backed response (UaidValidationResponse, UaidConnectionStatus).

Chat Sessions

Chat Relay

Basic Chat

typescript

1const session = await client.chat.createSession({ uaid: 'uaid:aid:123...' });
2
3const reply = await client.chat.sendMessage({
4sessionId: session.sessionId,
5message: 'Hello from the SDK!',
6streaming: false,
7});
8
9console.log(reply.content);
10
11await client.chat.endSession(session.sessionId);

Seed chat sessions with a UAID ({ uaid: 'uaid:...' }) for all integrations. The streaming flag is passed through to the broker; if the backend supports streaming, you can adapt the response accordingly.

Passing downstream auth (paid OpenRouter models)

AgentAuthConfig supports four schemes:

type	Fields used	Example
bearer	token	{ type: 'bearer', token: 'sk-or-...' }
basic	username, password	{ type: 'basic', username, password }
apiKey	headerName, headerValue	{ type: 'apiKey', headerName: 'x-api-key', headerValue: '...' }
header	headerName, headerValue, optional headers map	Use for bespoke header names or multi-header payloads

Cross-protocol chat playbook

The Standards SDK ships end-to-end demos that bridge Registry Broker chat to both AgentVerse mailbox/proxy agents and ERC-8004 HTTP agents:

• standards-sdk/demo/registry-broker-agentverse-demo.ts
• standards-sdk/demo/registry-broker-erc8004-demo.ts
• standards-sdk/demo/registry-broker/register-agent-moltbook.ts (register + Moltbook claim details)

Chat history and compaction

The history demo (standards-sdk/demo/registry-broker-history-demo.ts) illustrates how to persist, audit, and eventually compact chat transcripts.

Agent Registration

Registration

Simple Register

typescript

1import type { HCS11Profile } from '@hashgraphonline/standards-sdk';
2
3const profile: HCS11Profile = {
4version: '1.0.0',
5type: 1,
6display_name: 'Ledger Guard',
7bio: 'Monitoring transactions for anomalies',
8aiAgent: {
9  type: 'openai',
10  model: 'gpt-4o-mini',
11  capabilities: ['monitoring', 'compliance'],
12},
13};
14
15const registration = await client.registerAgent({
16profile,
17registry: 'hashgraph-online',
18protocol: 'aid',
19endpoint: 'https://ledger-guard.example.com',
20metadata: {
21  trustScore: 92,
22  uptime: 99.95,
23},
24});
25
26console.log(registration.uaid, registration.agent.nativeId);

Handling asynchronous responses & progress tracking

When a registration includes additional registries (for example ERC-8004) the broker returns 202 Accepted with a status: "pending" payload. The primary Hashgraph inscription is committed immediately, while downstream registrars are processed in the background via a work queue.

All progress tracking endpoints are protected by account ownership checks.

Skill Verification (DNS Domain Proof)

The RegistryBrokerClient skill APIs support version-scoped verification requests and DNS TXT domain proof.

// 1) request paid verification for an exact version
await client.requestSkillVerification({
  name: 'demo-skill',
  version: '1.0.0',
  tier: 'basic', // or 'express'
});

// 2) check verification status/signals for that version
const status = await client.getSkillVerificationStatus({
  name: 'demo-skill',
  version: '1.0.0',
});

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

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

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

console.log(status.verified, domainProof.signal.ok);

Skill Lifecycle and Preview Status

Use these methods when you need the machine-readable lifecycle contract behind validate-first GitHub Actions, preview pages, and canonical name@version status lookups.

const status = await client.getSkillStatus({
  name: 'demo-skill',
  version: '1.0.0',
});

const statusByRepo = await client.getSkillStatusByRepo({
  repo: 'https://github.com/hashgraph-online/demo-skill',
  skillDir: '.',
  ref: 'refs/pull/42/merge',
});

const preview = await client.getSkillPreview({
  name: 'demo-skill',
  version: '1.0.0',
});

const previewByRepo = await client.getSkillPreviewByRepo({
  repo: 'https://github.com/hashgraph-online/demo-skill',
  skillDir: '.',
  ref: 'refs/pull/42/merge',
});

const previewById = await client.getSkillPreviewById('preview_demo');

console.log(status.trustTier, statusByRepo.found, preview.found, previewByRepo.found, previewById.found);

These map to:

• GET /api/v1/skills/status
• GET /api/v1/skills/status/by-repo
• GET /api/v1/skills/preview
• GET /api/v1/skills/preview/by-repo
• GET /api/v1/skills/preview/{previewId}

Use the repo-based methods for pull request validation because they resolve state against repo, skillDir, and an optional Git ref before falling back to published name@version records.

Secretless GitHub OIDC preview upload

Validate-only workflows can upload preview reports without RB_API_KEY when the workflow grants id-token: write.

const previewReport = {
  schemaVersion: 'skill-preview.v1',
  repository: {
    url: 'https://github.com/hashgraph-online/demo-skill',
    ref: 'refs/pull/42/merge',
  },
  skill: {
    name: 'demo-skill',
    version: '1.0.0',
    skillDir: '.',
  },
};

const previewUpload = await client.uploadSkillPreviewFromGithubOidc({
  token: process.env.ACTIONS_ID_TOKEN ?? '',
  report: previewReport,
});

console.log(previewUpload.previewId, previewUpload.statusUrl);

This maps to:

• POST /api/v1/skills/preview/github-oidc

UAID DNS Verification (HCS-14)

Use these methods to validate that a UAID is correctly bound to a DNS TXT record (_uaid.<nativeId>).

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

// 1) live DNS TXT verification (optionally persist signal to agent metadata)
const verifyResult = await client.verifyUaidDnsTxt({
  uaid,
  persist: true,
});

// 2) read stored status or force live recheck via query flags
const dnsStatus = await client.getVerificationDnsStatus(uaid, {
  refresh: true,
  persist: true,
});

console.log(verifyResult.verified, dnsStatus.profileId, dnsStatus.dnsName);

These map to:

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

Protocol Discovery

Helpers

Detect Protocol

typescript

1const protocols = await client.listProtocols(); // { protocols: string[] }
2
3const detected = await client.detectProtocol({
4message: {
5  headers: { 'content-type': 'application/json' },
6  body: '{"hello":"world"}',
7},
8});
9
10console.log(detected.protocol); // e.g. "aid"

Example: Discover and Chat

Full Flow

discover-chat.ts

typescript

1const client = new RegistryBrokerClient({ apiKey: process.env.RB_API_KEY });
2
3// 1. Find high-trust audit agents
4const auditAgents = await client.search({ q: 'audit', minTrust: 80, limit: 5 });
5
6// 2. Ask the top result a question
7const topAgent = auditAgents.hits[0];
8const session = await client.chat.createSession({ uaid: topAgent.uaid });
9await client.chat.sendMessage({ sessionId: session.sessionId, message: 'Summarize your capabilities.' });