PIX ↔ USDT
with no friction.

Overview

Signed webhooks, native idempotency, a Telegram bot that reports every cent in real time and answers integration questions 24/7 — and documentation that fits on a single page.

Cash-in: PIX comes in, USDT goes out on Polygon. Cash-out: USDT and USDC on the major networks become PIX — Polygon in seconds, and Ethereum, BNB Chain, Arbitrum, Optimism, Base, Avalanche, TON, Aptos, NEAR and others within each network's confirmation time (full table).

Integrate in 60 seconds

1. Open your operations group — Sandbox MCP (agents) strongly recommended, takes 1 minute and is what guarantees you are notified when something happens to your money.
2. Create your key — talk to the bot on Telegram (say "my name is YourCompany" and the credential is born in the chat) or a POST /keys (there is a button below that does it right now). No waiting, no human in the loop — nobody generates a credential for you, you generate it yourself.
3. Create a charge — POST /cashin/charge with the amount and the payer's CPF/CNPJ. It returns a copy-and-paste PIX code ready for the screen.
4. Receive USDT — once it is paid, we settle on Polygon and notify you by webhook and Telegram, with the transaction hash.

Sandbox — test everything before spending anything

One call, no API key — this is the only endpoint that does not ask for a credential (IP-limited). No name, no email, no wallet, no approval.

curl -s -X POST https://api.luniumpay.com/keys/sandbox \
  -H 'Content-Type: application/json' -d '{"name":"my first test"}'

You get a key lun_test_… that runs the entire cash-out without a cent moving, on the same base URL. What the sandbox covers: POST /cash-outs, the accept and every state through to the outcome. What it does not cover: cash-in (the test key refuses with sandbox_sem_cashin — creating a charge would generate a genuinely payable QR), payouts (they depend on settled volume) and automatic webhooks: sandbox orders do not fire webhooks on their own — but a sandbox key can call POST /webhooks/test and validate your handler's signature and transport before any real operation. Code written here was designed to go to production unchanged: same shapes, same states, same error contract, same validations. Real limits and financial behavior are those of your production key — read them from GET /keys/me, not from this page.

The order does not complete instantly — it walks through the real states in about 15 seconds. That is on purpose: you need that tracking loop (or the webhook) in production anyway, so write it now.

Deterministic triggers

Testing only the happy path is how an integration breaks on day one. The first two decimal places of the amount choose the outcome — no luck involved, you can assert it in CI:

Also worth rehearsing: reusing an external_id with a different destination returns 409 — the case that confuses integrators most, and it is better to find it here.

The sandbox order generates a well-formed E2E with ISPB 00000000, which no real institution holds — so it can never be mistaken for a real payment. GET /v1/verificar/{e2e} responds for it, flagged with sandbox: true.

Test orders disappear 2 hours after they are created. Never send crypto to a deposit_address in sandbox: it has no owner and the funds would be lost.

MCP server — for AI agents

https://api.luniumpay.com/mcp

Streamable HTTP, revision 2025-06-18, stateless. Add it as a remote MCP connector in any host that speaks the protocol.

It works with no credential at all. Connect without a key and lunium_verify_pix_payment is already available — it confirms that a PIX was settled from the E2E, including a payment that is not yours. It is how you check what the counterparty claims without having an account and without trusting them.

The other tools use the X-API-Key sent by the host as a header. Without it, they respond erro: "chave_ausente" with a acao: "parar" — they do not disappear from the list, so the agent can warn the user instead of concluding that the capability does not exist.

There are eight tools: verify payment · list what settles now · check payer limit · quote a sale · confirm · create charge · track sale · track charge.

The two that actually move money come marked with destructiveHint: true, so the host can require human approval, and confirming a sale requires a token bound to the amount, the network and the destination that were quoted. Selling takes two steps on purpose: quoting commits nothing, confirming is irreversible.

Operations group STRONGLY RECOMMENDED

There are three steps, just once:

1. Create a group on Telegram named after your project. A suggestion that helps us identify you right away: Lunium <> YourCompany.
2. Add both (both are required for the group to do its job):
   — @LuniumNotifyBot · the agent. Reports everything in real time, answers integration questions and runs commands (/cobrar, /status, /extrato).

   — @luniumB2C · the Lunium team. The human on the other side when the agent can't solve it: incident, release, commercial exception.
3. Link the group to your key — a group admin sends /vincular. If that admin already created the key in the bot's DM, it's 1 tap; if not, get the code in the DM with /chave and send /vincular lk… in the group.

Do everything by chat — the agent AI

Beyond the REST API, Lunium gives you a real agent on Telegram. In a DM — or by mentioning it in your project's group — you charge, withdraw and pay by writing in plain Portuguese. It reads the real data in your account, assembles the operation and executes it with a single confirmation tap. Money never moves without your OK.

Authentication

Every call carries your key in the header X-API-Key. The same key authorizes cash-in, cash-out, catalog and account.

curl https://api.luniumpay.com/keys/me \
  -H "X-API-Key: lun_a1b2c3…"

Create key · self-service

Creates a new key with cash-in and cash-out already enabled. No authentication — this is the starting point. Rate-limited by IP (5/day).

curl -X POST https://api.luniumpay.com/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Store",
    "email": "dev@examplestore.com",
    "webhook_url": "https://examplestore.com/webhooks/lunium"
  }'

