Autoconversion Rules

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 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

You create a rule for an account, choosing the target asset, network, purpose, and a name.
The response includes deposit details (sourceDepositInfo): for a BRL account, a PIX brCode. Share it with whoever is sending the funds.
Every deposit paid through it is matched to the rule and converted to the target asset.
You receive webhooks as each conversion moves through its lifecycle.

You can create and view rules in the Dashboard (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.

Request

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"
  }'

Response

{
  "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)
`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 applied to each conversion. Must belong to your project

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.

Request

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.

Track conversions

Each matched deposit runs as an on-ramp transaction, so subscribe to the onramp.* webhook 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.

Request

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"
  }'

Response

{ "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.

Accounts

Virtual accounts that receive the deposits rules convert.

Webhooks

Subscribe to conversion lifecycle events.

Partner Fees

Earn revenue on every conversion a rule executes.

Exchange Rates

How conversion rates are quoted and locked.

​How it works

​Create a rule

​Request fields

​Share the deposit details

​Errors

​Retrieve a rule

​Minimum amount

​Track conversions

​Test in sandbox

​Related resources

Accounts

Webhooks

Partner Fees

Exchange Rates

How it works

Create a rule

Request fields

Share the deposit details

Errors

Retrieve a rule

Minimum amount

Track conversions

Test in sandbox

Related resources