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, MXN, USD, EUR, and GBP accounts.

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`, `TRON`, or `STELLAR`. 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
USD	ACH, FEDWIRE, SWIFT	Bank details (`accountNumber`, `routingNumber` or `bic`, `bankName`)	Wires to the account
EUR	SEPA	Bank details (`iban`, `bic`)	Transfers to the IBAN
GBP	FPS	Bank details (`sortCode`, `accountNumber`)	Transfers to the sort code and account number

For BRL and MXN, 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.

A customer can have only one active rule per USD, EUR, or GBP account at a time. Deposits in these currencies are matched to the customer’s account rather than a per-rule reference, so a second rule would be ambiguous. Creating one while another is active returns 409 AUTOCONVERSION_RULE_ALREADY_EXISTS. Delete the existing rule to create a new one. BRL and MXN rules have no such limit.

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
`409`	`AUTOCONVERSION_RULE_ALREADY_EXISTS` (see the note above)

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"

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

List rules

List a customer’s rules, newest first, with GET /autoconversion-rules?customerId={customerId}. Results are paginated: pass size (1–50, default 25) and the previous page’s nextCursor as cursor. List items include the rule’s name but not sourceDepositInfo, so fetch a single rule to get the deposit details.

Request

curl "https://api-sandbox.lumx.io/autoconversion-rules?customerId=3c90c3cc-0d44-4b50-8888-8dd25736052a&size=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "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",
      "name": "BRL → USDC investment",
      "createdAt": "2026-07-08T23:18:58.574Z"
    }
  ],
  "pagination": {
    "size": 25,
    "total": 1,
    "hasNextPage": false,
    "nextCursor": null
  }
}

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. For USD, EUR, and GBP rules, omit reference, since deposits are matched to the account.

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.

Use Cases

Customer Onboarding

Conversions

Build with AI

Autoconversion Rules

How it works

Create a rule

Request fields

Errors

Retrieve a rule

List rules

Minimum amount

Track conversions

Test in sandbox

Accounts

Webhooks

Partner Fees

Exchange Rates

​How it works

​Create a rule

​Request fields

​Share the deposit details

​Errors

​Retrieve a rule

​List rules

​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

List rules

Minimum amount

Track conversions

Test in sandbox

Related resources