---
title: "Buy an entity's address"
method: POST
path: "/v1/account/reveals"
tags: ["Unlocks"]
---

# Buy an entity's address

`POST /v1/account/reveals`

## Request

- Base URL: `https://api.pmwallets.com`
- URL: `https://api.pmwallets.com/v1/account/reveals`
- Auth: API key in header `x-api-key`

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.

## Request body

- object
  - `entityId` string, required: The 12-character handle from the board. A raw address is refused (400) unless you already own it.
  - `maxPriceCents` integer, required: Ceiling in cents: the price you were shown. 0 is a real cap (free band).
  - `viaPlan` boolean: Unlock from the active plan allowance instead of buying.

## Response `201`

Unlocked, or already owned (alreadyOwned: true, nothing charged). HTTP 201. A free unlock lasts only while the wallet stays in the free band.

- UnlockResult
  - `entityId` string: The full 0x address.
  - `label` string
  - `priceCents` integer: Charged now (0 when free, from the plan, or already owned).
  - `alreadyOwned` boolean: You already had it; nothing was charged.
  - `viaPlan` boolean

## Other responses

- `400`: Missing/invalid maxPriceCents, unknown handle, or a raw address you do not own.
- `401`: No valid API key (missing, malformed, unknown or revoked).
- `402`: `error: insufficient_balance` with priceCents and balanceCents; nothing charged.
- `403`: Daily distinct-entity limit reached.
- `404`: Entity is not in any published window.
- `409`: `error: price_changed` (priceCents, agreedCents) or `error: plan_exhausted` (limit, priceCents). Nothing charged.
- `503`: Temporarily unavailable; nothing was charged. Retry shortly.

---

[API](https://skmtc.dev/pmwallets/apis/pmwallets-api.md) · [All operations](https://skmtc.dev/pmwallets/apis/pmwallets-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pmwallets/apis/pmwallets-api/revisions/d5023fb40430?raw)