Rate Limits

Every endpoint under https://api.namefi.io/v-next is rate limited per account. The limit is shared across all backend instances, so it holds no matter which server handles your request.

The limit

60 requests per minute, per account.
The window is a rolling 60 second window.
The limit applies to the whole v-next surface combined, not per endpoint.

Response headers

Every response (including 429s) carries these headers so you can pace your requests without guessing:

Header	Meaning
`RateLimit-Limit`	How many requests you get in the 1 minute window.
`RateLimit-Remaining`	How many requests are remaining in the current window.
`RateLimit-Reset`	Seconds until the current window resets.

When you are over the limit, the API also returns a standard Retry-After header (in seconds) alongside the 429.

When you exceed the limit

A request over the limit responds with HTTP 429 Too Many Requests:

{ "error": "Too Many Requests" }

Read Retry-After (or RateLimit-Reset) and wait that many seconds before retrying.

Reading the headers

The SDK abstracts raw responses away, so read the RateLimit-* headers from a direct fetch/requests call (or inspect them with cURL).

const res = await fetch('https://api.namefi.io/v-next/balance', {
  headers: { 'x-api-key': process.env.NAMEFI_API_KEY! },
});

console.log('Limit', res.headers.get('RateLimit-Limit'));
console.log('Remaining', res.headers.get('RateLimit-Remaining'));
console.log('Reset (s)', res.headers.get('RateLimit-Reset'));

if (res.status === 429) {
  const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
  console.log(`Rate limited, retry in ${retryAfter}s`);
}

Backing off on `429`

A small helper that retries once Retry-After has elapsed:

import { setTimeout as sleep } from 'node:timers/promises';

async function withRetry(url: string, init: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, init);

    if (res.status !== 429) {
      return res;
    }

    const retryAfter = Number(
      res.headers.get('Retry-After') ?? res.headers.get('RateLimit-Reset') ?? 1,
    );
    await sleep(retryAfter * 1000);
  }

  throw new Error('Rate limit exceeded after retries');
}

const res = await withRetry('https://api.namefi.io/v-next/balance', {
  headers: { 'x-api-key': process.env.NAMEFI_API_KEY! },
});