HeroWallet Public API — Overview
Base URL:
https://api-p.herowallet.com
The HeroWallet Public API gives developers programmatic access to real-time blockchain and token data: supported chains, token catalogs, live market data, trending/gainers/losers lists, price history, and token logos — the same data that powers the HeroWallet app.
This document describes the product at a level that doesn't change release to release. It intentionally does not list specific endpoint paths, versions, parameters, or response shapes — those evolve between releases. For anything concrete, use the live docs below.
Where to Find the Actual API Docs
| Resource | Path | Purpose |
|---|---|---|
| Swagger UI | /swagger | Interactive, browsable API explorer — endpoints, parameters, try-it-out |
| OpenAPI spec | /openapi | Machine-readable schema — use to generate typed clients or drive a docs page |
| Health check | /health | Service liveness probe |
These paths are always open and considered stable. Any tooling that needs endpoint names, request/response shapes, or auth details (frontend reference pages, generated clients, etc.) should pull from /openapi at build/run time rather than hardcoding them — that way it stays correct automatically as the API evolves, with no hand-off needed.
What the API Covers
The data model is organized around these areas:
- Blockchains — which mainnet chains are currently supported, and per-chain metadata (name, logo, chain ID, wallet feature support).
- Feature support — which optional features (trending, new listings, gainers/losers, etc.) are available for a given chain. Always check this before rendering feature-dependent UI, since coverage varies by chain.
- Tokens — a searchable, paginated token catalog enriched with live market data (price, market cap, volume, liquidity), plus curated views (new listings, trending, high volume, high liquidity, top gainers, top losers).
- Token detail & history — full token profiles and OHLCV-style price/market-cap/volume history for charting.
- Token logos — a proxy that fetches and streams logo images from a fixed allowlist of trusted image hosts, solving CORS/hotlinking issues when rendering logos client-side.
New capabilities get added within these same areas over time; the exact endpoint names and fields are always in Swagger.
Authentication, at a Glance
Some parts of the API are open and require no credentials; others require an API key sent in a request header. Which endpoints fall into which category — and the exact header/scheme — can change between releases, so check /swagger or /openapi for the current rule rather than assuming.
Integration Pattern
The general shape of an integration, independent of specific endpoint names:
- Load reference data once and cache it — the chain list changes rarely; fetch it on startup and cache client-side.
- Check feature support for the selected chain before rendering chain-dependent UI (not every chain supports every feature).
- Fetch the data views you need (catalog, trending, gainers, etc.), optionally in parallel.
- Proxy all logo URLs through the token-logo endpoint rather than hitting external CDNs directly from the browser.
- Attach credentials (where required) to every request — see
/swaggerfor which calls need them.
Operational Notes
| Topic | Detail |
|---|---|
| Caching | Reference and catalog data is cached server-side and refreshed on a short interval — don't poll faster than necessary. |
| Rate limiting | API traffic is rate limited. Limits differ by endpoint and may change between releases; a 429 response indicates the limit was hit. |
| Timestamps | All timestamps are UTC, ISO 8601. |
| Pagination | List endpoints that support pagination follow a consistent page/page-size convention. |
| Response format | All endpoints return application/json, except the logo proxy, which streams raw image bytes. |
For the Frontend Team
This document is meant to be stable enough to build a one-time "API overview" page from — the product story and data areas above don't change often.
For anything dynamic (endpoint list, parameters, example requests/responses, auth requirements per endpoint), pull from the live OpenAPI spec at /openapi rather than duplicating it here, so the page stays correct across releases without needing a new copy of this file each time.