Transaction limits

BlendFi caps transaction volume in two layers: a per-transaction cap that applies to every operation on the platform, and a per-user daily/monthly ceiling resolved from a server-managed tier. Every conversion (onramp and offramp) goes through both checks at quote accept. If either is exceeded, the call fails with transaction_limit_exceeded (HTTP 422), no reservation is made, and the conversion is not created. All limits are in BRL.

The two layers

Checks run in order: platform cap first, then per-user. The first layer to be exceeded is the one named in the response.

Platform per-transaction cap

A single BRL value sets the maximum amount any one operation can carry, end to end. It applies to every quote accept on the platform. BlendFi does not publish the exact value; it is sized to absorb partner traffic and rarely affects an individual partner.

The cap is per-transaction, not per-day. It only checks the size of this operation, not how much has been moved in the day or month. That is what the per-user tier handles.

Per-user tier

Every end customer is bound to a limit tier (for example tier_0, tier_1, and so on). The tier carries:

• A daily BRL ceiling: the sum of the user's conversions in the current day (Brasília time).
• A monthly BRL ceiling: the sum of the user's conversions in the current month.

A newly created user is assigned the default tier. The tier can be raised later through a review by the BlendFi team (see How to request a raise).

You do not see the tier id on the user response. The information you can observe today is:

• The user's risk_profile, returned on GET /v1/users/:id and GET /v1/users. The profile is set server-side by the platform KYC questionnaire and reflects the segment the user fits into; it is informational and is not a setter you can write.
• The transaction_limit_exceeded error when an operation would push the user over the ceiling (see What the error looks like).

Transaction flow

When you accept a quote, BlendFi runs both checks before reserving any volume:

The amount that counts toward the ceiling is the BRL value of the operation at quote accept. For onramp, that is expected_source_amount. For offramp, that is the target BRL amount carried by the quote.

Daily and monthly reset

The daily counter resets at midnight Brasília time. The monthly counter resets on the first day of the month, Brasília time.

Cancellation, expiry, and failure

When a conversion is canceled (POST /v1/conversions/:id/cancel) or ends in expired or failed, the reserved volume is released back to the user's counters. A conversion that never settled does not eat into the ceiling.

The release is best-effort: in the rare case the release call fails, the counters self-correct on the next reset window. You do not have to retry anything from your side.

What the error looks like

{
  "code": "transaction_limit_exceeded",
  "message": "Transaction amount exceeds the platform per-transaction cap.",
  "request_id": "01KPR9F6MM8G147177J7ZQPJHG"
}

The code is stable: match on transaction_limit_exceeded. The message identifies the layer:

How to request a raise

The per-user tier can be raised through a review by the BlendFi team. There are two channels:

Partner API (preview)

POST /v1/users/{user_id}/limit-upgrade-requests is the partner-facing channel. It is the endpoint your integration will call when the limit-upgrade review flow ships. Today the endpoint returns 501 limit_upgrade_not_available so you can wire it up ahead of time; it will start accepting submissions in a future release. Until then, use the manual channel below.

When the endpoint is enabled, it accepts the user id on the path and an Idempotency-Key header. No body is required to initiate the request; the BlendFi team reviews the user's history and contacts you about the outcome.

Manual channel

To raise a user today, reach out to the BlendFi team with:

• The user_id whose tier should be revised.
• The target daily and monthly volume for that user, in BRL.
• Any context that justifies the raise (steady-state volume, expected peaks, business-model change).

Platform-wide caps are revised the same way and on a different cadence.

FAQ

Do limits apply in sandbox? Yes. Sandbox uses platform and user limits. Use it to verify your handling of transaction_limit_exceeded before going to production.

Is it the quote amount or the settled amount that counts? The BRL value at quote accept. For onramp, expected_source_amount. For offramp, the target BRL on the quote. Divergences between expected and received (offramp under or over-funded) do not change what was already counted; the release on terminal failure or cancellation brings the counter back.

Two simultaneous quote-accepts for the same user that together exceed the ceiling, which one passes? The first to reserve passes. The second receives 422 transaction_limit_exceeded. The check and reserve are atomic.

How do I know how much of a user's ceiling has been consumed? There is no public endpoint that returns consumption today. If you need this for an internal dashboard or alert, contact the BlendFi team.

Can I change a user's tier? Not directly. The tier is server-managed; partners request a review (see How to request a raise) and BlendFi applies the change.

Why is risk_profile on the user response if I cannot set it? It is a server-side classification carried over from the platform KYC. It is informational, useful for your own segmentation, and may shift between KYC submissions. It does not determine the tier; the tier is a separate assignment.

Read next