const r = await fetch('https://api.luniumpay.com/keys', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Example Store',
    email: 'dev@examplestore.com',
    webhook_url: 'https://examplestore.com/webhooks/lunium',
  }),
});
const conta = await r.json();
// conta.api_key ← save it NOW (shown only here)

import requests

r = requests.post("https://api.luniumpay.com/keys", json={
    "name": "Example Store",
    "email": "dev@examplestore.com",
    "webhook_url": "https://examplestore.com/webhooks/lunium",
})
conta = r.json()
# conta["api_key"] ← save it NOW (shown only here)

Response 201:

{
  "api_key": "lun_9f2c40d1e8…",          // ← the only time it is shown
  "webhook_secret": "whk_5d1a…",          // if you sent webhook_url
  "key": {
    "key_id": 7, "prefix": "lun_9f2c40d1", "name": "Example Store",
    "cashin_enabled": true, "cashout_enabled": true,
    "fee_bps": 250, "fee_fixed_cents": 100,   // house default: 2.5% + R$ 1.00 — negotiable by volume
    "rate_limit_per_minute": 60, …
  },
  "limits": { "tier": "Inicio", "daily_limit_cents": 500000, … },
  "monitor_url": "https://api.luniumpay.com/cashin/monitor?token=dsh_…",  // live read-only dashboard
  "telegram": {
    "bot": "@…",
    "link": "https://t.me/…?start=lk1a2b3c…",  // one tap = real-time alerts
    "hint": "Crie um grupo com o time e adicione o agente."
  },
  "docs": "https://docs.luniumpay.com"
}

Your account

Everything about your key: configuration, tier, daily limit (cash-in and payouts — the sale has none), today's usage and the Telegram link.

curl https://api.luniumpay.com/keys/me -H "X-API-Key: $LUNIUM_KEY"

{
  "key": { "key_id": 7, "prefix": "lun_9f2c40d1", "name": "Example Store",
           "cashin_enabled": true, "cashout_enabled": true,
           "webhook_configured": true, "telegram_linked": true, … },
  "limits": {
    "tier": "Crescimento",
    "daily_limit_cents": 2500000,
    "used_today_cents": 431000,
    "available_today_cents": 2069000,
    "settled_volume_cents": 9174350,
    "next_tier": { "tier": "Escala", "unlocks_at_settled_volume_cents": 50000000,
                    "daily_limit_cents": 10000000 }
  }
}

Updates name, settlement_address and webhook_url (sending null clears the field). "rotate_webhook_secret": true rotates the secret — the new one comes in the response, only once.

curl -X PATCH https://api.luniumpay.com/keys/me \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{ "settlement_address": "0xAbC123…", "webhook_url": "https://examplestore.com/wh" }'

Limits & tiers — progressive by volume

Trust is built by volume. Every key starts in the Start tier and moves up automatically as it settles volume with us. The end payer is validated by our regulated PIX provider — your ceiling is only a risk gauge.

• The daily ceiling counts cash-in + payouts and resets at midnight (America/Sao_Paulo). The cash-out does not count toward this quota — it has a per-operation limit, not a daily one.
• Source of truth: the numbers on this page are reference; what the API enforces comes in GET /keys/me → limits.per_operation (range per cash-in, cash-out and payout operation), limits.payer_limits (ladder by CPF/CNPJ) and limits.daily_limit_applies_to (what consumes the quota). Don't hardcode limits in your code: read them from here, they change without notice.
• Operations in progress count toward the ceiling; expired/refunded ones free the space back up.
• Blew past it? The API responds 403 with a limits in the body — show it to your finance team and try again the next day, or speed up the upgrade by settling volume.
• Your current tier, usage and next step: GET /keys/me or /limites in the bot.

Limit per payer (CPF/CNPJ) NEW

Beyond the ceiling of your key, there is a second scale: the one for each CPF/CNPJ that pays. It protects you and us from the same problem — mule accounts, stolen card/PIX and fraud probing always come in through a new payer, never a recurring one. A new CPF starts small and grows on its own:

• The clock starts at the first confirmed payment, not at the first charge created — generating a QR is free, paying is not. That way no one "ages" a CPF just by issuing charges.
• The limit counts what has been paid and what is in flight (pending charge still valid) — available = ceiling − paid − pending. It applies from day one: before the 1st confirmed payment, the CPF/CNPJ can have at most R$ 60 in open charges at the same time (aggregate, not R$ 60 per QR) — opening several QRs does not break the ceiling. Expired ones don't count.
• Payers that already have history with you already start out mature — nothing was reset.
• It holds in both usage modes and is independent of your tier: even on Escala, a first-time CPF pays at most R$ 60 on the first one.

{
  "erro": "limite_do_pagador",        // ← branch out from here (the contract for the whole API)
  "acao": "corrigir",
  "detail": "Nas primeiras 24h o CPF/CNPJ pode movimentar R$ 200,00. Já usou R$ 120,00; disponível: R$ 80,00…",
  "payer_limits": {
    "stage": "first_24h",
    "window_limit_cents": 20000,
    "used_cents": 12000,
    "available_cents": 8000,
    "matures_in_hours": 23
  },
  "code": "payer_limit"               // legacy alias — retired on 2026-11-09, branch on "erro" instead
}

Quick reference

