Hermes Aggregator Docs

Appearance

5-Minute Quickstart ​

This guide walks through the minimum integration sequence:

  1. Load tokens.
  2. Load providers.
  3. Request a quote.
  4. Read quote results and errors.

Base URLs ​

  • Production API: https://api.hermes.ag

Prerequisites ​

  • HTTP client (curl, fetch, or equivalent)

API Limits ​

Default IP limits are applied per route:

  • /v1/tokens: 30 requests per 60 seconds
  • /v1/tokens/:identifier: 60 requests per 60 seconds
  • /v1/providers: 60 requests per 60 seconds
  • /v1/quote: 30 requests per 60 seconds

Use response headers (RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) to track your current budget.

If you need higher limits, reach out on Discord.

1) Fetch Tokens ​

Use /v1/tokens to get token metadata and the instrumentAdmin values required for quote requests.

bash
curl "https://api.hermes.ag/v1/tokens"
ts
const tokensResponse = await fetch('https://api.hermes.ag/v1/tokens');
if (!tokensResponse.ok) throw new Error(`tokens failed: ${tokensResponse.status}`);
const tokens = await tokensResponse.json();

2) Fetch Providers ​

Use /v1/providers to get provider IDs you can pass to whitelistedProviders in quote requests.

bash
curl "https://api.hermes.ag/v1/providers"
ts
const providersResponse = await fetch('https://api.hermes.ag/v1/providers');
if (!providersResponse.ok) throw new Error(`providers failed: ${providersResponse.status}`);
const providers = await providersResponse.json();

3) Request a Quote ​

Call /v1/quote with required params:

  • inputInstrumentId
  • inputInstrumentAdmin
  • outputInstrumentId
  • outputInstrumentAdmin
  • amount (positive decimal string)
  • recipient

Example:

bash
curl "https://api.hermes.ag/v1/quote?inputInstrumentId=Amulet&inputInstrumentAdmin=DSO::1220b1431ef217342db44d516bb9befde802be7d8899637d290895fa58880f19accc&outputInstrumentId=USDCx&outputInstrumentAdmin=decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef&amount=10&recipient=user-address"
ts
const params = new URLSearchParams({
  inputInstrumentId: 'Amulet',
  inputInstrumentAdmin:
    'DSO::1220b1431ef217342db44d516bb9befde802be7d8899637d290895fa58880f19accc',
  outputInstrumentId: 'USDCx',
  outputInstrumentAdmin:
    'decentralized-usdc-interchain-rep::12208115f1e168dd7e792320be9c4ca720c751a02a3053c7606e1c1cd3dad9bf60ef',
  amount: '10',
  recipient: 'user-address',
});

const quoteResponse = await fetch(`https://api.hermes.ag/v1/quote?${params.toString()}`);
const quotePayload = await quoteResponse.json();

if (!quoteResponse.ok) {
  throw new Error(JSON.stringify(quotePayload));
}

4) Read Success and Error Responses ​

Success response shape:

  • requestId: string
  • totalTimeMs: number
  • swapType: "exactIn"
  • platformFeeBps: number
  • quotes: QuoteItem[]

Notes:

  • quotes can be empty when providers fail or no route is available.
  • Quotes are sorted by best outAmount first.
  • Each quotes[i] is a QuoteItem (one executable route variant).
  • Execute by branching on quote.execution.executionMode:
    • magicAddress: send to quote.execution.transferAddress without memo.
    • transfer: send to quote.execution.transferAddress and include quote.execution.memo.
  • Re-fetch a quote when amount, token pair, provider filter, or recipient changes.

Validation error (400) shape:

json
{
  "error": "Invalid quote request",
  "details": [
    {
      "field": "amount",
      "message": "amount must be a positive decimal string"
    }
  ]
}

Rate limit error (429) shape:

json
{
  "error": "Too Many Requests",
  "details": "Rate limit exceeded for this route"
}

Responses also include rate-limit headers:

  • RateLimit-Policy
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After (only on 429)

Next Step ​

Go to the Quote endpoint reference for full request and QuoteItem and execution-mode details.