> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Open API access by default — add a Partner key for higher limits and analytics
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:
```bash theme={"system"}
curl https://api.hypermid.io/v1/chains
```
Or via any SDK with no `apiKey`:
```typescript theme={"system"}
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:
```bash cURL theme={"system"}
curl https://api.hypermid.io/v1/chains \
-H "X-API-Key: pk_live_yourkey"
```
```typescript TypeScript theme={"system"}
import { Hypermid } from "@hypermid/sdk";
const client = new Hypermid({
apiKey: process.env.HYPERMID_API_KEY,
});
```
```python Python theme={"system"}
from hypermid import Hypermid, HypermidConfig
import os
hm = Hypermid(HypermidConfig(api_key=os.environ["HYPERMID_API_KEY"]))
```
```go Go theme={"system"}
import hypermid "github.com/Hypermid/hypermid-sdk-go"
client := hypermid.New(&hypermid.Config{
APIKey: os.Getenv("HYPERMID_API_KEY"),
})
```
```rust Rust theme={"system"}
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
Apply at [partner.hypermid.io](https://partner.hypermid.io/login). 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](https://partner.hypermid.io/login).
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).
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:
```json theme={"system"}
{
"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:
```json theme={"system"}
{
"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
1. **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.
2. **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.
3. **Key rotation** — Rotate periodically and immediately if you suspect compromise. Rotation is one click in the partner portal's **API Keys** page.
4. **Monitor usage** — Check the partner dashboard for unexpected request patterns or geographic anomalies. Anything that doesn't match your traffic profile is worth investigating.