Every endpoint in one table. Base: https://api.luniumpay.com · authentication via X-API-Key except where noted.

OpenAPI · Postman & Insomnia

Every endpoint in a single file. Import the spec and you get a ready-made collection — with authentication and examples — to test the API without writing anything.

https://docs.luniumpay.com/openapi.json

Cash-in — PIX in, USDT out

Your customer pays an ordinary PIX (copy-and-paste QR); Lunium receives it, converts it and sends USDT (Polygon) to the address you specify — yours, fixed on the key, or one per charge. No connected wallet, no friction for the payer.

Balance in reais (custody) — deposit and withdraw by PIX

Keys with custody enabled (custodia_ativa: true in GET /saldo) hold reais for the partner's end customers — the "Deposit and Withdraw" tab of a wallet app. The ledger is append-only: balance = sum of the movements.

curl -X POST https://api.luniumpay.com/cashin/charge -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"amount_cents":10000,"payer_tax_number":"12345678909","destino":"saldo","customer_ref":"user_42","chain":"polygon","asset":"usdt"}'
curl "https://api.luniumpay.com/saldo?customer_ref=user_42" -H "X-API-Key: $KEY"
curl -X POST https://api.luniumpay.com/payouts -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"amount_cents":5000,"pix_key":"12345678909","pix_key_type":"cpf","tax_number":"12345678909","customer_ref":"user_42","external_id":"withdrawal-1"}'

Two holding periods: the balance shows up immediately, but each deposit can only be used after carencia_horas (D+1); and the first deposit of a sub-account locks any withdrawal for 24h (carencia_ate in GET /saldo; 423 carencia_primeiro_deposito on both withdrawal routes). Charges carry fonte (pix|saldo) and destino (cripto|saldo).

Nothing is advanced and no fee is absorbed: what the provider charges is what the balance pays. Custody is enabled per key by support.

Quote (read-only)

How much of the stablecoin comes out for a given BRL amount, without creating anything. It already applies your key's fee. Accepts asset: "usdt" (default) or "usdc".

curl -X POST https://api.luniumpay.com/cashin/preview \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{ "amount_cents": 25000 }'

const quote = await lunium('POST', '/cashin/preview', { amount_cents: 25000 });

quote = lunium("POST", "/cashin/preview", {"amount_cents": 25000})

{ "asset": "usdt", "amount_cents": 25000,
  "admin_fee_bps": 250, "admin_fee_fixed_cents": 100,   // 2.5% + R$1 flat
  "fee_total_cents": 723, "net_cents": 24277,        // total fee and net amount
  "brl_per_usdt": "5.10", "usdt_amount": "47.558132" }

base = max(0, amount_cents − admin_fee_fixed_cents)   // the flat part comes off first
net_cents = floor(base × (10000 − admin_fee_bps) ÷ 10000)   // truncates, never rounds
fee_total_cents = amount_cents − net_cents            // flat + percentage together

Create charge

curl -X POST https://api.luniumpay.com/cashin/charge \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 25000,
    "payer_tax_number": "12345678901",
    "payer_name": "Maria Souza",
    "payout_address": "0xAbC123…",
    "external_id": "order-8812"
  }'

const charge = await lunium('POST', '/cashin/charge', {
  amount_cents: 25000,
  payer_tax_number: '12345678901',
  payer_name: 'Maria Souza',
  payout_address: '0xAbC123…',
  external_id: 'order-8812',
});
mostrarQR(charge.qr_copypaste);   // comes ready for the screen

charge = lunium("POST", "/cashin/charge", {
    "amount_cents": 25000,
    "payer_tax_number": "12345678901",
    "payer_name": "Maria Souza",
    "payout_address": "0xAbC123…",
    "external_id": "order-8812",
})
mostrar_qr(charge["qr_copypaste"])

{
  "cashin_id": "ci_b3f9d2a41c6e8f5a90d7",
  "status": "pending",
  "amount_cents": 25000,
  "payout_address": "0xAbC123…", "chain": "polygon",
  "qr_copypaste": "00020126580014br.gov.bcb.pix…",   // PIX copy-and-paste code
  "qr_image_url": "https://…/qr.png",
  "external_id": "order-8812",
  "expires_at": "2026-07-20T18:45:00.000Z"
}

Charge status

Full snapshot — includes the on-chain hash once the USDT goes out.

curl https://api.luniumpay.com/cashin/ci_b3f9d2a41c6e8f5a90d7/status \
  -H "X-API-Key: $LUNIUM_KEY"

{
  "cashin_id": "ci_b3f9d2a41c6e8f5a90d7",
  "status": "paid",
  "settlement_status": "sent",
  "amount_cents": 25000,
  "depix_received_cents": 25000,          // what ACTUALLY came in
  "usdt_amount": "46.040515",
  "settlement_tx_hash": "0x8ef1…",
  "settlement_tx_url": "https://polygonscan.com/tx/0x8ef1…",
  "payer_tax_number": "•••••••8901",      // always masked
  "paid_at": "2026-07-20T18:34:12.000Z",
  "settled_at": "2026-07-20T18:34:40.000Z", …
}

List charges

The charges on your key, most recent first. Filters: status, start/end, limit (max. 200) and external_id (recovery). Response: { "charges": [ … ] } in the same format as the status — perfect for daily reconciliation.

