Hermes Aggregator Docs

Appearance

GET /v1/tokens/:identifier ​

Purpose ​

Fetches a single token by:

  • Numeric id (for example 0), or
  • instrumentId (for example USDCx).

When to Call ​

  • When resolving a token from route params.
  • When validating a previously stored token reference.

Request ​

  • Method: GET
  • Path: /v1/tokens/:identifier
  • Path param:
    • identifier: string

Response ​

200 OK returns one token object with the same shape as /v1/tokens items.

404 Not Found when no matching token exists:

json
{
  "error": "Token with identifier not-real not found"
}

Errors ​

  • 404 for unknown token identifier.
  • 429 Too Many Requests when rate limit is exceeded.

Integration Notes ​

  • URL-encode identifier in clients.
  • Default IP policy for /v1/tokens/:identifier is 60 requests per 60 seconds.
  • Need higher limits? Reach out on Discord.

Examples ​

Get by numeric ID:

bash
curl "https://api.hermes.ag/v1/tokens/0"

Get by instrumentId:

bash
curl "https://api.hermes.ag/v1/tokens/USDCx"
ts
const identifier = encodeURIComponent('USDCx');
const response = await fetch(`https://api.hermes.ag/v1/tokens/${identifier}`);
const payload = await response.json();

if (response.status === 404) {
  throw new Error('Token not found');
}

if (!response.ok) {
  throw new Error(JSON.stringify(payload));
}