Treasury management

Build a treasury product for corporate customers that need to hold working capital across multiple currencies, sweep funds between related entities, and execute FX conversions on demand. Balances are centralized in stablecoin in each entity’s wallet, and converted to local fiat only when needed.

Step 1: Generate your API key

Head over to dashboard.lumx.io. Once logged in, generate a new API key and store it securely. See Authentication for details.

Step 2: Onboard the corporate with multi-currency accounts

Create a business customer for the entity that will hold the treasury. Provision the fiat accounts they need so incoming deposits are converted to stablecoin and consolidated in the customer’s wallet automatically. See Coverage for supported currencies and rails.

Request

curl -X POST https://api-sandbox.lumx.io/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "BUSINESS",
    "legalName": "Acme Holdings Ltd.",
    "taxId": "123456-7",
    "incorporationDate": "2019-01-15",
    "country": "CYM",
    "email": "treasury@acme.com",
    "accounts": ["USD", "EUR", "BRL", "MXN", "GBP"]
  }'

Before the corporate can transact, they must accept Lumx’s terms of service (POST /customers/{id}/tos) and complete KYB. See Business verification for the full onboarding flow.

Step 3: Fund the corporate’s wallet

Once each account is ACTIVE, create an autoconversion rule for it, using the account’s id as accountId. You do this once per account: the response’s sourceDepositInfo carries the deposit details for that currency. Share them with the corporate’s treasury team, and every deposit that lands is converted to stablecoin and consolidated in the customer’s wallet, whatever the amount.

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": "af04e979-360a-428a-84e6-cbd8ffc4942b",
    "targetCurrency": "USDC",
    "purpose": "PERSONAL_ACCOUNT",
    "name": "USD treasury funding"
  }'

Each deposit must be worth at least 50 USD in the account’s currency. A USD, EUR, or GBP account holds one active rule at a time. All deposits land as stablecoin in the same wallet. The corporate doesn’t hold separate per-currency balances. If the corporate already holds stablecoin on-chain, they can also transfer it directly to the wallet returned at customer creation, no conversion needed. Subscribe to the onramp.success webhook to know the moment the wallet is credited and balances are ready to be moved or converted. For the response, the deposit details per currency, and when to create a one-off on-ramp instead, see Global accounts.

Step 4: Onboard subsidiaries and counterparty destinations

How you model the corporate group depends on whether each entity needs its own wallet. Multi-entity (each subsidiary holds its own balance): onboard each subsidiary as its own business customer. Each gets a dedicated wallet, and you can move funds between them with internal transfers. Single-entity (parent holds all balances): register each related external destination under the parent customer with the appropriate holder.relationship so transfers out are correctly categorized.

Relationship	Use when
`SELF`	The destination belongs to the same legal entity as the customer
`HOLDING_COMPANY`	The destination belongs to the parent of the customer
`SUBSIDIARY_COMPANY`	The destination belongs to a subsidiary of the customer

The taxId format varies by jurisdiction; see Tax IDs by country for the expected value per country.

curl -X POST https://api-sandbox.lumx.io/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Acme US - Operations",
    "rail": "FEDWIRE",
    "currency": "USD",
    "identifier": {
      "type": "CHECKING",
      "accountNumber": "123456789012",
      "routingNumber": "021000021"
    },
    "bank": {
      "name": "JPMorgan Chase Bank",
      "address": {
        "line1": "383 Madison Avenue",
        "city": "New York",
        "state": "NY",
        "postalCode": "10179",
        "country": "USA"
      }
    },
    "holder": {
      "type": "BUSINESS",
      "relationship": "SUBSIDIARY_COMPANY",
      "legalName": "Acme US Inc.",
      "taxId": "12-3456789",
      "incorporationDate": "2020-03-15",
      "email": "us@acme.com",
      "address": {
        "line1": "100 Wall Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10005",
        "country": "USA"
      }
    }
  }'

See Destinations for all supported rails and the full holder schema.

Step 5: Move funds between entities

When subsidiaries are onboarded as separate customers, move stablecoin between their wallets without going through fiat. Transfers settle in seconds and don’t incur FX cost.

Request

curl -X POST https://api-sandbox.lumx.io/transactions/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "980dc26b-42fd-4044-8a42-2271d20a2eb9",
    "currency": "USDC",
    "amount": "100000.000000",
    "metadata": {
      "memo": "Q2 working capital injection - Acme US"
    }
  }'

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "type": "TRANSFER",
  "state": { "status": "PENDING" },
  "request": {
    "currency": "USDC",
    "from": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "to": "980dc26b-42fd-4044-8a42-2271d20a2eb9",
    "amount": "100000.000000"
  }
}

Step 6: Convert balances to fiat on demand

When the corporate needs to settle in fiat (paying a supplier, repatriating profits, funding a subsidiary’s local account), create an off-ramp transaction debiting the wallet. Use the purpose code that matches the move:

Scenario	Purpose
Sweep to the entity’s own external account	`PERSONAL_ACCOUNT` (requires a destination with `SELF` holder relationship)
Loan or capital injection between related entities	`LOAN`
Cross-border supplier or invoice payment	`TRADE_TRANSACTIONS`
Tax remittance	`TAX`
Bill payment	`BILLS`

See Purpose codes for the full list and rules.

Request

curl -X POST https://api-sandbox.lumx.io/transactions/off-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destinationId": "e80d3137-eddd-4791-b9b8-6e36b289f284",
    "sourceCurrency": "USDC",
    "sourceAmount": "50000.00",
    "purpose": "LOAN"
  }'

For predictable FX (budgeting, monthly settlements, locked supplier quotes), fetch a locked exchange rate first and pass its id as exchangeRateId on the off-ramp request. See Exchange Rates.

Step 7: Track and reconcile

Subscribe to offramp.success, offramp.failed, transfer.success, and account.active webhooks to keep balances, transfers, and conversion status in sync inside your product. See Webhooks.

Global accounts

Provision multi-currency virtual accounts.

Exchange Rates

Lock FX rates for predictable conversions.

Destinations

Holder relationships for inter-company moves.

Transactions

Transfer, off-ramp lifecycle and purpose codes.

Use Cases

Onboarding

Collect

Pay out

Build with AI

Treasury management

Step 1: Generate your API key

Step 2: Onboard the corporate with multi-currency accounts

Step 3: Fund the corporate’s wallet

Step 4: Onboard subsidiaries and counterparty destinations

Step 5: Move funds between entities

Step 6: Convert balances to fiat on demand

Step 7: Track and reconcile

Global accounts

Exchange Rates

Destinations

Transactions

​Step 1: Generate your API key

​Step 2: Onboard the corporate with multi-currency accounts

​Step 3: Fund the corporate’s wallet

​Step 4: Onboard subsidiaries and counterparty destinations

​Step 5: Move funds between entities

​Step 6: Convert balances to fiat on demand

​Step 7: Track and reconcile

​Related resources

Global accounts

Exchange Rates

Destinations

Transactions

Step 1: Generate your API key

Step 2: Onboard the corporate with multi-currency accounts

Step 3: Fund the corporate’s wallet

Step 4: Onboard subsidiaries and counterparty destinations

Step 5: Move funds between entities

Step 6: Convert balances to fiat on demand

Step 7: Track and reconcile

Related resources