Use HL Names API

Consult & operate against the Hyperliquid Names API. Use when your agent needs to resolve `.hl` names, reverse-resolve addresses, fetch HLN profiles or recor...

Security Scan

The skill is internally consistent: it documents and instructs only HL Names API interactions, asks for no unrelated credentials, and includes optional eval/run scripts that align with the described purpose.

Purpose & Capability

Name, description, SKILL.md, README, and reference docs all consistently describe resolving .hl names, profiles, records, and mint-pass workflows; required capabilities (HTTP calls to api.hlnames.xyz) match that purpose and no unrelated cloud or platform credentials are requested.

Instruction Scope

SKILL.md instructions focus on selecting HLN endpoints, validating identifiers, and interpreting responses. They do not instruct reading unrelated host files or exfiltrating data. Guardrails limit actions (e.g., don't broadcast transactions) and recommend preserving user keys.

Install Mechanism

No install/spec that downloads or executes remote code is present; the repository is instruction-first with optional local eval scripts. No high-risk install URLs or archive extraction are used.

Credentials

The skill requires no mandatory env vars. The repo and runner provide an optional HLN_API_KEY and include a hard-coded fallback public agent key (NILB2EY-R4LUDOA-WN5G5JQ-KHAQOLA) used when no key is supplied. The eval runner also references model provider keys (OPENAI_API_KEY, VENICE_API_KEY, ANTHROPIC_API_KEY) for running tests—these are optional and only for the provided evaluation tooling, not required by the skill itself.

Persistence & Privilege

always:false and normal autonomous invocation allowed. The skill does not request system-wide config paths or claim to modify other skills. The provided scripts operate locally and are typical for an eval/test harness.

Assessment

This skill appears coherent and limited to HL Names API usage. Notes before installing or running: 1) The repo includes a public fallback API key embedded in scripts/docs — it's intended as a convenience fallback, not a secret; if you have a private HLN_API_KEY set it via .env (HLN_API_KEY). 2) The eval runner (runner/run.sh) will call external model provider APIs if you run it and therefore needs your provider keys (OPENAI_API_KEY, VENICE_API_KEY, etc.) — do not run the eval runner unless you intend to provide those credentials. 3) The skill will make live HTTP calls to api.hlnames.xyz (or testnet/local URL if requested); review responses before sharing them, since profile/records fields are user-controlled. 4) If you want extra assurance, inspect the small shell scripts included (runner/*, scripts/*) before executing them locally; they are for evaluation and not required for the agent to use the API guidance.

Use 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.

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

Workflow

1. Determine the data source you actually need. Use the narrowest public endpoint that answers the request.
2. 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.
3. 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.
4. Call the endpoint with the correct method and headers.
5. 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.
6. 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.

Endpoint Selection

Use this quick routing map first:

• Need a nameHash from a domain: GET /utils/namehash/:domain
• Need registration status from a nameHash or 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.

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.

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.

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