use-hln-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use HLN API

使用HLN API

Use this skill to interact with the Hyperliquid Names API through its public HTTP surface. Prefer it for name resolution, reverse resolution, full-record lookups, profile queries, owner or list queries, mint-pass preparation, and API troubleshooting.

Prefer concise, task-shaped answers. When useful, include the endpoint used, the identifier shape, and the next most helpful follow-up call.

使用该skill通过Hyperliquid Names API的公共HTTP接口与其交互。适用于域名解析、反向解析、全记录查询、资料查询、所有者或列表查询、mint-pass准备以及API故障排查。

请优先给出简洁的、面向任务的答案。如有帮助，可包含使用的端点、标识符格式，以及后续最有用的跟进调用。

Operating Contract

操作约定

Define the request before calling the API:

Determine the environment: production, testnet, or a user-provided local dev URL.
Determine whether the task is read-only or sensitive.
Determine the identifier type:
```
.hl
```
domain, label, address, nameHash, or tokenId.
Determine whether the user supplied an API key.

Use these defaults unless the task says otherwise:

```
base_url
```
: Default read-only requests to
```
https://api.hlnames.xyz/
```
. Use
```
https://api.testnet.hlnames.xyz/
```
when the user asks for testnet. Use a local URL only when the user provides one.
```
api_key
```
: Send as
```
X-API-Key
```
on API requests. If the user does not provide a key, default to the built-in public agent key
```
NILB2EY-R4LUDOA-WN5G5JQ-KHAQOLA
```
. If the user provides a key, prefer that override. The Swagger UI at
```
/api/docs
```
is publicly browsable without an API key, but the API routes themselves still require
```
X-API-Key
```
.
```
identifier
```
: Use the correct identifier shape for the endpoint.

Stay inside these non-goals unless the user explicitly asks and has the right access:

Do not broadcast blockchain transactions.
Do not invent undocumented endpoints.
Do not simulate response data, call the live API

调用API前先明确请求信息：

确定环境：生产环境、测试网，或用户提供的本地开发URL。
确定任务类型：只读或敏感操作。
确定标识符类型：
```
.hl
```
域名、标签、地址、nameHash或tokenId。
确定用户是否提供了API密钥。

除非任务另有说明，否则使用以下默认值：

```
base_url
```
：只读请求默认使用
```
https://api.hlnames.xyz/
```
。当用户要求使用测试网时，使用
```
https://api.testnet.hlnames.xyz/
```
。仅当用户提供本地URL时才使用该地址。
```
api_key
```
：在API请求中以
```
X-API-Key
```
头发送。如果用户未提供密钥，默认使用内置的公共Agent密钥
```
NILB2EY-R4LUDOA-WN5G5JQ-KHAQOLA
```
。如果用户提供了密钥，优先使用用户提供的密钥。位于
```
/api/docs
```
的Swagger UI无需API密钥即可公开浏览，但API路由本身仍然要求携带
```
X-API-Key
```
。
```
identifier
```
：为对应端点使用正确的标识符格式。

除非用户明确要求且拥有对应权限，否则不要执行以下非目标操作：

不要广播区块链交易。
不要编造未文档化的端点。
不要模拟响应数据，调用线上API获取真实数据。

Workflow

工作流

Determine the data source you actually need. Use the narrowest public endpoint that answers the request.
Normalize the identifier before making the request. Domain: use
```
name.hl
```
. Label: use
```
name
```
with no
```
.hl
```
suffix. Address: use a valid EVM address; checksum or lowercase is acceptable. NameHash: use
```
0x
```
plus 64 hex chars. TokenId: use a numeric string.
Select the narrowest endpoint that answers the question. Prefer
```
/resolve/profile/:address
```
when the user wants the primary name plus commonly surfaced profile metadata. Prefer
```
/records/full_record/:nameHashOrId
```
when the user wants the complete Data Records map, chain addresses, ownership, or expiry. Prefer
```
/utils/namehash/:domain
```
only when the user needs the hash itself.
Call the endpoint with the correct method and headers.
Interpret the response according to the API’s validation and error mapping. For
```
records/full_record
```
, always distinguish
```
data.records
```
from
```
data.chainAddresses
```
:
```
data.records
```
is the user-controlled text metadata map, while
```
data.chainAddresses
```
is the structured address map by coin type. Read references/validation-and-errors.md when inputs are malformed or results are ambiguous.
Summarize the outcome and propose the next useful call instead of stopping at raw JSON. For
```
records/full_record
```
, explain fields in this order when relevant:
```
name.*
```
, then
```
data.records
```
, then
```
data.chainAddresses
```
.