cash-in lifecycle

cash-out — crypto in, PIX out

The way back: you (or your customer) send crypto and a PIX key receives reais. Three-step flow: quote → accept → deposit. After the deposit, it is on us: conversion and PIX go out on their own, with an event at every transition.

We accept USDT and USDC on the main networks — Polygon with settlement in seconds, and Ethereum, BNB Chain, Arbitrum, Optimism, Base, Avalanche, TON, Aptos, NEAR and others at each network's own time. See the two paths and the timing table before choosing the network.

Asset catalog

Current assets, networks and limits for cash-out. It is the source of truth — the catalog changes on its own as networks go in and out of maintenance, so read from it instead of hard-coding a list in your code.

{
  "updatedAt": "2026-07-31T03:18:16.793Z",
  "fast": [ { "asset": "USDT", "network": "polygon" } ],   // settles in seconds
  "convert": [                                          // major networks, timing set by the network
    { "asset": "USDT", "networks": ["eth", "bsc", "arbitrum", …],
      "min": "10", "max": "200000", "precision": 8 }
  ],
  "dex": { "chains": ["polygon"], "note": "…" }
}

curl https://api.luniumpay.com/catalog -H "X-API-Key: $LUNIUM_KEY"

Two settlement paths — choose by timing

The same POST /cash-outs serves both; what decides is the pair asset + network you send. The difference that matters to your customer is when the PIX lands.

Networks and estimated times

Estimates measured by the confirmations required per network. The min is per order (USDT 10 · USDC 20); the ceiling is 200,000 per order, subject to your tier.

Long-tail tokens via DEX (Polygon). Symbols repeat — when using a token from the /catalog/dex, also send the exact token_address in the quote. The token is converted on-chain before the PIX, so the outcome depends on the liquidity of the pair.

Create quote

curl -X POST https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT", "network": "polygon", "amount": "50",
    "pix_key": "12345678901", "pix_key_type": "cpf",
    "external_id": "withdrawal-2207"
  }'

const ordem = await lunium('POST', '/cash-outs', {
  asset: 'USDT', network: 'polygon', amount: '50',
  pix_key: '12345678901', pix_key_type: 'cpf',
  external_id: 'withdrawal-2207',
});

ordem = lunium("POST", "/cash-outs", {
    "asset": "USDT", "network": "polygon", "amount": "50",
    "pix_key": "12345678901", "pix_key_type": "cpf",
    "external_id": "withdrawal-2207",
})

{
  "cashout_id": "dede940b-6adb-4104-ac6b-979b1e84b1f5",
  "state": "QUOTE_CREATED",
  "asset": "USDT", "network": "polygon", "amount": "50",
  "brl_amount": "268.00",                // the PIX the key will receive
  "pix_key": "123•••••901",               // always masked
  "expires_at": "2026-07-20T18:40:00.000Z"
}

Accept the quote

Locks the quote and returns the deposit address. Send exactly the quoted amount, on the right network; on networks with memo/tag, include the deposit_tag.

{
  "cashout_id": "dede940b-6adb-4104-ac6b-979b1e84b1f5",
  "state": "AWAITING_DEPOSIT",
  "deposit_address": "0xDdE987…",          // send the crypto here
  "brl_amount": "268.00", …
}

Status & list

Current state. Our worker also tracks every order 24/7 and fires a webhook/Telegram on each transition — polling is optional, not required.

Orders for your key, most recent first. Response: { "cash_outs": [ … ] }.

cash-out lifecycle

Refund — what happens in each failure

Send refund_address (your customer's wallet, on the network of the sale) in every quote. It is the destination of any refund; without it, the crypto goes back to the on-chain origin of the deposit — and the origin of an exchange withdrawal is the wallet of the exchange.

• Copy-and-paste code in the wrong field, or outside USDT/USDC Polygon → rejected at the quote (pix_key_invalida / br_code_nao_suportado). Nothing moves: there is no deposit address yet. To pay a QR use br_code.
• QR rejected by the settlement provider at payment time (expired charge, already paid, QR not recognized) → the settlement provider returns the crypto to Lunium's custody within seconds and it goes on to refund_address; MANUAL_REVIEW → REFUNDED with a refund_tx_hash.
• Provider rejects the PIX key after the deposit (invalid/nonexistent) → MANUAL_REVIEW (cashout.under_review); the crypto returns to Lunium's custody and automatically goes to refund_address; it ends in REFUNDED (cashout.refunded) with refund_tx_hash. What is refunded is the net amount the provider returned.
• Failure before sending (provider down, key rejected on submission) → retried every 5 min for up to 45 min; if it does not settle, the full amount (fee included) goes back to refund_address; REFUNDED + hash.
• PIX reversed after being paid (rare — destination account blocked) → same path: REFUNDED with a refund_tx_hash.
• Deposit different from the quoted amount → the amount actually received is paid. A different token stays in MANUAL_REVIEW.
• Deposit after expires_at → the order is revived when the deposit shows up (up to 7 days); otherwise MANUAL_REVIEW.
• Automatic ceiling: 5,000 USDT per order; above that, someone on the operations team executes it and you receive REFUNDED + hash all the same. The refund always goes out on the network and token of the deposit, from Lunium's custody address; the gas is on us.

refund_address, refund_tx_hash and deposit_from come in GET /cash-outs/{id} and in every webhook.

Incorrect deposits and recovery

After the accept, send exactly the quoted amount, in the asset and on the network that were quoted, in a single transaction, before the expires_at. The engine has a tolerance band — 90% to 105% of the quoted amount — and, within it, the PIX is calculated on what actually arrived, not on what was quoted. Outside it, the deposit is not processed automatically: it is held and becomes a manual review. Nothing is refunded to the on-chain origin automatically (same rule as refund).

payouts — PIX directly in reais unlocks at R$ 1,000

The third rail on the same key: pay any PIX key in BRL with a single POST — no crypto at the end, no QR, no accept step. You send the amount and the recipient's PIX key; the PIX goes out and you receive the event payout.sent (webhook + Telegram). Ideal for platforms that need to pay users, suppliers or commissions in reais.

Send a PIX

curl -X POST https://api.luniumpay.com/payouts \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 15000,
    "pix_key": "maria@exemplo.com", "pix_key_type": "email",
    "tax_number": "12345678901",
    "external_id": "commission-042"
  }'

