Authentication

Hypermid uses an open access model: every endpoint works without authentication on the anonymous tier. Partner API keys are optional — they unlock higher rate limits, custom fee terms, webhook events scoped to your traffic, and the Partner Dashboard.

Access tiers

	Anonymous	Partner
Signup required	No	Yes
Rate limit — heavy endpoints (`quote`, `execute`, `routes`, `status`)	30 req/min	2,000 req/min
Rate limit — read endpoints (`chains`, `tokens`, `balances`, `gas`, `tools`, `connections`, `ping`)	240 req/min	6,000 req/min
Fee terms	Default tier	Custom / negotiable
Partner Dashboard	—	✓
Analytics & transactions	—	✓
Webhooks	—	✓
Priority support	—	✓

The split-bucket design lets cache-friendly reads (chains, balances) be high-volume without burning the heavy budget that hits paid upstreams.

Anonymous access

No authentication is required. Just call the API:

curl https://api.hypermid.io/v1/chains

Or via any SDK with no apiKey:

import { Hypermid } from "@hypermid/sdk";
const client = new Hypermid();

Anonymous traffic is rate-limited per IP. The 30/min heavy + 240/min read split is designed for typical human-driven widget usage and indie projects. If you need more headroom, register for a partner key.

Partner access

To use a partner key, send it in the X-API-Key header on every request:

curl https://api.hypermid.io/v1/chains \
  -H "X-API-Key: pk_live_yourkey"

import { Hypermid } from "@hypermid/sdk";

const client = new Hypermid({
  apiKey: process.env.HYPERMID_API_KEY,
});

from hypermid import Hypermid, HypermidConfig
import os

hm = Hypermid(HypermidConfig(api_key=os.environ["HYPERMID_API_KEY"]))

import hypermid "github.com/Hypermid/hypermid-sdk-go"

client := hypermid.New(&hypermid.Config{
    APIKey: os.Getenv("HYPERMID_API_KEY"),
})

use hypermid_sdk::{Hypermid, HypermidConfig};

let client = Hypermid::new(HypermidConfig {
    api_key: Some(std::env::var("HYPERMID_API_KEY")?),
    ..Default::default()
});

Keys are prefixed pk_live_ followed by a random ID — e.g. pk_live_a1b2c3d4e5f6g7h8. Treat the full value as a secret.

Getting a partner key

Request access

Apply at partner.hypermid.io. Partner accounts are reviewed and provisioned by the Hypermid team — typical turnaround is 1–2 business days. You’ll receive a magic-link email once approved.

Use the magic link, then log in any time at partner.hypermid.io/login.

Copy your API key

Go to API Keys in the partner portal. Your Primary key is shown there — copy the full pk_live_... value once and store it securely (env var or secret manager).

Use it

Include the key in the X-API-Key header on every API call, or pass it to the SDK constructor.

Treat partner keys as secrets. Never expose them in frontend JavaScript, mobile apps, browser extensions, or public repositories. All authenticated API calls should originate from your backend server. If a key is ever leaked, rotate it immediately from the API Keys page.

Rate limits

Every response includes rate-limit headers in meta.rateLimit. Use these to back off proactively before you hit a 429:

{
  "data": { ... },
  "error": null,
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": 1711234567,
    "rateLimit": {
      "limit": 2000,
      "remaining": 1872,
      "reset": 1711234627
    }
  }
}

Field	Description
`limit`	Maximum requests allowed in the current 60s window for this tier+bucket
`remaining`	Requests remaining in the current window
`reset`	Unix timestamp (seconds) when the window resets

The limit field reflects whichever bucket your call landed in — heavy or read — so the same key may show different limits on different endpoints in the same minute.

Hitting a 429

When you exceed the limit, you get HTTP 429 with a RATE_LIMIT error:

{
  "data": null,
  "error": {
    "code": "RATE_LIMIT",
    "message": "Rate limit exceeded. Retry after the reset timestamp.",
    "details": {}
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": 1711234567,
    "rateLimit": {
      "limit": 2000,
      "remaining": 0,
      "reset": 1711234627
    }
  }
}

Use meta.rateLimit.reset (Unix seconds) to compute exact backoff. Most SDKs handle this automatically — see the per-language docs for retry behaviour.

Security best practices

Server-side only — Never include your API key in frontend JavaScript, mobile apps, or any client-side code. Use the anonymous tier for client-side calls; route partner-authenticated traffic through your backend.
Environment variables — Store keys in env vars or a secret manager (1Password / Vault / AWS Secrets Manager), never in source code or config files committed to git.
Key rotation — Rotate periodically and immediately if you suspect compromise. Rotation is one click in the partner portal’s API Keys page.
Monitor usage — Check the partner dashboard for unexpected request patterns or geographic anomalies. Anything that doesn’t match your traffic profile is worth investigating.

Getting Started

Guides

Resources

Access tiers

Anonymous access

Partner access

Getting a partner key

Rate limits

Hitting a 429

Security best practices

​Access tiers

​Anonymous access

​Partner access

​Getting a partner key

​Rate limits

​Hitting a 429

​Security best practices

Access tiers

Anonymous access

Partner access

Getting a partner key

Rate limits

Hitting a 429

Security best practices