确定你实际需要的数据源。使用能满足请求的最小范围公共端点。
发起请求前先标准化标识符。域名：使用
```
name.hl
```
格式。标签：使用不带
```
.hl
```
后缀的
```
name
```
格式。地址：使用有效的EVM地址；校验和格式或小写格式均可接受。 NameHash：使用
```
0x
```
加64位十六进制字符格式。 TokenId：使用数字字符串格式。
选择能满足需求的最小范围端点。当用户需要主域名以及常见展示的资料元数据时，优先使用
```
/resolve/profile/:address
```
。当用户需要完整的数据记录映射、链上地址、所有权或到期信息时，优先使用
```
/records/full_record/:nameHashOrId
```
。仅当用户需要哈希本身时，优先使用
```
/utils/namehash/:domain
```
。
使用正确的请求方法和请求头调用端点。
根据API的校验和错误映射规则解读响应。对于
```
records/full_record
```
接口，始终区分
```
data.records
```
和
```
data.chainAddresses
```
：
```
data.records
```
是用户可控的文本元数据映射，而
```
data.chainAddresses
```
是按代币类型分类的结构化地址映射。当输入格式错误或结果不明确时，请阅读references/validation-and-errors.md。
总结结果并提出后续有用的调用建议，而不是仅返回原始JSON。对于
```
records/full_record
```
接口，相关字段按以下顺序说明：
```
name.*
```
，然后是
```
data.records
```
，最后是
```
data.chainAddresses
```
。

Endpoint Selection

端点选择

Use this quick routing map first:

Need a
```
nameHash
```
from a domain:
```
GET /utils/namehash/:domain
```

Need registration status from a

nameHash

tokenId

GET /utils/registered/:nameHashOrId

Need a resolved address from a domain:
```
GET /resolve/address/:domain
```
Need a primary name from an address:
```
GET /resolve/primary_name/:address
```
Need a primary name plus surfaced profile metadata from an address:
```
GET /resolve/profile/:address
```
Need historical resolved addresses for a domain:
```
GET /resolve/past_resolved/:domain
```
or range variant
Need expiry for a name:
```
GET /metadata/expiry/:nameHashOrId
```
Need the full HLN record payload:
```
GET /records/full_record/:nameHashOrId
```
Need the rendered SVG image:
```
GET /records/image/:tokenId
```
Need supported coin types:
```
GET /records/coin_types
```

Need owner or list queries:

GET /utils/all_names

GET|POST /utils/all_primary_names

, or

GET /utils/names_owner/:address

Need a signed mint pass:
```
POST /sign_mintpass/:label
```
when the developer is ready to continue promptly into the mint transaction

Read references/endpoints.md for the full endpoint catalog, request shapes, and response notes. Read references/integration.md when the user is integrating HL Names into a HyperEVM dApp or wallet flow.

使用此快速路由映射优先匹配：

需要从域名获取
```
nameHash
```
：
```
GET /utils/namehash/:domain
```

需要通过

nameHash

或

tokenId

查询注册状态：

GET /utils/registered/:nameHashOrId

需要通过域名解析得到地址：
```
GET /resolve/address/:domain
```
需要通过地址查询主域名：
```
GET /resolve/primary_name/:address
```
需要通过地址查询主域名以及展示的资料元数据：
```
GET /resolve/profile/:address
```
需要域名的历史解析地址：
```
GET /resolve/past_resolved/:domain
```
或范围查询变体
需要域名到期时间：
```
GET /metadata/expiry/:nameHashOrId
```
需要完整HLN记录payload：
```
GET /records/full_record/:nameHashOrId
```
需要渲染的SVG图片：
```
GET /records/image/:tokenId
```
需要支持的代币类型：
```
GET /records/coin_types
```

需要所有者或列表查询：

GET /utils/all_names

、

GET|POST /utils/all_primary_names

或

GET /utils/names_owner/:address

需要签名的mint pass：当开发者准备好立即继续铸造交易时，调用
```
POST /sign_mintpass/:label
```

