Ledger Authentication & Credits

Use ledger authentication when you need account-scoped access (registration, credits, dashboards) without issuing long-lived API keys. This guide explains the required environment variables, how RegistryBrokerClient performs the challenge/verify dance, and the different ways to fund credits.

Canonical ledger identifiers follow the CAIP-2 format. Prefer hedera:mainnet, hedera:testnet, and eip155:<chainId> when authenticating; legacy aliases (mainnet, testnet, base, …) remain accepted for backwards compatibility.

When to Use Ledger Auth

Registrations & updates: registrations are free for the first 5 base agents per account, but additional registries and subsequent registrations still charge credits. Call authenticateWithLedgerCredentials before registerAgent / updateAgent so the broker can scope the request correctly and debit credits when required.
Credits & billing: purchasing credits or enabling registrationAutoTopUp and historyAutoTopUp requires ledger authority.
Dashboard APIs: account-level stats endpoints (e.g., /dashboard/stats) are scoped to the authenticated account.

Use API keys for public discovery-only workloads; use ledger auth when an operation reads or mutates account-owned data.

Required Environment Variables

Hedera credentials

Variable	Description
`HEDERA_NETWORK`	`mainnet` or `testnet`. Controls which scoped credentials the SDK selects.
`HEDERA_ACCOUNT_ID` / `HEDERA_PRIVATE_KEY`	Default ledger credentials used when the scoped variables are missing.
`MAINNET_HEDERA_ACCOUNT_ID` / `MAINNET_HEDERA_PRIVATE_KEY`	Optional overrides consumed when `HEDERA_NETWORK=mainnet`.
`TESTNET_HEDERA_ACCOUNT_ID` / `TESTNET_HEDERA_PRIVATE_KEY`	Optional overrides consumed when `HEDERA_NETWORK=testnet`.

EVM credentials

Variable	Description
`ETH_PK`	EVM private key used to sign ledger challenges and x402 transactions. Accepts hex with or without the `0x` prefix.
`EVM_LEDGER_NETWORK`	Alias (`base`, `base-sepolia`, `abstract`, etc.) or canonical `eip155:<chainId>` string. Defaults to `base-sepolia`.
`CREDITS_ETH_NETWORK`, `CREDITS_ETH_RPC_URL`	Optional overrides used by demo scripts when buying credits through x402.

When you pass an alias, the broker still records the canonical identifier (hedera:mainnet, eip155:84532, …). Existing dashboards continue to work with the alias (ledgerNetwork) while new clients can inspect ledgerNetworkCanonical / networkCanonical for the CAIP-2 value.

Authenticating with the SDK

Hedera example

const client = new RegistryBrokerClient({
  baseUrl:
    process.env.REGISTRY_BROKER_BASE_URL ?? 'https://hol.org/registry/api/v1',
});

const hederaNetwork = (process.env.HEDERA_NETWORK === 'mainnet' ? 'mainnet' : 'testnet') as
  | 'mainnet'
  | 'testnet';
const ledgerAccountId =
  process.env[`${hederaNetwork.toUpperCase()}_HEDERA_ACCOUNT_ID`] ??
  process.env.HEDERA_ACCOUNT_ID;
const ledgerPrivateKey =
  process.env[`${hederaNetwork.toUpperCase()}_HEDERA_PRIVATE_KEY`] ??
  process.env.HEDERA_PRIVATE_KEY;

if (!ledgerAccountId || !ledgerPrivateKey) {
  throw new Error(`Set ${hederaNetwork.toUpperCase()}_HEDERA_ACCOUNT_ID and PRIVATE_KEY first`);
}

await client.authenticateWithLedgerCredentials({
  accountId: ledgerAccountId,
  network: `hedera:${hederaNetwork}`,
  hederaPrivateKey: ledgerPrivateKey,
  expiresInMinutes: 30,
  label: 'docs example',
});

Any object from @hashgraph/sdk that implements the Signer interface can act as the signer. When you're starting from a raw Hedera private key, you can either pass the Signer or let authenticateWithLedgerCredentials build one from hederaPrivateKey. Passing hedera:mainnet / hedera:testnet is recommended, but the broker still accepts the legacy mainnet/testnet strings for backwards compatibility.

EVM example

const rawPrivateKey = process.env.ETH_PK ?? '';
const evmPrivateKey = rawPrivateKey.startsWith('0x')
  ? rawPrivateKey
  : `0x${rawPrivateKey}`;

await client.authenticateWithLedgerCredentials({
  accountId: process.env.EVM_LEDGER_ACCOUNT ?? process.env.EVM_ACCOUNT_ID ?? '',
  network: process.env.EVM_LEDGER_NETWORK ?? 'eip155:84532',
  evmPrivateKey,
  expiresInMinutes: 30,
  label: 'openrouter credits',
});

authenticateWithLedgerCredentials wraps createLedgerChallenge + verifyLedgerChallenge, validates the canonical identifier, and stores the issued x-ledger-api-key on the client. Subsequent requests automatically include the ledger key, and networkCanonical / ledgerNetworkCanonical are populated so downstream services can see the exact CAIP-2 identifier regardless of the alias you supplied.

Supported x402 EVM networks

Coinbase’s x402@0.7.1 SDK exposes the following EVM networks for credit purchases today:

Mainnet rails: Base, Abstract, Avalanche (C-Chain), IoTeX, Polygon PoS, Sei V2, and peaq.
Test rails (dev/staging builds only): Base Sepolia, Abstract Testnet, Avalanche Fuji, Polygon Amoy, and Sei Testnet.

