Validators
Package validators is one-click validator onboarding: prove your Genesis NFT, get a node provisioned, queue its registration.
Package validators is one-click validator onboarding: prove your Genesis NFT, get a node provisioned, queue its registration.
| Base URL | https://api.hanzo.ai |
| Operations | 4 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
validators
Returns one claimed validator slot, scoped to the caller's org.
GET /v1/validators/{tokenId}
Returns one claimed validator slot, scoped to the caller's org.
A slot another org holds, and a slot nobody holds, are both 404 — never a different status, so this route cannot be used to probe which slots are taken.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
tokenId | path | string | yes | TokenID is the slot's GenesisNFT token id, from the path, as a decimal string. |
Issues the single-use nonce and the exact message a wallet must sign to claim a validator slot.
GET /v1/validators/challenge
Issues the single-use nonce and the exact message a wallet must sign to claim a validator slot.
The nonce is bound to (validated org, slot) and stored server-side, so a signature obtained for one org or one slot can never be replayed for another, and the message POST /v1/validators verifies is rebuilt from those same server facts rather than trusted from the caller. Redeem it with POST /v1/validators before it expires; it can be redeemed once.
A tokenId outside the Validator tier is refused here rather than after signing.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
tokenId | query | string | — | TokenID is the Validator-tier GenesisNFT token id, as a decimal string in the ?tokenId= query. |
Returns the validator slots the caller's org has claimed.
GET /v1/validators
Returns the validator slots the caller's org has claimed.
One entry per claimed slot with its node identity, its live-ish node status and the owner-gated registration queued for it, if any. Slots are org-scoped by the validated identity, so a caller can only ever see their own — a slot claimed by another org is not merely hidden from this list, it is unreachable through the whole surface.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | string | — | Limit is how many slots to return, as a decimal string in the ?limit= query. |
Claims a validator slot and provisions its node, after proving the caller's wallet owns the slot's NFT.
POST /v1/validators
Claims a validator slot and provisions its node, after proving the caller's wallet owns the slot's NFT.
The pipeline, all server-enforced: burn the single-use challenge (so a replayed or forged nonce dies before any chain read), recover the signer from the message this server rebuilds, require that wallet to hold Validator-tier GenesisNFT #tokenId on Ethereum mainnet, generate a fresh luxd staking identity and seal it into KMS, write a LuxNetwork CR for a NEW node, and ENQUEUE an owner-gated registration. The registration is never auto-submitted to any P-Chain — the owner co-signs it out of band — and the stake weight is set at co-sign time, never derived from the NFT.
It fails CLOSED at every gate: a bad signature, a non-owner, a non-tier slot or an unavailable KMS all leave no claim persisted and no key material exposed. Re-claiming a slot this org already holds re-applies the node CR and returns 200 with the existing identity (keys and NodeID are stable); a slot held by another org is 409. A cluster-less deployment still claims the slot, seals the keys and queues the registration, reporting the node as "node_pending".
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
nonce | string | — | Nonce is the value GET /v1/validators/challenge issued for this slot. |
signature | string | — | Signature is the wallet's personal_sign over the challenge message, hex with a 0x prefix. |
tokenId | integer | — | TokenID is the Validator-tier GenesisNFT token id being claimed. |
How is this guide?