HostNexFlow › Library › Crypto API rate limits, explained
Crypto API rate limits, explained: how a real token API meters you
Rate limits aren't punishment — they're the resource contract between an API and its callers. Using NexFlow's own /api/v1 as the worked example: who gets metered, what the lanes are, and how to stay under the cap you were actually given.
Ask most crypto APIs about their rate limits and you get a number — "100 requests per minute" — that turns out to be wrong the first time you actually load it. The honest version is a small contract: which lane you're in (anonymous, keyed, or paid), what the meter counts (per-IP, per-key, per-endpoint), and what the API does at the wall (429, slower responses, or a payment offer). NexFlow's public API at nexflowscan.com/api/v1/ is a clean worked example of all three lanes running at once, because the docs and the proxy code publish the actual mechanics rather than a marketing tier table.
This guide reads that contract the way an integrator should, so the surprises you do hit are the interesting kind.
Lane one: keyless access is metered per real client IP
The first lane costs nothing and needs no signup: call a /api/v1/ endpoint with no key and you ride a per-IP fair-use cap. Two details in that sentence matter more than the number. "Per-IP" means your NAT'd office, your cloud provider's shared egress, and every serverless function in your region may share one bucket — a keyless integration that works from your laptop can throttle from production without anything changing in your code. And "real client IP" means the service works hard to see through the proxy chain — the edge proxy forwards the true originating address rather than trusting a header, specifically so that the fair-use cap can't be trivially evaded by rotating X-Forwarded-For.
The practical read: the keyless lane is for exploration, evaluation, and low-volume tools. If your caller count or your audience is real, it is the wrong lane by construction — not because it's stingy, but because "shared IP" and "production traffic" collide somewhere you can't see.
Lane two: an API key moves the meter to your account
The x-api-key request header is the identity claim: the proxy forwards it to the upstream verbatim, and metering attaches to the key rather than the egress IP. That single change fixes the two keyless failure modes — your limit no longer depends on who shares your IP, and your limit becomes yours: visible in your account terms, stable across deploys, and independent of where your code runs.
Key hygiene matters for the same reason metering does: a leaked key lets someone else spend your limit. Keep keys server-side, scope them as tightly as the provider allows, and rotate on a schedule — a key in a shipped mobile app or a public GitHub repo is a fair-use bucket with a stranger's name on it.
Lane three: the x402 lane — no key, payment instead
NexFlow also runs a paid lane that skips API keys entirely: x402 endpoints answer an unpaid request with a 402 offer, and the client retries with a payment proof in a header — X-PAYMENT in the v1 transport, PAYMENT-SIGNATURE in the v2 — receiving the data plus a settlement receipt back in X-PAYMENT-RESPONSE. The rate limit in this lane is your wallet: every call is paid, so there's no cap to negotiate, only cost to optimize.
Two implementation details are worth knowing before you build on it. First, the proxy runs dual-stack header handling — both v1 and v2 payment header names pass through, so a client built on either transport version works on the canonical base. Second, charge-on-success: a 402 offer never charges you, and payment headers are deliberately stripped from HEAD requests — a HEAD is a metadata probe, never a purchase, so it always answers the offer rather than settling a payment for an empty body. If your health-checks probe endpoints with HEAD, they won't drain a balance.
Read the real contract: the machine-readable spec — every endpoint, every lane's rules — is live at nexflowscan.com/api/v1/openapi.json. When docs and behavior disagree, the OpenAPI document is what the proxy actually serves.
What the meter is actually protecting
Rate limits feel like friction until you look at what sits behind them. Token-risk endpoints do real work per call — contract reads, pool queries, holder analysis — and that work has a marginal cost per request that a flat subscription can absorb only if usage is bounded. The cap is what makes "unlimited free tier" claims elsewhere honest or not: an API that says unlimited but silently degrades hasn't removed the cap, it's hidden it in latency.
The x402 lane is the same physics stated differently: instead of bounding your usage to protect the resource, it prices each call so the resource pays for itself. Both are versions of the same contract — the question an API answers with its rate-limit design is "who pays for the marginal request," and there are only three candidates: everyone (fair-use caps), your account (keys), or the request itself (payments).
Timeouts are limits too
The meter isn't only about request counts — wall-clock is a resource. On this API, ordinary calls are bounded at roughly 60 seconds at the edge, while x402 paid calls get ~110: a paid request has real work to do (payment verification, settlement, and batch handlers that can return up to 10 verdicts) and killing it mid-settlement would charge you for a 502. The asymmetry is deliberate and it's a tell: a provider's timeout structure tells you which operations it considers worth the wall-clock spend.
For callers, the lesson is to design retries around idempotent failure, not just 429s. A request that times out may have already settled upstream — for paid lanes, retry blind and you can pay twice. Retry on 429 and connection errors; on timeout, reconcile first.
Staying under the cap you were given
The boring habits are the whole game. Cache aggressively and honestly — token risk data is a snapshot, not a stream, so re-scanning a contract that hasn't changed spends your limit on a byte-identical answer. Spread batch work over time rather than bursting; per-minute caps reward steady cadence. Use the paid lane for the calls that must land — a scanner you sell can't ride a shared-IP bucket. And build your client to see the limit: log the 429s and the retry-after hints rather than discovering the cap when a customer does.
The last habit is the least technical and the most skipped: read the openapi.json for the endpoints you're actually calling, not the tier table on the marketing page. The contract that's enforced is the one the proxy serves.
Where this lands in practice
If you're evaluating the API, start keyless — it's what the lane is for — and watch for the shared-IP ceiling before you design around it. If you're shipping a product on it, get a key; if your workload is spiky and your budget is per-call, the x402 lane prices that honestly. And if you're writing a scanner or dashboard that will sit on a busy shared egress — a cloud region, a VPN, a serverless platform — assume the keyless lane is invisible congestion and skip it entirely. The lanes are the contract; pick yours on purpose.
Frequently asked
What are the three ways to call the NexFlow API?
Keyless (metered per real client IP, for evaluation), keyed (x-api-key header — metering attaches to your account), and the x402 paid lane (no key — a 402 offer, then payment proof in a header, settlement receipt back).
Why did my keyless integration throttle in production but not in testing?
The keyless cap is per real client IP — shared egress (cloud regions, NAT, serverless platforms) means your production traffic may share a bucket with strangers. Testing from your laptop hits a bucket that's all yours.
What is the x402 lane?
A pay-per-call lane with no API key: unpaid requests get a 402 offer, the client retries with a payment proof (X-PAYMENT or PAYMENT-SIGNATURE), and gets data plus a settlement receipt. The rate limit is your wallet.
Do paid API calls have different timeouts?
Yes — ordinary calls are bounded near 60s at the edge; x402 paid calls get ~110s because payment verification and settlement take real wall-clock. Never blind-retry a timed-out paid call: it may have already settled.
Where's the machine-readable API spec?
nexflowscan.com/api/v1/openapi.json — every endpoint and lane rule, served by the proxy itself. When docs and behavior disagree, the OpenAPI document is what the API actually enforces.