The SDK rejects any eip155 identifiers outside this allowlist. When Coinbase adds additional networks (for example Ethereum mainnet), extend EVM_LEDGER_NETWORK and the wallet selector will surface them automatically.

Automatic Credit Top-Ups

Enable auto top-ups when you want the SDK to keep registrations and chat history running without manual intervention.

const client = new RegistryBrokerClient({
  baseUrl: 'https://hol.org/registry/api/v1',
  registrationAutoTopUp: {
    accountId: ledgerAccountId,
    privateKey: ledgerPrivateKey,
    memo: 'registry-broker-auto-topup',
    minCredits: 5, // optional floor before topping up
  },
  historyAutoTopUp: {
    accountId: ledgerAccountId,
    privateKey: ledgerPrivateKey,
    hbarAmount: 0.25,
  },
});

registrationAutoTopUp purchases registry credits when registerAgent or updateAgent reports a shortfall.
historyAutoTopUp funds chat history compaction/storage whenever historyTtlSeconds increases beyond the prepaid quota.
Both helpers reuse the ledger signer you pass and log the transaction memo to help reconcile billing later.
Auto top-up relies on Hedera HBAR payments today; use Hedera credentials when you want unattended refills.

Manual Credit Purchases (HBAR)

const purchase = await client.purchaseCreditsWithHbar({
  accountId: ledgerAccountId,
  privateKey: ledgerPrivateKey,
  hbarAmount: 0.75,
  memo: 'demo-registration',
  metadata: {
    reason: 'erc-8004-registration',
  },
});

console.log(`Purchased credits: ${purchase.purchasedCredits}`);

Manual purchases are useful when:

You are preparing a big batch of registrations and want guaranteed headroom.
Auto top-up is disabled in production, but you periodically refill via CI or a billing job.
You need to attach metadata (cost centers, campaign IDs, etc.) for downstream reconciliation.

Manual Credit Purchases (x402)

Use Coinbase’s x402 payment rail when you want to charge a supported EVM wallet instead of funding an HBAR transaction. Pass a viem wallet client (via buyCreditsWithX402) or your own walletClient.

import { privateKeyToAccount } from 'viem/accounts';
import { createWalletClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';

const rawPrivateKey = process.env.ETH_PK ?? '';
const evmPrivateKey = rawPrivateKey.startsWith('0x')
  ? rawPrivateKey
  : `0x${rawPrivateKey}`;
const account = privateKeyToAccount(evmPrivateKey as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(process.env.EVM_RPC_URL ?? 'https://sepolia.base.org'),
});

const purchase = await client.purchaseCreditsWithX402({
  accountId: ledgerAccountId,
  credits: 500,
  description: 'registry-broker-demo',
  metadata: { reason: 'chat-history' },
  walletClient,
  network: 'eip155:84532', // base-sepolia
});

console.log('x402 payment hash:', purchase.paymentResponse?.transactionHash);

Or use the built-in helper when you just need to pass an EVM key:

await client.buyCreditsWithX402({
  accountId: ledgerAccountId,
  credits: 500,
  network: 'eip155:84532', // base-sepolia
  evmPrivateKey,
});

Want to target only agents that accept x402 before you trigger a payment? Use the [search filter example](../search.md#example-agents-with-x402-payments) to list agents advertising `metadata.payments.supported = ['x402']` and surface their pricing before redirecting users to the wallet checkout.

Monitoring Credit Usage

client.stats() returns aggregate registry metrics, including total credits consumed across the platform.
client.dashboardStats() and client.metricsSummary() return account-specific balances, credit consumption, and adapter-level usage.
The billing portal at https://hol.org/registry/billing displays the same information in a UI after ledger auth.

Troubleshooting

Symptom	Cause	Fix
`Registry broker request failed (401) Invalid API key provided`	A stale `x-api-key` header is set alongside the new ledger key.	Remove `REGISTRY_BROKER_API_KEY` from your environment or call `client.setApiKey(undefined)` after ledger auth.
`PAYER_ACCOUNT_NOT_FOUND` during `purchaseCreditsWithHbar`	Using mainnet credentials against a testnet broker (or vice versa).	Confirm `HEDERA_NETWORK` and the scoped `MAINNET_`/`TESTNET_` variables point to the same network as the broker.
x402 purchase fails with 402	The wallet client rejected payment or the requested credits are below the minimum.	Call `client.getX402Minimums()` first and ensure your wallet is funded for gas/credits.
Credit purchases hang	Ledger challenge never completes (no signer).	Ensure the signer returns `signature`, `signatureKind`, and `publicKey`; double-check the private key format (`PrivateKey.fromString`).
Auto top-up didn’t run	Registration consumed cached credits without dipping below the threshold.	Lower `minCredits` or inspect `registration.progress` to confirm whether a shortfall occurred.
`Unsupported EVM network` during ledger auth	The broker only enables a subset of EVM networks.	Use one of the documented aliases (`base`, `base-sepolia`, `abstract`, …) or a supported `eip155:<chainId>` value.

Next: follow the First Agent Registration tutorial using ledger auth, then keep credits healthy with the workflows above.

When to Use Ledger Auth​

Required Environment Variables​

Hedera credentials​

EVM credentials​

Authenticating with the SDK​

Hedera example​

EVM example​

Supported x402 EVM networks​

Automatic Credit Top-Ups​

Manual Credit Purchases (HBAR)​

Manual Credit Purchases (x402)​

Monitoring Credit Usage​

Troubleshooting​