const payout = await lunium('POST', '/payouts', {
  amount_cents: 15000,
  pix_key: 'maria@exemplo.com', pix_key_type: 'email',
  tax_number: '12345678901',
  external_id: 'commission-042',
});

payout = lunium("POST", "/payouts", {
    "amount_cents": 15000,
    "pix_key": "maria@exemplo.com", "pix_key_type": "email",
    "tax_number": "12345678901",
    "external_id": "commission-042",
})

{
  "payout_id": "po_4c1d9e22ab37f0885a1c",
  "status": "processing",
  "amount_cents": 15000,
  "pix_key": "ma•••@exemplo.com", "pix_key_type": "email",
  "external_id": "commission-042",
  "created_at": "2026-07-21T12:00:00.000Z"
}

Status & list

List response: { "payouts": [ … ] }. Notifications arrive on their own via webhook and Telegram — polling is optional.

Signed webhooks

Set the webhook_url (when creating the key or via PATCH /keys/me) and receive a POST on every event — cash-in and cash-out, same signature, same format:

POST {your webhook_url}
Content-Type: application/json
X-Webhook-Signature: sha256=3f5a9c…              // v1 — HMAC of the raw body
X-Lunium-Signature:  t=1786153475,v1=8b21e4…     // v2 — HMAC of "t.body" (prefer this one)
X-Lunium-Event:      cashin.settled
X-Lunium-Event-Id:   evt_9c3f21a70b5e4d8812ff0a63
X-Lunium-Delivery-Id: dlv_4f0a72c1e8b5           // changes on every attempt
X-Lunium-Attempt:    1                           // >1 = you may already have received it
X-Lunium-Timestamp:  1786153475

{
  "event": "cashin.settled",
  "event_id": "evt_9c3f21a70b5e4d8812ff0a63",   // stable across retries
  "created_at": "2026-07-20T18:34:41.000Z",
  "data": { …same format as the status endpoint… }
}

Store the event_id. It is the identity of the event and does not change on a retry — it is what keeps a retry on our side from becoming a double credit on yours. The X-Lunium-Delivery-Id is the opposite: it identifies that specific attempt, and it is the number you quote so we can find the exact delivery. And treat an unknown event as a no-op: the list grows without notice, and ignoring what you do not recognize is the correct behavior.

Verify the signature (always!)

We send two signatures, from the same secret. The v1 (X-Webhook-Signature) signs only the body and remains valid — if your handler already verifies it, change nothing. The v2 (X-Lunium-Signature) signs "<timestamp>.<raw body>" and it exists for a practical reason: since v1 carries no timestamp inside, it is valid forever — anyone who captures a delivery (a proxy log, an endpoint that changed hands) can replay that cashin.settled months later and you would credit it again. With the timestamp inside the HMAC you reject anything stale. For new integrations, use v2.

v1 status: deprecated, with a set date — shutdown on November 9, 2026 (Monday). Until then it keeps being sent normally to existing integrations and nothing breaks. Keys created from 2026-08-08 onward already receive only v2. Migrate your handler to X-Lunium-Signature before that date — the reminder also goes out in the partner group and on the changelog.

import { createHmac, timingSafeEqual } from 'node:crypto';

// use the RAW BODY (string/buffer), not the re-serialized JSON
// v2 — rejects a stale delivery, so a replay cannot credit you twice
function assinaturaValida(corpoBruto, header, secret, toleranciaSeg = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header || ''));
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranciaSeg) return false;   // too old
  const esperada = createHmac('sha256', secret).update(`${m[1]}.${corpoBruto}`).digest('hex');
  const a = Buffer.from(esperada), b = Buffer.from(m[2]);
  return a.length === b.length && timingSafeEqual(a, b);
}

app.post('/webhooks/lunium', express.raw({ type: '*/*' }), (req, res) => {
  if (!assinaturaValida(req.body, req.headers['x-lunium-signature'], process.env.LUNIUM_WEBHOOK_SECRET))
    return res.status(401).end();
  const { event, event_id, data } = JSON.parse(req.body);
  if (jaProcessei(event_id)) return res.status(200).end();   // our own retry cannot credit twice
  if (event === 'cashin.settled') creditar(data.external_id, data.usdt_amount);
  res.status(200).end();   // answer 2xx fast; process asynchronously
});

