Skip to main content

Name Resolving

Resolve a Name​

Resolves a ZCash name to retrieve its associated ZCash Address, its proof details, synchronization checkpoints, and registration data.

Endpoint​

GET https://indexer.zcashnames.co/v1.0/resolve/{name} (Just name resolving)
POST https://indexer.zcashnames.co/v1.0/resolve/{name} (If additional parameters are required)

Path Parameters​

ParameterTypeRequiredDescription
{name}stringYesThe ZCash name to resolve (e.g., richard.zcash).

Request Body​

The request body must be a JSON object containing the following parameters:

ParameterTypeDefaultDescription
extendedbooleanfalseIf true, additionally returns domain_tx (the TX hash of the domain registration).
with_checkpointbooleanfalseIf true, also returns checkpoint: the anchored checkpoint whose root (the same as smt_root) this proof was built against. It is null while a sync is being committed; repeat the request.

Code Examples​

curl -X POST https://indexer.zcashnames.co/v1.0/resolve/richard.zcash \
-H "Content-Type: application/json" \
-d '{
"extended": true,
"with_checkpoint": true
}'

Response Example

{
"response": {
"domain_name": "bob.zec",
"target_address": "u146xylzx0uygtu0f2ae0p67w0229vm8h756aurrhsjpsfpyxy20ustc62xhtc9a4xrr734u5nndw0kzzav7vt57qh95yvwqktpqcfvkwx",
"owner_pubkey": "1111111111111111111111111111111111111111111111111111111111111111",
"price": 250000000,
"nonce": 1780000002,
"smt_root": "5892c31e50ad3a4cf0407b91b3012a196d60c4e4f53e37261ac6747dea180eea",
"merkle_proof": [
"29bc98ae3a939618e50ba72e11a25ba30b37bb53a168a17463b9ef3fe90495d8",
"0000000000000000000000000000000000000000000000000000000000000000"
],
"proof_depth": 2,
"proof_terminal": "Occupied"
}
}
FieldTypeDescription
domain_namestringThe registered name
target_addressstringTarget ZCash address
owner_pubkeystringPublic key of the name owner
priceintprice tag (used for Marketplace)
nonceintincremental nonce
smt_rootstringThe Merkle tree root (hex) the proof was built against, in every answer
merkle_proofstring[]sibling hashes, hex; [0] is deepest. Length equals proof_depth
proof_depthintnumber of siblings — verify it equals merkle_proof.length
proof_terminalstring | object"Occupied", "Vacant" or {"Blocked":{…}} — see below
extended:
created_block_idintdomain creation ZCash block_id
updated_block_idintdomain last update ZCash block_id
domain_txstringThe ZCash transaction hash of the name registration
with_checkpoint:Fields inside "checkpoint" (null while a sync is being committed):
idxintIndex of the root in the anchor contract’s rootAt mapping (0 is the genesis root); the resume cursor for checkpoint discovery
block_idintThe ZCash block_id the checkpoint covers
smt_rootstringThe checkpoint's root (hex) — the same as smt_root above

proof_terminal​

Describes what sits at the end of the proof path, which is what lets a proof show absence as well as presence:

ValueMeaning
"Occupied"the name's own leaf is there — a successful resolution. Reject any resolution whose terminal is not this.
"Vacant"an empty subtree is there — the name is unregistered
{"Blocked": {"record": {…}}}a different name's leaf occupies that position, so the queried name is unregistered. The blocking record is included in full so you can verify the claim rather than trust it.

A name the indexer does not know is answered with the error Domain not found, without a proof: the API does not return Vacant or Blocked proofs yet, so a "not found" is the indexer's word. Check it with a second indexer before relying on it.

Verification code for all of this, in Python, PHP and JavaScript, is on Verifying Proofs.

Reverse Name Lookup​

Provide a ZCash Address to perform a reverse resolving:

GET/POST https://indexer.zcashnames.co/v1.0/resolve/reverse/{address}

The POST params are described above.

Names by Owner​

All names owned by a given Ed25519 public key.

GET/POST https://indexer.zcashnames.co/v1.0/resolve/owner/{Ed25519_public_key}

The POST params are described above.