Address unlocks
Buy an entity's address
CHARGES THE BALANCE the entity's band price (0 = free) and returns its address. Send the handle and maxPriceCents, the price shown (higher now: 409 price_changed, nothing charged). Paid unlocks are permanent. viaPlan uses the plan allowance instead. Spends 1 daily distinct-entity unit.
POST/v1/account/revealsAPI keySpends balance
Request body
entityIdstringrequired
The 12-character handle from the board. A raw address is refused (400) unless you already own it.
maxPriceCentsintegerrequired
Ceiling in cents: the price you were shown. 0 is a real cap (free band).
Allowed range: 0 <= x
viaPlanboolean
Unlock from the active plan allowance instead of buying.
Response
entityIdstring
The full 0x address.
labelstring
priceCentsinteger
Charged now (0 when free, from the plan, or already owned).
alreadyOwnedboolean
You already had it; nothing was charged.
viaPlanboolean
Responses
201Unlocked, or already owned (alreadyOwned: true, nothing charged). HTTP 201. A free unlock lasts only while the wallet stays in the free band.
400Missing/invalid maxPriceCents, unknown handle, or a raw address you do not own.
401No valid API key (missing, malformed, unknown or revoked).
402
error: insufficient_balance with priceCents and balanceCents; nothing charged.403Daily distinct-entity limit reached.
404Entity is not in any published window.
409
error: price_changed (priceCents, agreedCents) or error: plan_exhausted (limit, priceCents). Nothing charged.503Temporarily unavailable; nothing was charged. Retry shortly.