Lumetrade API

v1

Lumetrade API documentation.

The Lumetrade API gives third-party partners secure server-to-server access to accounts, wallets, currencies, beneficiaries, deposits, withdrawals, and trade data and execute trades. 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.

Rate limiting

External API traffic is rate limited at Cloudflare before it reaches Neptune. Requests to api.staging.lumetrade.com, api.lumetrade.com, api.staging.lumepay.com, and api.lumepay.com under /api/v1/** are limited to 33 requests per 10 seconds per client IP and Cloudflare data center. Requests above that limit receive HTTP 429 with {"error":"rate_limit_exceeded","message":"API rate limit exceeded"}. Neptune does not currently emit X-RateLimit-* quota headers, so clients should still use conservative retry and backoff behavior.

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 may poll the read endpoints and may subscribe to the documented webhook events for supported deposit, withdrawal, trade, and test lifecycle notifications. Webhooks are delivered at least once; consumers must deduplicate using the webhook and delivery identifiers sent with each callback.

Webhooks

The active v1 webhook catalog is available from GET /api/v1/webhooks/events. Current supported event types are test.event, deposit.pending, deposit.completed, deposit.cancelled, withdrawal.accepted, withdrawal.processing, withdrawal.completed, withdrawal.failed, withdrawal.cancelled, withdrawal.reversed, and trade.completed. Do not assume unlisted events are emitted.

Create subscriptions in PENDING_VERIFICATION, call the verify endpoint until the callback target has returned a successful webhook.verification response, then activate the subscription. The same subscription can be deactivated and its event list can be updated. Customer-facing secret rotation and customer re-enable of system-disabled subscriptions are not supported in v1. Webhook signing secrets are platform-managed per-subscription configuration distributed to customers out-of-band by Lume.

Delivery callbacks include X-Lume-Webhook-Id, X-Lume-Webhook-Delivery-Id, X-Lume-Webhook-Event, X-Lume-Webhook-Timestamp, and X-Lume-Webhook-Signature. The signature is v1= plus lowercase hex HMAC-SHA256 over <X-Lume-Webhook-Timestamp>.<raw JSON request body> using the active Lume-provisioned per-subscription webhook signing secret. Verification challenges use the same signed callback header contract. Any 2xx callback response is success. Non-2xx, timeout, transport, and security validation failures are failed attempts. Neptune retries failed deliveries using the configured retry schedule and disables the subscription after the configured maximum failed attempts for a single outbox row.

Financial lifecycle payloads are minimal: they contain the webhook id, event type, and resource type/id. Payloads do not expose Sumsub, KYC, KYT, provider ids, wallet metadata, bank details, internal reconciliation fields, remediation reasons, or internal case state. Neptune does not promise static outbound source IPs for v1 webhook delivery.

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

This is version v1 of this API documentation. Last update on Jul 20, 2026.