import hmac, hashlib, re, time

# v2 — rejects a stale delivery, so a replay cannot credit you twice
def assinatura_valida(corpo_bruto: bytes, header: str, secret: str, tolerancia=300) -> bool:
    m = re.match(r"^t=(\d+),v1=([0-9a-f]{64})$", header or "")
    if not m or abs(time.time() - int(m.group(1))) > tolerancia:
        return False
    esperada = hmac.new(secret.encode(), f"{m.group(1)}.".encode() + corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, m.group(2))

# Flask
@app.post("/webhooks/lunium")
def lunium_webhook():
    if not assinatura_valida(request.get_data(), request.headers.get("X-Lunium-Signature"), SECRET):
        return "", 401
    evento = request.get_json()
    if ja_processei(evento["event_id"]):        # our own retry cannot credit twice
        return "", 200
    if evento["event"] == "cashin.settled":
        creditar(evento["data"]["external_id"], evento["data"]["usdt_amount"])
    return "", 200

• Delivery: retry with exponential backoff: 12 attempts, waiting 2ⁿ minutes with a ceiling of 60 — ~7 hours in total, not a day. Any 2xx ends it. Each destination is attempted in parallel: one of your endpoints being down does not delay anyone else's events.
• Dedupe: each (operation, event) pair fires once. On your side, deduplicate by the event_id.
• Nothing is lost silently: once the attempts are exhausted, the delivery is left as failed in GET /webhooks/deliveries and you recover it with the retry below. Our operations team is alerted immediately as well — before, an event could die without anyone knowing.
• webhook_url must be https and point to a public internet address.
• Security: reject an invalid signature with 401; never process without verifying.

Test your handler before the first real one

Don't find out the endpoint was wrong when the first real PIX fails to arrive:

curl -X POST https://api.luniumpay.com/webhooks/test \
  -H "X-API-Key: $LUNIUM_KEY"

// response — what YOUR endpoint replied, measured by us
{ "ok": true, "status_code": 200, "ms": 180,
  "event_id": "evt_…", "delivery_id": "dlv_…", "url": "https://your.app/webhooks/lunium" }

Fires an event webhook.test over the same transport as production — same signatures, same headers — so whatever passes here passes there. It moves no money, does not enter the queue and works with a sandbox key too. Maximum of 6 per minute.

What went out, what failed, and how to recover

GET  /webhooks/deliveries?status=failed        // also: ?event=&limit=
POST /webhooks/deliveries/{event_id}/retry     // resends it now

The list returns status (pending · sent · failed), attempts, last_error and a failed_count — you don't need to know how to filter to find out you missed an event. The retry attempts immediately and answers with the result; if it fails again, the delivery goes back to the queue with 12 fresh attempts. Anything already confirmed with 2xx is refused with 409 ja_entregue, so you don't duplicate by accident.

Design note: the retry is addressed by the event_id because today each event has exactly one destination (one webhook_url per key) — event and delivery are 1:1. The delivery_id identifies each attempt at sending. If one day there are multiple destinations per event, a per-delivery route will appear — this one still holds.

Telegram agent — operations and support

