Lumetrade API

v1

Lumetrade API documentation.

The Lumetrade API gives third-party partners secure server-to-server access to Lumetrade accounts, wallets, currencies, beneficiaries, deposits, withdrawals, and trade data. Use this API to build operational dashboards, initiate supported money movement workflows, reconcile transactions, and surface account or wallet information in your own internal systems.

This documentation describes the external v1 API contract and the conventions your integration should follow from its first request through production use.

Authentication and access

API requests must include both X-API-KEY and X-API-SECRET headers. API keys are created through the authenticated user's API key management flow. The same user can revoke or rotate those credentials when needed. Treat the API secret as a server-side credential only; never expose it in browser, mobile, or other client-side code.

Authentication and access failures are handled consistently across the external API:

• 401 means the request could not be authenticated because API key headers are missing, invalid, revoked, or expired.
• 403 means the request was authenticated, but the API key owner is not allowed to perform the action because of permissions, account state, or access rules.

Individual endpoint documentation does not repeat these responses unless an endpoint has authentication or access behavior that differs from the standard API key flow.

Currency and assets

Supported currencies, assets, networks, and withdrawal rails are configuration-driven. When building forms or validation rules, use the relevant external, public, or user currency and payment route endpoints instead of hard-coding an asset list from this document. External account and currency endpoints are scoped to the API key owner's effective jurisdiction.

Security

Production and staging integrations must use HTTPS. Rotate API keys immediately if you suspect a secret has been exposed. Store secrets in a vault or server-side secret manager, and do not log full API secrets.

Error model

Error responses use Lumetrade's standard error envelope:

{
  "code": 1133,
  "message": "Validation error: amount is required",
  "httpStatus": 400,
  "requestId": "req_01HY...",
  "timestamp": "2026-01-01T00:00:00Z",
  "errors": [
    {
      "field": "amount",
      "message": "must be greater than 0"
    }
  ]
}

Common non-authentication error classes include 400 validation failures, 404 resources not found for the authenticated owner, 409 insufficient funds or conflicting money movement state, and 500 unexpected server errors.

Pagination and filtering

Current list endpoints may expose reserved query parameters for page, size, sort, date range, and status filters. Unless an endpoint explicitly says otherwise, current responses are unpaginated arrays and your integration should not depend on server-side pagination behavior yet.

Transaction lifecycle

Deposits, withdrawals, trades, and fills move through domain statuses such as pending, processing, completed, failed, cancelled, or reversed depending on the resource type. A status is final only when the specific endpoint and business flow represent it as terminal. Your integration should poll the read endpoints for status changes because webhooks are not currently documented for this API.

This is version v1 of this API documentation. Last update on May 15, 2026.