JSON-RPC Reference
The ZNS indexer exposes a read-only JSON-RPC 2.0 API with four methods: resolve, list_for_sale, status, and events.
The canonical spec is openrpc.json, also served at /openrpc.json. Use the explorer below to hit a live indexer, or point any OpenRPC code generator at the spec URL to scaffold a typed client.
For curl and language examples without the SDK, see Direct RPC. For signature verification, see Signature Scheme.
Hosted endpoints:
| Network | URL |
|---|---|
| Testnet | https://light.zcash.me/zns-testnet |
| Mainnet (beta) | https://light.zcash.me/zns-mainnet-test |
OpenRPC 1.3.2
ZNS Indexer API
v0.1.0 · MIT
Local: http://127.0.0.1:3000
resolve
Look up a name or address registration
Resolves a ZNS registration by name or by Zcash unified address. If the query is a valid Zcash address, returns an array of all registrations bound to that address (one address may own multiple names). If the query is a name, returns a single registration object or null if not found.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | yes | A ZNS name (e.g. "alice") or a Zcash unified address |
Result - registration
For name queries: a single ResolveResult or null. For address queries: an array of ResolveResult.
one of
ResolveResult
Registration
| Field | Type | Description |
|---|---|---|
| name* | string | The registered name. Must be 1-62 characters of lowercase ASCII letters and digits only. No hyphens, no underscores, no unicode. Used verbatim in signature pre-images. |
| address* | string | Zcash unified address bound to this name. Used verbatim (byte-for-byte) in signature pre-images. |
| txid* | string | Transaction ID of the registration memo |
| height* | integer | Block height at which the registration was confirmed |
| nonce* | integer | Replay-protection counter, incremented on each UPDATE/DELIST. Reset to 0 on BUY. Used verbatim (decimal ASCII) in signature pre-images for UPDATE and DELIST. |
| signature | string | null | Ed25519 admin signature over the most recent action that wrote this row, encoded as standard base64 with padding (88 characters). The pre-image template is determined by `last_action`. See the 'Signature Verification' section in the API description for encoding rules, all templates, and the full verification procedure. |
| last_action* | "CLAIM" | "UPDATE" | "DELIST" | "BUY" | The action that produced the current `signature`. Selects the pre-image template used for signature verification. See the 'Signature Verification' section in the API description for all templates and the full verification procedure. |
| pubkey | string | null | Ed25519 public key of the sovereign owner, encoded as standard base64 with padding (44 characters). Identifies the entity that performed the action recorded in `last_action`. |
| Field | Type | Description |
|---|---|---|
| listing | Listing | null | Active listing if the name is for sale, otherwise null |
Array of ResolveResult
ResolveResult
Registration
| Field | Type | Description |
|---|---|---|
| name* | string | The registered name. Must be 1-62 characters of lowercase ASCII letters and digits only. No hyphens, no underscores, no unicode. Used verbatim in signature pre-images. |
| address* | string | Zcash unified address bound to this name. Used verbatim (byte-for-byte) in signature pre-images. |
| txid* | string | Transaction ID of the registration memo |
| height* | integer | Block height at which the registration was confirmed |
| nonce* | integer | Replay-protection counter, incremented on each UPDATE/DELIST. Reset to 0 on BUY. Used verbatim (decimal ASCII) in signature pre-images for UPDATE and DELIST. |
| signature | string | null | Ed25519 admin signature over the most recent action that wrote this row, encoded as standard base64 with padding (88 characters). The pre-image template is determined by `last_action`. See the 'Signature Verification' section in the API description for encoding rules, all templates, and the full verification procedure. |
| last_action* | "CLAIM" | "UPDATE" | "DELIST" | "BUY" | The action that produced the current `signature`. Selects the pre-image template used for signature verification. See the 'Signature Verification' section in the API description for all templates and the full verification procedure. |
| pubkey | string | null | Ed25519 public key of the sovereign owner, encoded as standard base64 with padding (44 characters). Identifies the entity that performed the action recorded in `last_action`. |
| Field | Type | Description |
|---|---|---|
| listing | Listing | null | Active listing if the name is for sale, otherwise null |
null
Errors
- -32602 Invalid params: missing 'query'
list_for_sale
Get all names currently listed for sale
Returns every name that has an active marketplace listing, ordered by block height descending (newest first). Prices are in zatoshis.
Parameters
None
Result - listings
ListForSaleResult
| Field | Type | Description |
|---|---|---|
| listings* | Listing[] | All active listings, newest first |
status
Get indexer synchronization status
Returns the current state of the ZNS indexer, including the latest synced block height, the admin public key used for signature verification, the UIVK being watched, counts of registered names and active listings, and the current pricing tiers.
Parameters
None
Result - status
StatusResult
| Field | Type | Description |
|---|---|---|
| synced_height* | integer | Latest block height the indexer has processed |
| admin_pubkey* | string | Ed25519 public key (32 raw bytes) used to verify all signed assertions in this API, encoded as standard base64 with padding (44 characters). See the 'Signature Verification' section in the API description for the full verification procedure. |
| uivk* | string | Unified incoming viewing key the indexer watches for memos |
| address* | string | Zcash unified address corresponding to the watched UIVK |
| registered* | integer | Total number of registered names |
| listed* | integer | Number of names currently listed for sale |
| pricing* | object | null | Current pricing configuration, or null if SETPRICE has never been issued. NOTE: this object carries no signature and cannot be cryptographically verified via this endpoint. See the 'Verifying pricing' subsection in the API description for details on how clients can obtain a trust-minimized view of pricing. |
events
Query the activity log with optional filters
Returns historical ZNS events (CLAIM, LIST, DELIST, RELEASE, UPDATE, BUY, SETPRICE) with optional filtering by name, action type(s), and block height. Results are ordered by block height descending. Supports pagination via limit and offset.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | no | Filter events for a specific name |
| action | "CLAIM" | "LIST" | "DELIST" | "RELEASE" | "UPDATE" | "BUY" | "SETPRICE" | no | Filter by a single action type |
| since_height | integer | no | Only return events after this block height |
| limit | integer | no | Maximum number of events to return (default 50, max 500) |
| offset | integer | no | Number of events to skip for pagination (default 0) |
Result - events
EventsResult
| Field | Type | Description |
|---|---|---|
| events* | Event[] | Matching events, newest first |
| total* | integer | Total number of matching events (before limit/offset) |
Schemas
Reusable types referenced by the methods above.
Registration
A ZNS name registration
A ZNS name registration
| Field | Type | Description |
|---|---|---|
| name* | string | The registered name. Must be 1-62 characters of lowercase ASCII letters and digits only. No hyphens, no underscores, no unicode. Used verbatim in signature pre-images. |
| address* | string | Zcash unified address bound to this name. Used verbatim (byte-for-byte) in signature pre-images. |
| txid* | string | Transaction ID of the registration memo |
| height* | integer | Block height at which the registration was confirmed |
| nonce* | integer | Replay-protection counter, incremented on each UPDATE/DELIST. Reset to 0 on BUY. Used verbatim (decimal ASCII) in signature pre-images for UPDATE and DELIST. |
| signature | string | null | Ed25519 admin signature over the most recent action that wrote this row, encoded as standard base64 with padding (88 characters). The pre-image template is determined by `last_action`. See the 'Signature Verification' section in the API description for encoding rules, all templates, and the full verification procedure. |
| last_action* | "CLAIM" | "UPDATE" | "DELIST" | "BUY" | The action that produced the current `signature`. Selects the pre-image template used for signature verification. See the 'Signature Verification' section in the API description for all templates and the full verification procedure. |
| pubkey | string | null | Ed25519 public key of the sovereign owner, encoded as standard base64 with padding (44 characters). Identifies the entity that performed the action recorded in `last_action`. |
Listing
A marketplace listing for a registered name
A marketplace listing for a registered name
| Field | Type | Description |
|---|---|---|
| name* | string | The listed name. Same constraints as `Registration.name`. Used verbatim in the LIST signature pre-image. |
| price* | integer | Asking price in zatoshis (1 ZEC = 100,000,000 zatoshis). Used verbatim (decimal ASCII, no padding) in the LIST signature pre-image. |
| nonce* | integer | Replay-protection nonce used in the LIST signature pre-image. Used verbatim (decimal ASCII) to reconstruct `LIST:{name}:{price}:{nonce}`. |
| txid* | string | Transaction ID of the listing memo |
| height* | integer | Block height at which the listing was confirmed |
| signature* | string | Ed25519 admin signature over the pre-image `LIST:{name}:{price}:{nonce}`, encoded as standard base64 with padding (88 characters). See the 'Signature Verification' section in the API description for encoding rules and the verification procedure. This signature must be verified independently of any enclosing `Registration.signature`. |
ResolveResult
A registration with optional listing info
Registration
A ZNS name registration
| Field | Type | Description |
|---|---|---|
| name* | string | The registered name. Must be 1-62 characters of lowercase ASCII letters and digits only. No hyphens, no underscores, no unicode. Used verbatim in signature pre-images. |
| address* | string | Zcash unified address bound to this name. Used verbatim (byte-for-byte) in signature pre-images. |
| txid* | string | Transaction ID of the registration memo |
| height* | integer | Block height at which the registration was confirmed |
| nonce* | integer | Replay-protection counter, incremented on each UPDATE/DELIST. Reset to 0 on BUY. Used verbatim (decimal ASCII) in signature pre-images for UPDATE and DELIST. |
| signature | string | null | Ed25519 admin signature over the most recent action that wrote this row, encoded as standard base64 with padding (88 characters). The pre-image template is determined by `last_action`. See the 'Signature Verification' section in the API description for encoding rules, all templates, and the full verification procedure. |
| last_action* | "CLAIM" | "UPDATE" | "DELIST" | "BUY" | The action that produced the current `signature`. Selects the pre-image template used for signature verification. See the 'Signature Verification' section in the API description for all templates and the full verification procedure. |
| pubkey | string | null | Ed25519 public key of the sovereign owner, encoded as standard base64 with padding (44 characters). Identifies the entity that performed the action recorded in `last_action`. |
| Field | Type | Description |
|---|---|---|
| listing | Listing | null | Active listing if the name is for sale, otherwise null |
ListForSaleResult
| Field | Type | Description |
|---|---|---|
| listings* | Listing[] | All active listings, newest first |
Event
A single ZNS activity event
A single ZNS activity event
| Field | Type | Description |
|---|---|---|
| id* | integer | Auto-incrementing event ID |
| name* | string | The name this event relates to. Follows the same pattern as `Registration.name` for name-scoped actions (CLAIM, UPDATE, BUY, LIST, DELIST, RELEASE). Empty string for SETPRICE events, which are not scoped to a specific name. |
| action* | "CLAIM" | "LIST" | "DELIST" | "RELEASE" | "UPDATE" | "BUY" | "SETPRICE" | The type of action that occurred. Selects the pre-image template for verifying `signature`. See the 'Signature Verification' section in the API description for all templates. |
| txid* | string | Transaction ID that triggered this event |
| height* | integer | Block height at which this event was confirmed |
| ua | string | null | Relevant address: claimer (CLAIM), owner (LIST), new address (UPDATE), buyer (BUY). Null for DELIST, RELEASE, and SETPRICE. Used verbatim in the signature pre-image as the `{address}` field for CLAIM/UPDATE/BUY. |
| price | integer | null | Price in zatoshis. Present for LIST and BUY; null otherwise. Used verbatim (decimal ASCII) in the LIST signature pre-image. |
| nonce | integer | null | Replay-protection nonce used in the signed payload. Present for LIST, DELIST, RELEASE, UPDATE, and SETPRICE. Used verbatim (decimal ASCII) in the signature pre-image. |
| signature | string | null | Ed25519 admin signature over the event's pre-image, encoded as standard base64 with padding (88 characters). The pre-image template is determined by `action`. Present for all action types. See the 'Signature Verification' section in the API description for all templates and the verification procedure. |
| pubkey | string | null | Ed25519 public key of the sovereign owner who performed this action, encoded as standard base64 with padding (44 characters). Present only for name-scoped actions (CLAIM, LIST, DELIST, UPDATE, BUY, RELEASE) that were signed by a user rather than the admin. Null for admin-signed actions and SETPRICE events. |
EventsResult
| Field | Type | Description |
|---|---|---|
| events* | Event[] | Matching events, newest first |
| total* | integer | Total number of matching events (before limit/offset) |
StatusResult
| Field | Type | Description |
|---|---|---|
| synced_height* | integer | Latest block height the indexer has processed |
| admin_pubkey* | string | Ed25519 public key (32 raw bytes) used to verify all signed assertions in this API, encoded as standard base64 with padding (44 characters). See the 'Signature Verification' section in the API description for the full verification procedure. |
| uivk* | string | Unified incoming viewing key the indexer watches for memos |
| address* | string | Zcash unified address corresponding to the watched UIVK |
| registered* | integer | Total number of registered names |
| listed* | integer | Number of names currently listed for sale |
| pricing* | object | null | Current pricing configuration, or null if SETPRICE has never been issued. NOTE: this object carries no signature and cannot be cryptographically verified via this endpoint. See the 'Verifying pricing' subsection in the API description for details on how clients can obtain a trust-minimized view of pricing. |
Last updated on