api reference

Coming soon. The API is not live. The contract below is published now so launchpads, token pages and treasuries can build against it before the endpoint is available; the shape will not change without notice here.

Principles

The API is read-only, unauthenticated and free. It exposes nothing that is not already derivable from the chain — it exists so that integrators do not each have to re-implement the eligibility and coverage rules to display a status.

Every response can be reproduced from the deployed contracts listed on Contracts. Treat the API as a convenience, not as a source of truth.

Base URL

https://api.hera.money/v1

Draft. The final host will be published here and on Contracts when the endpoint goes live.

Coverage status

Returns whether a token on Arc is currently covered.

GET /v1/coverage/{tokenAddress}

Parameter	In	Description
tokenAddress	path	The token's contract address on Arc, 0x-prefixed. Case-insensitive.

Response

{
  "token": "0x…",
  "status": "covered",
  "asOfBlock": 4182663,
  "checks": {
    "minimumAge": true,
    "minimumVolume": true,
    "activeLossEvent": false
  },
  "reserve": {
    "balanceUsdc": "…",
    "perEventCapUsdc": "…"
  }
}

Field	Meaning
status	One of covered, not_covered, under_review. See below.
asOfBlock	The Arc block the answer was computed at.
checks	The individual conditions behind the status, so an integrator can show why a token is not covered.
reserve	The reserve balance and the per-event cap at asOfBlock, so a partner can show capacity alongside status.

Status values

Value	Meaning
covered	The token clears the minimum age and volume, and has no active loss event. Eligible holders would be settled if one were verified.
under_review	The token is being assessed against the minimums, or a loss event has been declared and the dispute window is open.
not_covered	The token does not clear the minimums, or coverage has been withdrawn.

covered is a statement about the token, not about any individual holder. A holder's own eligibility still depends on the conditions in Eligibility.

Errors

Status	Body	When
400	{ "error": "invalid_address" }	The path parameter is not a valid address.
404	{ "error": "unknown_token" }	The address is not a token contract on Arc, or has never traded.
429	{ "error": "rate_limited" }	Too many requests. Limits to be published.

Badge

The same status, as an image, for pages that cannot run code.

GET /v1/badge/{tokenAddress}.svg

Returns the "Covered by HERA" badge in the state matching the token's current status, with Cache-Control set to a short lifetime so an embedded badge stays current. Until this endpoint is live, embed the static badge described in Partner Badge.

Versioning

The path is versioned (/v1). Fields may be added to a response without a version change; fields will not be removed or change meaning within a version.

Not in scope

There is no write API. Coverage cannot be requested, purchased or configured through it: a token is covered because it meets the published conditions, and the API only reports that.