Skip to main content

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.

Every Lumx customer gets a wallet on each supported blockchain, provisioned at the same time as the customer. Wallets are only enabled for use once the customer reaches APPROVED — see Identity Verification. Once active, the wallet holds stablecoin balances between on-ramps, transfers, and off-ramps, so you can fund a customer once and pay out from the same balance as many times as you need.

​
Wallet schema

Each wallet has:
  • blockchain: the network the address belongs to. One of ETHEREUM, POLYGON, BASE, TRON.
  • address: the on-chain address. Holds balances and can receive direct transfers.
  • blockExplorerUrl: deep link to the address on the relevant block explorer.
  • isDefault: the wallet Lumx uses when an on-ramp, off-ramp, or exchange rate request doesn’t specify a blockchain.
  • balances: current stablecoin holdings on that wallet. Each entry has currency (USDC or USDT), amount, and updatedAt.
Wallets on a customer response
{
  "wallets": [
    {
      "blockchain": "POLYGON",
      "address": "0x1234567890123456789012345678901234567890",
      "blockExplorerUrl": "https://polygonscan.com/address/0x1234567890123456789012345678901234567890",
      "isDefault": true,
      "balances": [
        { "currency": "USDC", "amount": "12500.00", "updatedAt": "2026-05-25T14:32:00Z" },
        { "currency": "USDT", "amount": "0.00", "updatedAt": "2026-05-25T14:32:00Z" }
      ]
    }
  ]
}
The wallets array is omitted on the Create a customer response. Fetch it later via Read a customer or subscribe to the customer.approved webhook.

​
Supported networks and stablecoins

Wallets support every blockchain and stablecoin available on the platform. For the full conversion matrix by currency, see Coverage.
BlockchainStablecoins
EthereumUSDC, USDT
PolygonUSDC, USDT
BaseUSDC
TronUSDT
The default blockchain is set at the project level. Pass blockchain on on-ramp, off-ramp, transfer, or exchange rate requests to target a specific network; omit it to fall back to the default.

​
How balances change

A wallet’s balance moves in three ways:
  • On-ramps credit the wallet with stablecoin once fiat lands on the matching account.
  • Transfers move stablecoin in or out, either between two Lumx customers or to and from any external wallet address.
  • Off-ramps debit the wallet and convert stablecoin to fiat sent to a registered destination.
Subscribe to onramp.success, offramp.success, and transfer.success webhooks to keep balances in sync inside your product.

​
Prefunded wallets

A wallet keeps its balance between operations. That means you can on-ramp once and trigger many payouts against the same wallet, without waiting for incoming fiat to clear before each one. A few common patterns:
  • Payroll. Fund the employer’s wallet at the start of the cycle, then trigger one off-ramp per employee against registered destinations. See Payroll.
  • Supplier batches. Hold working capital in stablecoin and settle invoices across rails on demand. See Treasury management.
  • Card acquiring. Keep a balance to credit users at checkout, before card networks settle.
  • Marketplace payouts. Pay sellers from your platform’s balance the moment an order ships. See Marketplaces.
Each payout has to debit the customer’s own wallet to a destination registered under that customer, or transfer to another onboarded customer’s wallet. Lumx needs to see every payer and payee, so pooling funds for unboarded third parties isn’t allowed. See Nested Payments.

​
External transfers

A wallet address is a real on-chain address. Anyone can send supported stablecoins to it, and you can transfer from it to any external wallet via the Transfer endpoint. Use this to:
  • Fund a customer’s wallet directly with stablecoin held elsewhere, with no on-ramp needed.
  • Move stablecoin to a self-custody wallet, exchange, or counterparty outside Lumx.

Customers

Customer entities and verification lifecycle.

Accounts

Virtual fiat accounts for incoming payments.

Destinations

Payout destinations and holder relationships.

Transactions

On-ramp, off-ramp, and transfer lifecycle.