Environments and rate limits
Sandbox vs production base URLs, key prefixes, current rate limits, and how to request raises.
Environments and rate limits
Two environments. Two base URLs. Two key prefixes. The rules are simple, and they don't cross.
Environments
| Environment | Base URL | Key prefix | What it does |
|---|---|---|---|
| Sandbox | https://api.sandbox.blendfi.com.br | sk_test_… | Live mirror of the API. Pix payments are simulated, USDT transfers stay in test wallets. No real money moves. |
| Production | https://api.blendfi.com | sk_live_… | Real money. Real Pix. Real on-chain settlement. Issued only after compliance review of your sandbox integration. |
A sandbox key against api.blendfi.com returns 401 authentication_failed. A production key against api.sandbox.blendfi.com.br returns the same. The two environments share nothing: not data, not keys, not idempotency records, not webhook subscriptions.
Hard separation
When you go live, you re-create your webhook subscriptions and any persisted state in the production environment. Sandbox state does not copy over. This is intentional — it forces you to verify your production wiring before partners can transact.
Differences you'll feel
Pix is simulated in sandbox
In sandbox, you drive payment-received events with `POST /v1/test_helpers/transactions/{id}/pay`. In production, the Pix bank delivers them when your end user actually pays.
Test helpers don't exist in production
The `/v1/test_helpers/*` namespace is sandbox-only. Calls in production return `404`. Your code paths that call them must be flagged as test-only.
Compliance review gates production
We review your sandbox integration end-to-end (idempotency, error retries, webhook signature verification) before issuing your `sk_live_…` key.
Rate limits
| Endpoint | Limit | Window | Notes |
|---|---|---|---|
POST /v1/quotes | 60 | per minute | Per API key. Default; can be raised for production partners on request. |
| All other endpoints | (no explicit limit) | — | Subject to global abuse protections. Sustained sub-10 req/s per key is fine in sandbox. |
When you exceed a limit, the response is:
{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded for POST /v1/quotes (60/min).",
"request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}The response includes a Retry-After header in seconds. Honor it. If absent, back off exponentially starting at 1 second, capped at 30 seconds.
When to ask for a raise
Default limits are sized for development and small-volume launch. If you expect:
- More than 60 quotes/min on a single key in production — email us before launch, not during the incident.
- Sustained > 10 req/s aggregate across endpoints — same.
- Burst patterns (e.g. campaign launches, bulk reconciliation jobs) — flag them ahead of time so we can pre-warm.
Email us with: your expected steady-state rate, your peak rate, and the duration of expected peaks. We'll either raise the limit or suggest a different integration pattern (e.g. quote caching for the same user/amount).
Sandbox quirks worth knowing
State resets periodically. Sandbox data is wiped roughly every 30 days, so any users, transactions, or webhook subscriptions you created may disappear. Don't build long-lived integration tests against sandbox data — re-create test fixtures at the start of each suite.
Sumsub sandbox is also a mirror. When you reach the KYC flow, the Sumsub sandbox responds to test applicants we provision. Real CPFs in sandbox are encrypted and never sent to a production KYC backend.
Webhook delivery to localhost works. We support tunneling tools (ngrok, cloudflared, tailscale funnel) for sandbox webhook testing. Production webhooks must terminate at a publicly reachable HTTPS endpoint.
Rate limit headers are present in sandbox too. Use sandbox to verify your client-side throttling logic before you hit production limits.
Custom domains and IP allowlists
Production traffic from BlendFi originates from a published egress range. We can share the current list on request — useful if your inbound webhook receiver is behind an IP allowlist.
We don't currently offer custom domains for inbound traffic (you call api.blendfi.com, period). If your security model requires a tenant-specific endpoint, talk to us.
What to read next
Getting started
Sandbox key, first request, first user — the fastest path through both environments.
Errors and retries
Full retry policy, including what to do when you hit `rate_limit_exceeded`.
API reference
Per-endpoint specifics. Rate limits surfaced inline where they apply.
FAQ
Why is the production base URL not prod.api.blendfi.com or similar?
Production is the unmarked default — api.blendfi.com — so the URL doesn't broadcast "this is the boring, safe one" to anyone reading your code. Sandbox is the qualified subdomain.
Can I get a sandbox key and a production key on the same account? Yes — they're issued independently, both bound to the same organization. Most partners run them side by side: sandbox for staging tests, production for live traffic.
What happens if I accidentally use a sandbox key in my production app?
The sandbox key fails against api.blendfi.com with 401 authentication_failed. No real money is at risk; the call simply fails. Watch your error rate dashboards — a sudden spike of authentication_failed after a deploy is the canonical signal that an environment variable got mixed up.
Are the rate limits checked before or after authentication? After. We authenticate first, then count against the per-key budget. Anonymous traffic is rejected before it touches the limiter.
Does the limiter use a sliding window or a fixed window? Sliding window over 60 seconds. So 60 requests at the start of minute 1 followed by 60 at the start of minute 2 will not trip the limiter, but 60 in the last 30 seconds of minute 1 followed by another 60 in the first 30 seconds of minute 2 will.