Every Lunium customer has a real agent on Telegram: an AI (Claude, via API, with access to the account's tools), not a menu of buttons. It creates credentials, operates through natural language, notifies in real time and answers integration questions — always with your key, isolated per customer (multi-tenant).

• Credentials in the chat. Say "my name is YourCompany" (or /criarchave) and the API key is created right there, with cash-in and cash-out enabled. Self-service, at scale — nobody at Lunium generates credentials for you.
• Operates through natural language, with confirmation. Ask "charge R$ 250 from CPF …" or "withdraw 25 USDT to my PIX key": the agent reads the real data from your account, assembles the operation and asks for a confirmation tap before any movement. Money never moves without your OK.
• Notifies in real time. Every PIX that comes in, every coin bought and sold (with a Polygonscan link), every PIX that goes out, reviews and failures — the second they happen.
• In your project's group (recommended for teams). Create a group (e.g.: Lunium YourProject), add the agent and have an admin link the key: the whole team starts receiving the alerts and running queries — each group scoped to your key, with credentials and secrets always reserved for direct messages.
• Live monitor. /monitor opens a real-time web dashboard of your flow (cash-in, cash-out, payouts) — read-only and shareable with the team. Also in the monitor_url of your key. Link leaked? PATCH /keys/me with a {"rotate_monitor_token": true} rotates the token — the old URL stops showing data immediately and the new one comes in the response.
• 24/7 support. Free text — "how do I validate the webhook signature?", "I'm getting 401" — and the agent answers immediately, with examples, trained on this documentation.

Your agent's link comes in the response of POST /keys (field telegram.link) and in the GET /keys/me — one tap and the chat is linked. The commands below also work through natural language.

Who can do what — agent permissions

The agent works in your direct message (DM) and in the group that is linked. The rules are not the same in both — and it is worth understanding that before adding people to the group:

Named roles (Owner · Admin · Operator · Viewer) with per-role capabilities are on our roadmap for larger teams. Today the model is the one in the table above: queries and operations for the group, config for admins, confirmation always tied to whoever requested it.

A key without going through a human

If a tool responded erro: "chave_ausente", an agent does not need to stop and ask for credentials. POST /keys/sandbox returns a lun_test_ key in one call, with no authentication and no form — over MCP, the same thing is the tool lunium_create_sandbox_key, which requires no key at all.

It runs cash-out on the same base URL as production and nothing settles (cash-in and payouts are not simulated). Make it clear to the user that this is a test key: moving real money requires a production key, and that is a human decision.

What to expect, in numbers we measured

These are measurements, not promises — collected on 2026-08-02 against the live service.

Errors

The error contract is: erro (a stable code that does not change when the text changes), acao (what to do) and detail (human-readable text — never branch on it). Limit errors also carry limits, already converted into your order's currency. Connectivity without auth: GET /ping → {"ok":true,"msg":"pong"}.

{ "erro": "limite_diario",
  "acao": "esperar",
  "detail": "Essa cobrança (R$ 900.00) estoura seu limite diário. Disponível hoje: R$ 450.00.",
  "limits": { "daily_limit_cents": 500000, "used_today_cents": 455000 } }

The four actions

This distinction exists because two opposite situations returned the same answer: an order larger than an entire day's quota was told “try tomorrow” — and tomorrow failed the same way, forever.

All codes

The same codes come out of sandbox and production. Code that branches on erro in sandbox keeps working when you swap the key.

{ "detail": "Essa cobrança (R$ 900.00) estoura seu limite diário. Disponível hoje: R$ 450.00. …",
  "limits": { "daily_limit_cents": 500000, "used_today_cents": 455000, "available_today_cents": 45000 } }

By HTTP code

Authentication & availability (any route)

Keys (/keys)

Cash-in (/cashin)

Cash-out (/cash-outs, /catalog)

Payouts (/payouts)

Rate limits

• 60 requests/min per key (token bucket, smooth). Exceeded → 429.
• POST /keys: 5 keys/day per IP.
• Cash-out quotes have a global protection ceiling; under peak load, 503 — retry in seconds.
• Need more? Talk to us — the per-key limit is configurable.

You don't have to guess your budget. Every authenticated response carries the current state in the headers — read them instead of hitting the ceiling to find out:

X-RateLimit-Limit: 60        // your per-minute ceiling (= rate_limit_per_minute)
X-RateLimit-Remaining: 42    // how many still fit right now
X-RateLimit-Reset: 18        // seconds until the bucket refills

On a 429, you also get Retry-After: <seconds> — wait that long before retrying, with backoff. The body carries erro: "rate_limit", acao: "esperar".

Rules that prevent expensive mistakes

Each one of these has already cost money — someone's, here. They are in the main doc so they don't cost you yours.

A fixed-amount charge does not accept “close enough”

A charge QR reconciles by the exact amount and by the txid that lives inside the BR Code. Paying R$ 0.59 too much is as invisible as R$ 0.59 too little: the money arrives and the sale stays “unpaid”. If you pass a copy-and-paste code on to your customer, send the entire BR Code — not just the PIX key extracted from it. The key alone becomes a standalone transfer, with no txid, and no automatic reconciliation will ever find it.

expires_at sets the window, not your code

Always read the expires_at from the response. Today it is ~15 minutes on Polygon and up to 300 on other networks, but that changes with the network and with the provider. A window hardcoded in the client is the classic source of “I paid and it expired”.

Dates: ISO 8601 in UTC.

Every date from the API comes out in ISO 8601 in UTC, ending in Z: 2026-08-01T22:35:49.123Z. Never treat it as local time — convert on your side. The only exception is the key's daily quota, which is computed in the Brasília time zone (America/Sao_Paulo) and therefore rolls over at midnight there, not at midnight UTC. A timestamp read wrong turns into “payment past the deadline” in an argument with the merchant — and the receipt is a document of record.

delayed is not a failure

The PIX was paid and the provider is holding the release — common on a new payer's first operation. The response carries delay_until. Do not cancel it and do not create a second charge: it turns into paid on its own, and the second charge becomes duplicate money to reconcile by hand.

Absence is not proof of absence

nao_encontrado when verifying an E2E means that Lunium did not settle that payment — does not that the PIX did not happen. Another institution may have settled it. Report that difference to your user instead of alleging fraud.

external_id on every write

It is the reconciliation key and what makes the call idempotent: repeating it returns the same order instead of creating another one. Reusing the same id with different parameters returns the order original and responds external_id_divergente — on purpose, so you don't think you updated something that did not change.

Idempotency

Send the your order id in external_id (cash-in and cash-out). Repeated the call with the same external_id and the same parameters? You get back the same operation (200) — with no duplicate charge and no duplicate order. Same id with different parameters → 409. It is your protection against timeout + retry.

Security

Daily reconciliation

How to match your day against ours, without a manual spreadsheet:

1. Tie everything together with external_id (the id from YOUR system) on charges, cash-outs and payouts — it is the primary key of reconciliation.
2. Pull the day's window: GET /cashin/charges?start=2026-07-21&end=2026-07-22, GET /cash-outs?limit=200 and GET /payouts?limit=200.
3. Check against the source-of-truth fields: in cash-in, the amount that counts is depix_received_cents (what actually came in) and settlement_tx_hash (on-chain proof); in cash-out, state = COMPLETED; in payout, status = sent.
4. Webhooks are the trigger, the API is the statement: process events idempotently and reconcile from the listing — never rely on the webhook alone to close the books.

Best practices (the production checklist)

• ✅ Key server-side only; the front-end never sees it X-API-Key.
• ✅ Credit from the webhook signed (cashin.settled / cashout.completed), with HMAC verification.
• ✅ Use external_id on every operation (idempotency for free).
• ✅ Amounts: cents (int) in cash-in, decimal string in cash-out — never float.
• ✅ Handle 429/5xx with retry + exponential backoff (1s, 2s, 4s…).
• ✅ Link Telegram — it is your real-time monitor, for free.
• ✅ Trust the depix_received_cents, not the quoted amount.

Complete example — PIX checkout → USDT

A minimal helper and the entire flow (create charge → track → credit via webhook):

// lunium.js — a 15-line helper, zero dependencies (Node 18+)
const BASE = 'https://api.luniumpay.com';
export async function lunium(method, path, body) {
  const r = await fetch(BASE + path, {
    method,
    headers: {
      'X-API-Key': process.env.LUNIUM_KEY,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await r.json();
  if (!r.ok) throw new Error(data.detail || `HTTP ${r.status}`);
  return data;
}

// 1) the customer clicked "pay with PIX"
const charge = await lunium('POST', '/cashin/charge', {
  amount_cents: pedido.totalCents,
  payer_tax_number: cliente.cpf,
  payer_name: cliente.nome,
  external_id: pedido.id,            // idempotency
});
render(charge.qr_copypaste);          // 2) show the copy-and-paste code

// 3) the REAL credit arrives on the signed webhook (see Webhooks):
//    event === 'cashin.settled'  →  release the order data.external_id

import os, requests

BASE = "https://api.luniumpay.com"

def lunium(method, path, body=None):
    r = requests.request(method, BASE + path, json=body,
                         headers={"X-API-Key": os.environ["LUNIUM_KEY"]})
    data = r.json()
    if not r.ok:
        raise RuntimeError(data.get("detail", f"HTTP {r.status_code}"))
    return data

# 1) create the charge
charge = lunium("POST", "/cashin/charge", {
    "amount_cents": pedido.total_cents,
    "payer_tax_number": cliente.cpf,
    "payer_name": cliente.nome,
    "external_id": pedido.id,
})
mostrar(charge["qr_copypaste"])       # 2) show the PIX code

# 3) credit on the 'cashin.settled' webhook (Webhooks section)

Idempotency & recovery by external_id

One number that solves the two worst moments of a payment integration: the retry that must not charge/pay twice, and the 500/timeout in which you don't know whether the operation existed.

Send external_id in every write operation — cash-in, cash-out and payout. It is your reconciliation key, and the contract is the same in all three:

Recovery: find out the truth after an error

Got a 500, a timeout, or lost the response? Do not retry blindly — ask. The same idempotency key is the read key:

GET /cashin/charges?external_id=order-8812
GET /cash-outs?external_id=withdrawal-2207
GET /payouts?external_id=commission-042

Each one responds 200 with the product's list: one element if the operation exists (with its current state), empty list if it does not exist — and then it is safe to create it again with the same external_id. The unique index guarantees 0 or 1 result. It is the antidote for the payout case where "the PIX may have gone out but the response was lost": you query and you know.

Before the first real charge

Seven checks. Each one exists because it already cost money or someone's all-nighter — this is not a formality.

1. Test the webhook with POST /webhooks/test and confirm a 2xx. It is the difference between finding out your handler is wrong now or when the first PIX fails to arrive.
2. Verify the signature (X-Lunium-Signature) and reject anything older than ~5 minutes. Never process an event without verifying it.
3. Deduplicate by event_id. A retry on our side is normal; a double credit is not.
4. Send external_id on every order. It is the reconciliation key and what makes the call idempotent — repeating it returns the same order instead of creating another one.
5. Branch on erro and acao, never by the text. detail is for humans and changes without notice.
6. Read the limits from GET /keys/me (per_operation and payer_limits) instead of hardcoding values in your code — they rise on their own with your volume.
7. Join the partner group. It is where contract changes are announced before they go live, and where you talk to us when it cannot wait.

The sandbox charges nothing and moves no money: POST /keys/sandbox returns a lun_test_… instantly, and all 7 items above can be exercised end to end there.

Versioning & changelog

Compatibility policy: changes that are additive (new fields in responses, new events, new codes for erro, new endpoints) happen without notice — write your parser to ignore unknown fields and handle an unknown event or code by whatever the acao says. Changes that break the contract (removing or renaming a field, changing semantics) are announced in advance.

Where the notice goes out, in order of reach: in the partner group on Telegram, in your key's bot and in this table. If you registered an e-mail in POST /keys, by e-mail as well — but most keys have no e-mail, so do not rely on it alone: join the group.

The OpenAPI is the contract. info.version in openapi.json goes up by a MINOR on every compatible addition and by a MAJOR if something breaks. An automated test checks, every 6 hours, whether production still does what that file promises — when it diverges, we are notified before you are.

Support & contact

⬡ Lunium — the PIX ↔ stablecoin hub. This documentation describes the current behavior of the API in production; contract-breaking changes are announced in advance in the partner group, in your key's bot and in the changelog.

ENVIRONMENT: PRODUCTION · 24/7 MONITORING · CONTATO@LUNIUMPAY.COM