@sperax/tool-name-service

Resolve Web3 names to addresses and back — ENS (.eth), SNS (.sol) and Space ID (.bnb, .arb), across Ethereum, Solana, BNB Chain and Arbitrum.

Name Service is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-name-service

Usage

Call it directly

import { nameServiceExecutor } from '@sperax/tool-name-service';

const result = await nameServiceExecutor.invoke('resolveName', {"name":"<name>"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { NameServiceManifest, nameServiceExecutor } from '@sperax/tool-name-service';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: NameServiceManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await nameServiceExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

NameServiceManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-name-service

API reference

resolveName

Resolve a human-readable Web3 name to an on-chain address. Supports ENS (.eth, Ethereum), SNS (.sol, Solana) and Space ID (.bnb on BNB Chain, .arb on Arbitrum). A name with no suffix is tried against every registry and may resolve in more than one. Also reports whether the ENS reverse record verifies the forward record.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | name | string | yes | Name to resolve, e.g. "vitalik.eth", "toly.sol", "cz.bnb", "dev.arb", or a bare "vitalik" to search all registries. |

reverseResolve

Find the Web3 names that point at an address (reverse resolution). An EVM address is checked against ENS primary names and Space ID (.bnb, .arb); a Solana address returns every .sol domain the wallet holds.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | address | string | yes | Address to look up — EVM (0x + 40 hex) or Solana (base58). The encoding is detected automatically. |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-name-service is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0