> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumx.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Autoconversion Rules
> Automatically convert incoming fiat deposits to stablecoin with a standing rule
An autoconversion rule runs a standing conversion for you: set it up once and every matching transaction is converted automatically, with no per-transaction API call. Rules convert **fiat deposits to stablecoin**. You share the deposit details with your customer, and each matching deposit (a PIX transfer using those details, for example) is converted to USDC or USDT and delivered on-chain.
Rules are tied to an [account](/concepts/accounts) issued by a Lumx banking partner. The account's currency defines the source currency of the conversion; the rule defines the target asset and network. Autoconversion is available for BRL and MXN accounts for now.
Stablecoin-to-fiat rules, converting a stablecoin deposit in a wallet to fiat, are coming. This guide covers the fiat-to-stablecoin direction available today.
## How it works
1. You create a rule for an account, choosing the target asset, network, purpose, and a name.
2. The response includes deposit details (`sourceDepositInfo`): for a BRL account, a PIX `brCode`. Share it with whoever is sending the funds.
3. Every deposit paid through it is matched to the rule and converted to the target asset.
4. You receive webhooks as each conversion moves through its lifecycle.
You can create and view rules in the [Dashboard](https://dashboard.lumx.io) (open the customer's page and go to the **Autoconversion Rules** tab) or through the API. The sections below cover the API flow.
## Create a rule
Send a `POST` request to `/autoconversion-rules`.
```bash Request theme={null}
curl -X POST https://api-sandbox.lumx.io/autoconversion-rules \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"accountId": "44dd9734-176a-4ced-924f-103f8d50ea5e",
"targetCurrency": "USDC",
"blockchain": "POLYGON",
"purpose": "INVESTMENT",
"name": "BRL → USDC investment"
}'
```
```json Response theme={null}
{
"id": "c7f64332-5d53-4685-8aa9-48a5348c18c2",
"accountId": "44dd9734-176a-4ced-924f-103f8d50ea5e",
"partnerFeeId": "123e4567-e89b-12d3-a456-426614174004",
"status": "ACTIVE",
"provider": "STARKBANK",
"sourceCurrency": "BRL",
"targetCurrency": "USDC",
"blockchain": "POLYGON",
"purpose": "INVESTMENT",
"sourceDepositInfo": [
{
"rail": "PIX",
"brCode": "00020126...5204",
"depositIdentifier": "IIDCDYjYUTbKouEUOyvxZ3xnU"
}
],
"createdAt": "2026-07-08T23:18:58.574Z"
}
```
### Request fields
| **Field** | **Required** | **Description** |
| :--------------- | :----------- | :-------------------------------------------------------------------------------------------------------------- |
| `accountId` | Yes | Account that receives the deposits. Must belong to your project |
| `targetCurrency` | Yes | Asset to convert into: `USDC` or `USDT` |
| `purpose` | Yes | End-use category of the funds (see [Transaction purpose](/concepts/transactions#transaction-purpose)) |
| `name` | Yes | A label for the rule, visible only to you |
| `blockchain` | No | Network for delivery: `ETHEREUM`, `POLYGON`, `BASE`, or `TRON`. Falls back to your project's default blockchain |
| `partnerFeeId` | No | [Partner fee](/concepts/partner-fees) applied to each conversion. Must belong to your project |
### Share the deposit details
`sourceDepositInfo` carries everything the sender needs, per rail. What you share depends on the account's currency:
| **Currency** | **Rail** | **Deposit details** | **How the sender pays** |
| :----------- | :------- | :-------------------------------------- | :------------------------------------------------------------ |
| BRL | PIX | Static PIX QR code (`brCode`) | Scans the QR or pastes the code, which embeds the reference |
| MXN | SPEI | CLABE (`clabe`) plus memo (`reference`) | Transfers to the CLABE with the memo as the payment reference |
The `depositIdentifier` (PIX) or `reference` (SPEI) is what matches a deposit to the rule. It's embedded in the PIX `brCode` and passed as the SPEI memo. Any deposit paid with it is converted.
### Errors
| **Status** | **Cause** |
| :--------- | :-------------------------------------------------------------------------------------------------- |
| `400` | `name` empty or missing, invalid enum value, or no `blockchain` set and your project has no default |
| `403` | Account or partner fee belongs to another project |
| `404` | Account or partner fee not found |
## Retrieve a rule
Fetch a single rule, including its current `sourceDepositInfo`, with `GET /autoconversion-rules/{id}`. Use it to re-render a deposit QR code or check a rule's status after creation.
```bash Request theme={null}
curl https://api-sandbox.lumx.io/autoconversion-rules/c7f64332-5d53-4685-8aa9-48a5348c18c2 \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response has the same shape as the create response. To list every rule for a customer, send `GET /autoconversion-rules?customerId={customerId}`.
## Minimum amount
Each deposit must be worth at least 50 USD in the account's currency. Deposits below the minimum are not converted, so the conversion never starts. If a deposit comes in under the minimum, [contact support](mailto:support@lumx.io).
## Track conversions
Each matched deposit runs as an on-ramp transaction, so subscribe to the `onramp.*` [webhook events](/developer/webhooks#available-events) to follow the lifecycle, from `onramp.transferring_fiat` through `onramp.trading` and `onramp.transferring_stablecoin` to `onramp.success`. The receipt (amounts, exchange rate, fees, transaction hash) is delivered on success.
## Test in sandbox
Deposits can't be made against sandbox accounts, so use `POST /autoconversion-rules/simulate-deposit` to trigger the flow end-to-end. Pass the rule's `sourceDepositInfo[0].depositIdentifier` (PIX) or `sourceDepositInfo[0].reference` (SPEI) as the `reference`.
```bash Request theme={null}
curl -X POST https://api-sandbox.lumx.io/autoconversion-rules/simulate-deposit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"accountId": "44dd9734-176a-4ced-924f-103f8d50ea5e",
"reference": "IIDCDYjYUTbKouEUOyvxZ3xnU",
"amount": "100.00"
}'
```
```json Response theme={null}
{ "matchedRule": true }
```
`matchedRule` tells you whether the simulated deposit matched an active rule. If it did, the conversion runs and your webhook endpoint receives the lifecycle events.
This endpoint only exists in sandbox. Calling it in production returns `404`.
## Related resources
Virtual accounts that receive the deposits rules convert.
Subscribe to conversion lifecycle events.
Earn revenue on every conversion a rule executes.
How conversion rates are quoted and locked.