Holovate
Coin service API reference
JSON over HTTPS, no API key for public reads, idempotent writes, and a public audit trail. Everything the Holovate frontend uses is documented here.
Last updated: 17 July 2026
The Holovate coin service is a small JSON-over-HTTPS API that powers wallets, the HVC ledger, land purchases, and DApp Studio reservations. Public endpoints require no API key.
Conventions
- Base URL:
https://holovate.space— all API routes live under/api/, plusGET /health. - Format: JSON requests and responses (
Content-Type: application/json). Request bodies over 1 MB are rejected. - Wallets: EVM-style
0x+ 40 hex characters. Addresses are normalized to lowercase. - Amounts: positive numbers, rounded to 6 decimal places.
- Land ids:
HV-001throughHV-096. - Idempotency: mutating endpoints honor an
Idempotency-Keyheader; identical retries return the original result. - Errors: non-2xx responses carry
{"error": {"code", "message", "details"}}.
Core endpoints
| Endpoint | Description |
|---|---|
GET /health | Service liveness, token symbol, and current ledger state hash. |
GET /api/coin/meta | Token configuration, wallet count, transaction count, state hash. |
POST /api/wallets | Create or update a wallet profile. Body: {wallet, name?, email?}. First sync pays the 3,200 HVC grant. |
GET /api/wallets/:wallet | Wallet balance, nonce, and owned lands. |
POST /api/transactions/faucet | Claim the 220 HVC daily faucet. Once per calendar day per wallet. |
POST /api/transactions/transfer | Move HVC between ledger wallets. Body: {from, to, amount, memo?}. |
POST /api/transactions/purchase-land | Buy a parcel. Body: {wallet, landId, price?}. Price is validated against the catalog; already-owned land is rejected. |
POST /api/services/reserve | Reserve a DApp Studio build. Body: {wallet, services: [ids]}. Creates a proposal — no payment. |
GET /api/transactions?wallet=0x...&limit=50 | Recent ledger transactions, optionally filtered by wallet (max 200). |
GET /api/ledger/audit | Public audit: state hash and wallet/land/transaction/proposal counts. |
# Inspect the ledger audit trail
curl -s https://holovate.space/api/ledger/audit
# Read a wallet
curl -s https://holovate.space/api/wallets/0x1111111111111111111111111111111111111111
# Claim the daily faucet (idempotent)
curl -s -X POST https://holovate.space/api/transactions/faucet \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-2026-07-17" \
-d '{"wallet":"0x1111111111111111111111111111111111111111"}'Catalog endpoints
| Endpoint | Description |
|---|---|
GET /api/parcels | The full 96-parcel catalog — id, district, biome, price, premium flag, and current ownership status. |
GET /api/services | The DApp Studio service catalog with USD estimates and HVC credits. |
Catalog endpoints ship with the current backend release; older deployments answer 404 not_found for them.
Mainnet plan endpoints
These endpoints are non-custodial: they only return unsigned transaction plans and recorded hashes. The service never holds keys and never submits transactions. Plan endpoints answer 409 contract_not_configured until operators configure a verified contract registry — no HVC contract is live on any public chain today.
| Endpoint | Description |
|---|---|
GET /api/mainnet/config?network=base | Network profile, configured contract addresses (if any), and ABIs. |
GET /api/mainnet/readiness | Per-network readiness: which of the five EVM profiles have a full contract set configured. |
POST /api/mainnet/intents/land-purchase | Unsigned approval + purchase plan for a parcel, priced from the catalog. |
POST /api/mainnet/intents/hvc-transfer | Unsigned ERC-20 transfer plan. |
POST /api/mainnet/transactions/register | Record a user-submitted transaction hash for bookkeeping. |
GET /api/mainnet/transactions?wallet=0x... | Recorded mainnet transaction hashes. |
Error codes
| Code | HTTP | Meaning |
|---|---|---|
wallet_required / wallet_invalid | 400 | Missing or malformed wallet address. |
amount_invalid | 400 | Amount is not a positive number. |
land_invalid | 400 | Land id is not in the HV-001…HV-096 range. |
services_required | 400 | No valid service ids supplied to a reservation. |
json_invalid | 400 | Request body is not valid JSON. |
faucet_claimed | 409 | Daily faucet already claimed today. |
insufficient_hvc | 409 | Balance too low for the requested amount. |
land_owned | 409 | Parcel already has an owner. |
price_mismatch | 409 | Submitted price differs from the catalog price. |
contract_not_configured | 409 | Mainnet contracts are not configured for that network. |
payload_too_large | 413 | Body exceeded 1 MB. |
not_found | 404 | Unknown endpoint or wallet. |
Questions or integration help: admin@holovate.space.