> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-staging.coinflow.cash/_mcp/server.

# Rate Limits

| Limiter                                                  | Window     | Limit  |
| :------------------------------------------------------- | :--------- | :----- |
| [Global](#global-rate-limit)                             | 1 minute   | Varies |
| Coinflow Login by Email                                  | 90 seconds | 3      |
| Coinflow Login by MerchantID                             | 90 seconds | 3      |
| KYC                                                      | 1 minute   | 3      |
| Checkout JWT                                             | 10 minutes | 5      |
| Checkout Totals (per wallet and merchant)                | 1 minute   | 100    |
| NotFound                                                 | 10 seconds | 10     |
| Support Tickets (visible on Coinflow merchant dashboard) | 1 hour     | 60     |

## Global rate limit

Every API request counts against a global limit. Which budget a request uses depends on how it is authenticated:

| Authentication                                                       | Budget                                  | Limit per minute |
| :------------------------------------------------------------------- | :-------------------------------------- | :--------------- |
| A valid merchant API key in the `Authorization` header               | Shared by all requests using that key   | 250 by default   |
| Session key (`x-coinflow-auth-session-key`), wallet headers, or none | Shared by all requests from the same IP | 400              |

When a limit is exceeded, the API responds with `429 Too Many Requests`.

### Rate limit headers

Responses from rate-limited endpoints include these headers:

| Header                | Description                                        |
| :-------------------- | :------------------------------------------------- |
| `RateLimit-Limit`     | Your request budget for the current window         |
| `RateLimit-Remaining` | Requests left in the current window                |
| `RateLimit-Reset`     | Seconds until the window resets                    |
| `Retry-After`         | Sent with a `429`: seconds to wait before retrying |

Slow down when `RateLimit-Remaining` gets low, and after a `429`, wait `Retry-After` seconds before retrying.

Endpoints with their own limiter, such as login or KYC, also count against the global limit. On those endpoints the headers describe the endpoint's own limit, not the global one, so `RateLimit-Limit` can differ between endpoints. The NotFound limiter is the exception: its responses show the global values, and its `429` has no `Retry-After`.

### Raised merchant limits

If Coinflow has raised your merchant limit above the 400 per-IP budget, your server-to-server calls can use it on endpoints that take a session key. Send your merchant API key in the `Authorization` header alongside `x-coinflow-auth-session-key`, and those requests count against your merchant budget instead of the per-IP budget.

Your merchant budget is shared by every request using your key, across all of your servers. The per-IP budget applies to each server separately, so if your traffic comes from several servers, check that your merchant limit covers their combined traffic before switching.

> **Warning**
>
> Only send your merchant API key from your servers. Never include it in browser or mobile app code, where anyone can extract it. Requests made from your customers' browsers or devices should send only the session key.

If your server-to-server traffic needs more than these limits allow, contact your Coinflow integrations representative to request a higher merchant limit.