Lumx developers and AI agents FAQ
How to integrate Lumx: REST API and OpenAPI spec, sandbox, API keys, webhooks, idempotency, errors, going live, the docs MCP server and AI coding tools.
What is a stablecoin payment API?
A stablecoin payment API is a programmable interface that lets a business move money between bank rails and stablecoins such as USDC and USDT, covering collection, conversion, custody and payout. Lumx is one such API: it connects local rails like Pix, SPEI, PSE, Bre-B, ACH, SEPA and SWIFT to USDC and USDT, with KYB/KYC built in.
How do I integrate with Lumx?
You integrate through a REST API. Create an account on the Lumx dashboard, generate an API key under Developers, API Keys, and call the API with it as a bearer token. The full API is described in an OpenAPI 3.0 specification that you can import into Postman, Insomnia or Swagger Editor, or feed to a code generator to produce a client in your own language.
Is there a sandbox, and how do I get access?
Yes. The sandbox is self-serve: you open the account from the dashboard without a request to the sales team, and new accounts start in the sandbox. It is a separate environment from production, at api-sandbox.lumx.io, with the same API surface and its own data. Production lives at api.lumx.io, and moving to it is a conversation with the Lumx team.
Can I test Lumx without moving real money?
Yes. The sandbox runs on testnet stablecoins and mock banking partners, so no real money moves. An on-ramp in the sandbox completes on its own and credits the stablecoin to the customer's wallet, and you can use that balance to test off-ramps. The sandbox also rejects invalid destinations, and COP works there like the other currencies.
How do I test customer verification outcomes in the sandbox?
You control the result with the last digit of the taxId you send. A taxId ending in 1 returns NOT_STARTED, 2 returns RFI, 3 returns FINAL_REJECTION, and any other digit returns APPROVED. The matching webhook fires almost instantly, so you can exercise approval, request-for-information and rejection paths before going live.
How does authentication work and how are API keys managed?
You authenticate with an API key created in the dashboard under Developers, API Keys. The key is shown once, so copy it immediately, and if it is compromised you revoke and rotate it from the dashboard. Keep keys on the server and out of version control and client-side code. You can also allowlist your server IPs; the allowlist applies to production only, and the sandbox accepts requests from any IP.
How do webhooks work and how do I verify their signatures?
Lumx sends an HTTP POST to your endpoint on every status change, for on-ramps, off-ramps, transfers, customers, accounts and destinations. Each request carries webhook-id, webhook-timestamp and webhook-signature headers. You compute an HMAC-SHA256 over webhook-id, webhook-timestamp and the raw body joined by dots, using your whsec_ secret base64-decoded as the key, and compare it with the header. Reject messages older than five minutes.
What happens when my webhook endpoint is down?
Lumx retries any delivery that does not return a 2xx response, up to eight attempts with exponential backoff: immediately, then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours twice. After the last attempt the message is marked failed, and you can retry it manually from the dashboard. Because retries mean the same event can arrive twice, deduplicate on webhook-id.
How does idempotency work in the Lumx API?
Send an Idempotency-Key header, ideally a UUID v4, on the POST and PATCH requests that accept it. Lumx stores the response per project and returns the cached result if you send the same key and body again, so a retry after a timeout never creates a duplicate transaction. The same key with a different body returns a 409, and keys expire after 24 hours.
What does an API error look like and how should I handle it?
Every error uses one response shape with requestId, timestamp, path, status, code and message, so one code path handles all failures. Match on the code field, never on the message, which can change. Field-level problems come back as a 400 VALIDATION_ERROR with a validationErrors list. Keep the requestId when you write to operations@lumx.io for support.
What changes when I move from the sandbox to production?
The base URL changes from api-sandbox.lumx.io to api.lumx.io, you use a production key, and every call now settles real money on mainnet blockchains and live banking rails. The IP allowlist applies in production only. Lumx publishes a production readiness checklist prompt that audits your integration for hosts, keys, idempotency, webhook hardening, error handling and pagination before the first payment.
How do I get production access?
The Lumx operations team enables production once your company passes Lumx's know-your-partner review and the contract is signed. After signature, access is switched on within minutes, and you generate a production API key in the dashboard. Until then you can build and test the whole integration in the self-serve sandbox, which needs no call with the Lumx team.
Can I build a Lumx integration with AI coding tools like Cursor, Claude Code or Lovable?
Yes. Lumx publishes build guides for Lovable, v0, Bolt.new, Replit, Cursor, Claude Code, Codex and Grok, each with a copy-paste prompt for customer onboarding, on-ramp deposits and transaction tracking, plus a prompt library for webhooks, off-ramps and a sandbox quickstart. The coding-assistant guides also connect the Lumx docs MCP server at docs.lumx.io/mcp, which needs no API key and gives your agent documentation access, not the ability to move money.