阅读references/endpoints.md获取完整的端点目录、请求格式和响应说明。当用户需要将HL Names集成到HyperEVM dApp或钱包流程时，请阅读references/integration.md。

Guardrails

护栏规则

Apply these guardrails on every task:

Default read-only requests to production unless the user asks for testnet or a local environment.
Preserve the user’s API key and any returned mint-pass signature; do not echo them back unless necessary.
Treat
```
POST /sign_mintpass/:label
```
as a readiness check in a time-sensitive mint workflow. Request it when the developer is prepared to submit the mint transaction promptly, because the returned payload expires quickly.
Distinguish between “not found” and “bad input”; the API maps them differently.

每个任务都要应用以下护栏规则：

只读请求默认使用生产环境，除非用户要求使用测试网或本地环境。
保护用户的API密钥和任何返回的mint-pass签名；除非必要，否则不要回显这些信息。
将
```
POST /sign_mintpass/:label
```
视为时间敏感的铸造工作流中的就绪检查。仅当开发者准备好立即提交铸造交易时才请求该接口，因为返回的payload会快速过期。
区分“未找到”和“输入错误”；API对两者的返回映射不同。

Examples

示例

Happy path:

User asks: “What HLN profile is attached to
```
0x...
```
?”
Default to production unless the user asked for another environment.
Call
```
GET /resolve/profile/:address
```
.
Return the primary name and any surfaced profile metadata.
If the user wants the complete Data Records map or chain addresses, suggest
```
GET /records/full_record/:nameHashOrId
```
.

Full record interpretation:

User asks: “Is this
```
full_record
```
payload a fixed profile schema?”
Explain that
```
data.records
```
is a user-controlled metadata map and may include suggested keys like
```
Avatar
```
,
```
Twitter
```
,
```
Discord
```
,
```
Bio
```
,
```
REDIRECT
```
, or custom app-specific keys.
Contrast it with
```
data.chainAddresses
```
, which is the separate structured map of blockchain addresses by coin type.
If summarizing the payload, cover
```
name.*
```
first, then
```
data.records
```
, then
```
data.chainAddresses
```
.

Failure path:

User asks: “Resolve
```
jeff.eth
```
on HLN.”
Detect that the input is not an
```
.hl
```
domain before calling the API.
Explain that HLN endpoints validate
```
.hl
```
names and suggest the corrected target if the user intended
```
jeff.hl
```
.
If the user still wants a request attempted, expect a
```
422 Unprocessable Content
```
.

正常流程：

用户提问：“
```
0x...
```
绑定的HLN资料是什么？”
默认使用生产环境，除非用户要求其他环境。
调用
```
GET /resolve/profile/:address
```
。
返回主域名以及所有展示的资料元数据。
如果用户需要完整的数据记录映射或链上地址，建议调用
```
GET /records/full_record/:nameHashOrId
```
。

全记录解读：

用户提问：“这个
```
full_record
```
payload是固定的资料schema吗？”
解释
```
data.records
```
是用户可控的元数据映射，可能包含建议的键如
```
Avatar
```
、
```
Twitter
```
、
```
Discord
```
、
```
Bio
```
、
```
REDIRECT
```
，或者应用自定义的特殊键。
对比说明
```
data.chainAddresses
```
是独立的、按代币类型分类的区块链地址结构化映射。
如果要总结该payload，首先说明
```
name.*
```
字段，然后是
```
data.records
```
，最后是
```
data.chainAddresses
```
。

异常流程：

用户提问：“在HLN上解析
```
jeff.eth
```
。”
调用API前先检测输入不是
```
.hl
```
域名。
说明HLN端点会校验
```
.hl
```
域名，如果用户本意是查询
```
jeff.hl
```
，建议使用修正后的目标。
如果用户仍然要尝试发起请求，预期会返回
```
422 Unprocessable Content
```
。

References

参考文档

Load only what you need:

references/endpoints.md: endpoint catalog, request/response notes, and environment guidance
references/integration.md: HyperEVM dApp workflow, wallet integration pointers, and minting references
references/validation-and-errors.md: identifier validation rules, auth behavior, and error mapping

仅加载你需要的内容：

references/endpoints.md：端点目录、请求/响应说明和环境指南
references/integration.md：HyperEVM dApp工作流、钱包集成指引和铸造参考
references/validation-and-errors.md：标识符校验规则、鉴权逻辑和错误映射