Skip to main content

Name Resolving

Resolve a Name​

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

Endpoint​

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

Path Parameters​

ParameterTypeRequiredDescription
{name}stringYesThe PIVX name to resolve (e.g., richard.pivx).

Request Body​

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

ParameterTypeDefaultDescription
extendedbooleanfalseIf true, additionally returns created_block_id, updated_block_id and domain_tx (the hash of the transaction of the name's latest operation).
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. updated_block_id comes with it as well.

Code Examples​

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

Response Example

{
"response": {
"domain_name": "richard.pivx",
"target_address": "ps1zu2xyry4rc5j0trs3w9zqr5ayhw8h3ulhsfw4reufcg8c62gpg3rzcj7tkasn7tlwgc9y4emwtq",
"owner_pubkey": "ba17d58e11e9828a4ffc140560730ce1b410c924043c1d60cf52a127bde47544",
"price": 750000000000,
"nonce": 1793384994,
"created_block_id": 5648982,
"domain_tx": "a1003dace6ed2ea966aba28926c6ecb7cb5436229db329ce72d118d2cf502d66",
"updated_block_id": 5649418,
"smt_root": "5613850a42087074b88a35dfd6c878d53267f6fa571438026a437c059cbc8245",
"merkle_proof": [
"5a9acd90db63c21d8eff4b656d4526c1bb4b5f9f5e7cf6c5a22719c4d8854bec",
"0000000000000000000000000000000000000000000000000000000000000000",
"d8f11c6213a091087e5bcf8aeac624c7f768d9436af9b6883880155e28e3f4a7",
"ed05b1037b96221bda47b2dd76aa37a93f3d39cb336f8e6f8a203f8fb1ea2a98",
"3af379894717ec7000caf91fcd2bf0e570fda54befa24f5a5770275728dcb11e",
"50e173401bd419424082e3cb2caf9ee62e0808e79e8c8ade99d3396f35e995ce",
"4c1b349c97b95c712f4777b357de9ff1535aad68bb7c56134273a88fefe8bef5",
"3695b047cfbd47f93c899c03736d085924a23ba48d51a6db8382bb2a7452c4b6",
"badcf46ab543cb4a9a1ad7335a07b87d8ede6dc241cf4b4168894f4822f08325",
"e33ad310acd0cc3f5a4261ed6a24615e60e91de423a8ace2f6716c0b60aa351c"
],
"proof_depth": 10,
"proof_terminal": "Occupied",
"checkpoint": {
"idx": 31,
"block_id": 5671618,
"smt_root": "5613850a42087074b88a35dfd6c878d53267f6fa571438026a437c059cbc8245"
}
}
}

This is an answer of indexer.pivx.name to the request above, at checkpoint 31 (PIVX block 5671618). The root changes with every new batch of operations, so a later request may return another smt_root and other siblings; this answer still folds to its own root with the code on Verifying Proofs.

FieldTypeDescription
domain_namestringThe registered name
target_addressstringTarget PIVX 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 PIVX block_id
updated_block_idintdomain last update PIVX block_id
domain_txstringThe PIVX transaction hash of the name's latest operation: its registration, until the name is updated, transferred, listed, unlisted or bought
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 PIVX 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 PIVX Address to perform a reverse resolving:

GET/POST https://indexer.pivx.name/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.pivx.name/v1.0/resolve/owner/{Ed25519_public_key}

The POST params are described above.

Paging the Lists​

The reverse and owner lookups answer one page of names at a time, in name order (A to Z). Two more POST parameters page through them:

ParameterTypeDefaultDescription
countinteger500Names per page, 1 to 500. A larger value is cut to 500.
afterstring—The last name of the page before: this page starts after it. Leave it out for the first page.

A page holding count names may have more after it: ask again with after set to its last name. A shorter page is the last one, and a page past the last name is an empty list, [].

curl -X POST https://indexer.pivx.name/v1.0/resolve/owner/{Ed25519_public_key} \
-H "Content-Type: application/json" \
-d '{"count": 100, "after": "alice.pivx"}'