API Conventions

Every endpoint on api.superhero.com is plain JSON over HTTPS. The rules below (base URLs, pagination, shared query parameters, units, errors, rate limits and the signature-based write flow) apply everywhere and are not repeated on the endpoint pages.

Base URLs

Both hosts serve the same paths. Every path is relative to the base and begins with /api/. The only versioned prefix is /api/v2/mdw/*, the indexed chain mirror. See Node & Middleware.

Outside production the server also serves Swagger UI at /api and the OpenAPI 3 document at /api-json.

Authentication

Reads need no credentials. No API key, bearer token, cookie or session:

curl -s "https://api.superhero.com/api/tokens?limit=3&order_by=market_cap&order_direction=DESC"

Writes are authorised by wallet signature. There is no login endpoint and no token to store. Every mutating flow is three steps:

1. POST the challenge endpoint with your ak_... address. It returns a nonce (or verification_token), a human-readable message and an expiry.
2. Sign message with the private key for that address.
3. POST the submit endpoint with the nonce, the signature and the value you are claiming.

The server verifies the signature against the address in the request. Endpoints that use this pattern:

Each claim flow has a matching unclaim and unclaim/submit pair, signed the same way. See Profile for request bodies.

The notification feed uses a bearer session token. One wallet signature is exchanged for a token, which is then sent as a normal Authorization: Bearer header:

POST /api/notifications/{address}/feed/challenge   ->  { nonce }
sign the message                                   ->  signature
POST /api/notifications/{address}/feed/session     ->  { token, expiresAt }
GET  /api/notifications/{address}/feed?limit=50    ->  Authorization: Bearer {token}

GET /api/notifications/web-push/vapid-public-key is public and needs no token.

Two endpoints take an API key. POST /api/trending-tags and PATCH /api/dex/tokens/{address}/listed accept it as either header:

x-api-key: YOUR_KEY
Authorization: Bearer YOUR_KEY

A missing or wrong key is a 401.

POST /api/affiliations takes no credential. It accepts a sender_address and a list of codes and returns a generated ten-character affiliation code. Its sibling POST /api/affiliations/invites/{code}/{provider}/{access_code} verifies access_code with GitHub, Google or X before handing out a private invite code.

Pagination

Most list endpoints return items plus meta:

{
  "items": [],
  "meta": {
    "currentPage": 1,
    "itemCount": 20,
    "itemsPerPage": 20,
    "totalItems": 4213,
    "totalPages": 211
  }
}

Pass page (1-based) and limit to walk it.

The limit cap is 100

100 is both the default and the maximum. What happens when you exceed it depends on the endpoint family:

Read meta.itemsPerPage rather than assuming your limit was honoured. page on /api/v2/mdw/* is capped at 1,000,000.

Invalid order_by

Most list endpoints hold an allow-set and return 400 Invalid order_by value: {value} for anything outside it. GET /api/tokens is the exception: an unrecognised order_by falls back to market_cap and an unrecognised order_direction to DESC, with no error.

Responses that are not the envelope

The analytics series endpoints return bare arrays and the totals endpoints return a scalar or a small object. See Analytics.

Shared query parameters

Parameter casing

Query keys are mostly snake_case, with exceptions. An unrecognised key returns unfiltered data rather than an error, so match the spelling per endpoint:

Currency conversion

Endpoints that accept convertTo take one of ae (default), usd, eur, aud, brl, cad, chf, gbp, xau. The same nine keys make up the PriceDto object returned wherever a value has a price:

{ "ae": 0.0421, "usd": 0.0013, "eur": 0.0011, "aud": 0.002,
  "brl": 0.0071, "cad": 0.0018, "chf": 0.001, "gbp": 0.00097, "xau": 0.0000004 }

Live AE fiat rates come from GET /api/coins/aeternity/rates, a flat map of lowercase currency code to number.

Units

The API mixes two conventions. Values in trade records and OHLC candles are in whole units (AE, whole tokens). Values read live from a contract (a token's market_cap, total_supply and dao_balance) are raw (aettos, base units).

market_cap therefore means two different scales depending on where you read it: on a token it is aettos, on a transaction or an OHLC candle it is AE. They differ by exactly 1e18.

Every key of a PriceDto is on the same scale as its ae key. Each fiat key is ae * rate[code], not a re-denomination: if ae is in aettos, so is usd. When rates are unavailable every key except ae is null.

decimals is a string in TokenDto, not a number. Parse it before using it as an exponent. Most numeric token fields are strings for the same reason: they are big integers that do not survive a double.

Errors

Failures are ordinary HTTP status codes with a JSON body carrying statusCode, message and error.

Request bodies and DTO-bound query parameters (the leaderboard, portfolio history) are validated strictly: an unknown property is a 400, and declared types are coerced ("5" becomes 5). Individually bound query parameters (most list endpoints) ignore unrecognised keys silently.

Rate limits

retryAfter is a field in the JSON body, in seconds. There is no Retry-After header and no X-RateLimit-* headers. Because the key includes the route path, the budget is spent separately on each guarded endpoint.

Guarded routes

Everything else (tokens, transactions, accounts, analytics, DEX, posts, trending tags, affiliations, search and feed) is unthrottled. Poll considerately and prefer the WebSocket for change notification.

CORS

Allowed methods are GET, POST, PUT, PATCH, DELETE, OPTIONS. A browser page on any origin can call api.superhero.com directly. The same setting governs the Socket.IO gateways. Responses are gzipped.

Caching

Several endpoints are served from an in-process cache rather than recomputed per request:

Some values are recomputed on a schedule: token performance and rank every five minutes, the daily analytics rows hourly, AE fiat rates every ten minutes, and trending scores as described on Trending.

Versioning and deprecation

There is no version negotiation. The OpenAPI document declares version 1.0, GET /api/stats reports the deployed package version as apiVersion, and no header or path segment selects a version. /api/v2/mdw/* is a name inherited from the middleware's own API.

Deprecation is by annotation. A retired parameter keeps validating and stops having an effect:

Related

• API Reference: the full endpoint index
• Tokens API: the TokenDto these unit rules apply to, field by field
• Accounts API: the portfolio and leaderboard endpoints with the camelCase date parameters
• Profile API: the challenge/signature write flow end to end
• Node & Middleware: when the REST API does not have the data