Skip to content

HLnames/use-hln-api / skills/use-hln-api

use-hln-api

Verified

Consult & operate against the Hyperliquid Names API. Use when your agent needs to resolve `.hl` names, reverse-resolve addresses, fetch HLN profiles or records, inspect owner or list queries, diagnose HLN API failures, prepare a mint-pass request, or guide HyperEVM dApp integration with HL Names.

FileKindSize
SKILL.mdskill md7.1 KB
references/endpoints.mdmarkdown5.1 KB
references/integration.mdmarkdown3.4 KB
references/validation-and-errors.mdmarkdown3.0 KB

references/endpoints.md

View on GitHub
# HLN API Endpoints

## Base URLs

- Production API: `https://api.hlnames.xyz/`
- Production Swagger docs: `https://api.hlnames.xyz/api/docs/`
- Testnet API: `https://api.testnet.hlnames.xyz/`

The Swagger UI is publicly browsable without an API key. API routes still require `X-API-Key`.

## Endpoint Catalog

| Goal | Method + Path | Input | Response Notes |
| --- | --- | --- | --- |
| Hash a domain | `GET /utils/namehash/:domain` | `.hl` domain | Returns `{ "nameHash": "0x..." }` |
| Check registration | `GET /utils/registered/:nameHashOrId` | nameHash or tokenId | Returns `{ "registered": true|false }` |
| List names | `GET /utils/all_names?begin=0&end=999` | optional range | Returns array of `{ name, namehash, tokenid }`; defaults to range `0..999` |
| List names for owner | `GET /utils/names_owner/:address` | address string | Prefer normalized addresses |
| List primary names | `GET /utils/all_primary_names?begin=0&end=999` | optional range | Returns array of `{ address, primaryName, namehash, tokenid }` |
| List primary names for addresses | `POST /utils/all_primary_names` | Optional JSON body `{ "addresses": ["0x..."] }` | Swagger documents an optional `addresses` array request body; do not combine it with `begin`/`end` because the server returns `400` |
| Resolve domain to address | `GET /resolve/address/:domain` | `.hl` domain | Returns `{ "address": "0x..." }` |
| Reverse-resolve address | `GET /resolve/primary_name/:address` | EVM address | Returns `{ "primaryName": "name.hl" }` |
| Fetch profile | `GET /resolve/profile/:address` | EVM address | Swagger shows `primaryName` and `avatar`; real responses may also surface additional user-controlled profile metadata |
| Fetch resolution history | `GET /resolve/past_resolved/:domain` | `.hl` domain | Returns array of `{ blockNumber, resolvedAddr }` |
| Fetch resolution history in range | `GET /resolve/past_resolved/:domain/:blockNumStart/:blockNumEnd` | `.hl` domain and numeric block range | Returns array of `{ blockNumber, resolvedAddr, previousResolvedAddr? }` |
| Fetch expiry | `GET /metadata/expiry/:nameHashOrId` | nameHash or tokenId | Returns `{ "expiry": "1771416632" }` as a stringified number |
| Fetch full record | `GET /records/full_record/:nameHashOrId` | nameHash or tokenId | Returns `{ name, data }` with text records and `chainAddresses` |
| Fetch rendered image | `GET /records/image/:tokenId` | tokenId | Returns `{ "image": "data:image/svg+xml;base64,..." }` |
| Fetch supported coin types | `GET /records/coin_types` | none | Returns `{ "coinTypes": [0, 60, 501] }` |
| Mint-pass signing | `POST /sign_mintpass/:label` | label path param | Returns `{ label, sig, timestamp, token, amountRequired }` per the Swagger example |

## Public Docs Baseline

- Swagger examples are intentionally illustrative, not exhaustive.
- Data Records are user-controlled. Treat additional returned metadata fields as valid unless the API indicates an error.
- Suggested/default-style Data Records called out in the consulted docs and session include `Avatar`, `Twitter` or `X`, `Discord`, `Bio`, `REDIRECT`, and `CNAME`.

## Response Interpretation Notes

- `resolve/profile` is the best single-call profile lookup when the user starts from an address.
- Swagger’s example for `resolve/profile` is minimal. In practice, this route may surface additional user-controlled profile metadata beyond `primaryName` and `avatar`.
- `records/full_record` is the richest public response. It contains:
  - `name.owner`
  - `name.controller`
  - `name.resolved`
  - `name.name`
  - `name.expiry`
  - `data.records`
  - `data.chainAddresses`
- Interpret `data.records` as the free-form, user-controlled metadata dictionary.
- Interpret `data.chainAddresses` as the separate structured address map keyed by coin type, not as part of the text-record schema.
- `records/image` requires a tokenId, not a nameHash. Convert first if needed.
- `metadata/expiry` currently returns `"0"` for unregistered names rather than a successful-looking future timestamp.

## Practical Call Patterns

- Need profile data from an address:
  - Call `GET /resolve/profile/:address`
- Need the complete Data Records map or chain addresses for a name:
  - Call `GET /utils/namehash/:domain`
  - Then call `GET /records/full_record/:nameHashOrId`
- Need owner or list queries:
  - Call `GET /utils/names_owner/:address`, `GET /utils/all_names`, or `GET|POST /utils/all_primary_names`
- Need primary names for a specific address set:
  - Call `POST /utils/all_primary_names` with JSON body `{ "addresses": ["0x...", "0x..."] }`
  - Do not send `begin` or `end` in the same request
- Need historical resolution context:
  - Call `GET /resolve/past_resolved/:domain/:blockNumStart/:blockNumEnd`
  - Use `previousResolvedAddr` to describe transitions
- Need a minting preflight:
  - Validate the label first
  - Confirm the developer is ready to continue promptly into the mint transaction
  - Call `POST /sign_mintpass/:label`
  - Expect Swagger’s documented response fields: `label`, `sig`, `timestamp`, `token`, and `amountRequired`
  - Treat the payload as short-lived input for immediate onchain minting rather than a long-lived credential
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall