[

Integrate off-ramps to local bank rails

]

End-to-end integrations

Integrate off-ramps to local bank rails

A copy-paste prompt that builds Lumx payouts end to end — register a destination with the right holder relationship, quote, off-ramp, settle.

// PROMPT

{ "type": "INDIVIDUAL", "name": "William Default", "taxId": "100.100.100-01", "birthDate": "1990-01-01" }

You are a senior backend engineer adding Lumx off-ramps — stablecoin out, fiat into a bank account — to an existing server-side application.

Ground truth. Read both before writing any code and follow them over any prior knowledge:
1. https://docs.lumx.io/llms.txt — the documentation index. Every page has a .md twin at its own path.
2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec. Take field names, required flags and enum values from here; the prose explains the compliance rules the spec cannot.

Work against sandbox at https://api-sandbox.lumx.io with a server-side key sent as "Authorization: Bearer <key>".

1. Generate the destination branches from the spec, do not paraphrase them. POST /destinations is a oneOf with one branch per rail and a different required set on each: PIX takes keyType and keyValue; SPEI takes clabe; ACH and FEDWIRE take accountNumber, routingNumber and type; SWIFT requires bic with either iban or accountNumber; SEPA requires iban and bic. Every branch but PIX also requires a bank object — and one of them lists bank as required without defining it, so flag that instead of inventing a shape.
2. Set holder.relationship on every destination from the closed enum — SELF for the customer's own account, or one of the twelve third-party values such as SUPPLIER, EMPLOYEE, CREDITOR. This is a compliance field, not a label: pick the one that is true.
3. Create the destination and keep its id. Confirm with GET /destinations?customerId={id} and handle destinations.under_verification, destinations.approved and destinations.final_rejection. The verification status enum in the spec carries a fourth value with no matching event, so read status from the API and do not drive it from webhooks alone.
4. Quote with POST /exchange-rates when the payer needs a number before committing; type LOCKED returns an id and expiresAt, type FLOATING prices at execution.
5. Pay with POST /transactions/off-ramp using either destinationId + sourceCurrency + sourceAmount + purpose, or destinationId + exchangeRateId + purpose. Send an Idempotency-Key header with a UUID v4 you generated and persisted alongside the payout row before sending. Reuse the stored key on every retry; a retry that mints a new key pays twice.
6. Follow offramp.transferring_stablecoin, offramp.trading, offramp.transferring_fiat, offramp.success and offramp.failed, and confirm with GET /transactions/{id} before you mark the payout settled.

Constraints:
- Every payout debits the wallet of the customer that owns the destination. Do not design a pooled account that pays third parties who are not onboarded — read /compliance/nested-payments and stop if the design requires it.
- PERSONAL_ACCOUNT as purpose is only valid with a SELF destination. Anything else returns a validation error.
- Map errors by code, never by message: INSUFFICIENT_BALANCE, RAIL_NOT_ENABLED, HOLDER_TAX_ID_MISMATCH, DESTINATION_NOT_FOUND, EXCHANGE_RATE_EXPIRED. Treat an unknown code as retryable-unknown and surface it.
- Do not state a rate limit. None is published. Handle 429 TOO_MANY_REQUESTS with exponential backoff.

Deliverables:
- A destination builder with one typed branch per rail and a test per branch.
- A payout function that is idempotent on your own payout id.
- A webhook handler for the five offramp.* events plus the three destinations.* events.
- A note listing every enum value you took from the spec and every rule you took from the prose.

  1. Onboard one sandbox customer to APPROVED and fund its wallet before running this — an off-ramp against an empty wallet fails on balance, not on your code.

  2. Decide the holder relationship for your real payout flow yourself, with whoever owns compliance. The agent should not guess it.

  3. Review the branch tests: a rail you do not use yet is the cheapest thing to delete now and the most expensive to guess later.

TALK TO OUR TEAM

Ready to transform your business with stablecoins?

Discover how our infrastructure can seamlessly integrate stablecoins into your financial operations quickly, securely, and efficiently.

©2026. All rights reserved.

LUMX SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA., a private legal entity, enrolled with the CNPJ/MF under No. 42.887.120/0001-00 ("Lumx"), acts as a virtual asset service provider and is in the process of adapting to the regulatory regime for Virtual Asset Service Provider Companies (SPSAV), pursuant to Central Bank of Brazil (BCB) Resolution No. 520/2025, currently being subject to the transition regime set forth in Article 88 thereof.


Lumx US OP LLC ("Lumx") is a financial technology and payments infrastructure company. Lumx US OP LLC is a Money Service Business (MSB) registered with the Financial Crimes Enforcement Network (FinCEN) (MSB #31000316459619). Lumx is not a state-licensed money transmitter and does not, in its own capacity, engage in the provision of regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial-institution partners.


Lumx is not a bank, financial institution, payment institution, or custodian of client funds. Certain services made available through the Platform may be provided by duly authorized and regulated third-party partners, in accordance with applicable laws and regulations.

Please refer to Lumx’s Terms of Use and Privacy Notice for further information regarding the conditions governing the use of the Platform and the processing of your personal data.