通过 API 兑换 BRL ↔ USDT

适用对象

• 需要在生产环境运行 BRL → USDT 及 USDT → BRL 的金融科技平台和企业。
• 每天进行兑换，并希望先查看价格再决策的财资团队。
• 希望将交易所手动操作，升级为有接口契约、状态跟踪及凭证的自动流程的企业。

面临的问题

BRL 与 USDT 兑换的不确定性，往往来自决策与执行之间的价格变化，以及依赖人工登录操作的流程。前者可能带来隐性损失，后者限制业务处理时间。

关键是区分 报价 的 执行。预览使用与真实订单相同的计价规则、结算方式、最低金额及拒绝条件，但不保存订单。先展示金额，由用户决定，再按实际订单的接受流程锁定报价。

完整交易流程

1. 预估： POST /cashin/preview （BRL → 加密资产）或 POST /cash-outs/preview （加密资产 → BRL），均不创建订单。
2. 预览返回结算方式（path）、数量，以及购买路由适用的最低 BRL 金额。
3. 购买： POST /cashin/charge 生成 Pix 收款单；付款确认并满足适用条件后，向指定钱包交付加密资产。
4. 卖出： POST /cash-outs + /accept 返回充值地址；充值确认后执行 Pix 付款。
5. 每笔交易均有 external_id、签名 webhook 及凭证，可用于自动对账。

使用的接口

可运行示例

# 创建订单前查询双向报价
curl -X POST https://api.luniumpay.com/cashin/preview -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":100000,"asset":"usdt","chain":"polygon"}'

curl -X POST https://api.luniumpay.com/cash-outs/preview -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset":"USDT","network":"polygon","amount":"1000"}'

const h = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };

// BRL -> USDT：R$X 可获得的加密资产数量，须满足通道最低金额
export async function comprar(cents) {
  const p = await (await fetch(`${API}/cashin/preview`, { method: "POST", headers: h,
    body: JSON.stringify({ amount_cents: cents, asset: "usdt", chain: "polygon" }) })).json();
  return { usdt: p.usdt_amount ?? p.amount, minimoBrlCents: p.min_brl_cents };
}

// USDT -> BRL：N USDT 可支付的 Pix 金额，不创建订单
export async function vender(qtd) {
  const p = await (await fetch(`${API}/cash-outs/preview`, { method: "POST", headers: h,
    body: JSON.stringify({ asset: "USDT", network: "polygon", amount: String(qtd) }) })).json();
  return { brl: p.brl_amount, trilho: p.path };
}

import os, requests

API, H = "https://api.luniumpay.com", {"X-API-Key": os.environ["LUNIUM_KEY"]}

def comprar(cents):
    p = requests.post(f"{API}/cashin/preview", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdt", "chain": "polygon"}).json()
    return p.get("usdt_amount") or p.get("amount"), p.get("min_brl_cents")

def vender(qtd):
    p = requests.post(f"{API}/cash-outs/preview", headers=H, timeout=30, json={
        "asset": "USDT", "network": "polygon", "amount": str(qtd)}).json()
    return p["brl_amount"], p["path"]

测试环境：先验证，再使用真实资金

只需一次调用，无需预先审批或绑定银行卡，仅测试人员邮箱为必填项，手册、流程图及接入步骤将发送至该邮箱。 lun_test_ 密钥可用于验证文档列出的功能，不涉及真实资金。

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","name":"meu-teste"}'

测试环境无法 不 证明真实结算。不会转移加密资产或支付真实 Pix；它用于验证接口契约，不能衡量实际结算渠道。

资产与网络

加密资产入金目录为 GET /catalog；Pix 收款后的交付目录为 GET /cashin/catalog。报价前，请查询所选流程的资产及网络。可用性和最低金额可能变化。

使用 deposit_tag 处理需要 memo 的充值；交付时，若路由要求，还须传入 payout_tag 。有关各字段， API 手册 提供了完整说明。

限额与资金冻结

查询 GET /keys/me 查询账户限额及费用，通过 GET /cashin/limits?payer_tax=... 查询付款人额度，并通过预览查询路由最低金额。不要为 cash-in、cash-out 及 Pix 对外付款共用固定上限。

收款单已付款后，仍可能等待资金解冻才能结算。通过状态、时间线及签名事件，区分款项收到、余额可用及最终交付。交易有效期见 expires_at。

依据实际跟踪，不作固定时效承诺

处理时间取决于流程、可用路由、网络确认及可能的资金冻结。请跟踪至最终状态，并查询 服务状态。模拟耗时不代表真实结算时间。

幂等性

传入 external_id 于支持该字段的资金操作中。重复相同请求会返回 同一笔 交易，不会新建第二笔。相同参数配合不同 ID 可能创建两笔交易；相同 ID 配合不同参数则返回 409 external_id_divergente ，而不会擅自猜测。

超时不等于拒绝。未收到响应时，须先通过 external_id 查询，原交易可能已经存在。

Webhook 与对账

状态变化通过带时间戳的 HMAC SHA-256 签名事件通知，请求头为 X-Lunium-Signature，格式为 t=…,v1=…。校验时间戳有效期可防止已捕获事件被重放；信任请求体前，须先完成验签。

Webhook 是主要通知方式，也可辅以轮询。查询状态时，请根据 timeline 中记录的 服务器时间 展示阶段，因为轮询计时器测得的是您的查询间隔，不能代表交易实际耗时。

未收到 2xx 时，系统按退避策略重试。可通过以下接口手动重发： POST /webhooks/deliveries/{event_id}/retry ；测试接收端 URL 使用 POST /webhooks/test。

异常处理

低于最低金额： 拒绝响应会列明数值；购买流程的 min_brl_cents 已包含在预览中，可在用户输入前展示最低金额。

超过最高金额： valor_acima_do_maximo 会返回当前上限。请通过 GET /keys/me 读取，不要固定写入代码，限额可能因合同条件变化。

报价过期： 订单包含 expires_at。请勿在过期后发送；需要新交易时须重新报价。如资金已发出，继续跟踪原订单并按其处理说明操作。

安全机制

• Webhook 签名 — Webhook 使用带时间戳的 HMAC SHA-256 签名，位于 X-Lunium-Signature，格式为 t=…,v1=…。须验证签名及时间戳有效期，以防重放。
• 幂等性 — Cash-in、cash-out 及 Pix 对外付款使用 external_id。相同内容重试返回同一交易，不创建第二笔；同一 external_id 配合不同参数会返回 409。
• 出站连接验证 — 每次投递前解析并验证 webhook URL，拒绝内网地址、云元数据地址及跳转至私网的重定向，并将连接固定至已验证 IP。
• 冻结限制默认拒绝放行 — 结算时检查资金冻结，并在 SQL 任务领取时再次校验，防止 worker、状态查询或队列提前结算。
• 付款持久化 — 提现会在调用服务商前，于同一数据库事务内保存订单并扣减余额，确保每笔扣款均有可对账的订单。
• 公开核验 — GET /v1/verificar/{e2e} 无需密钥即可核验已结算 Pix，交易对方可自行验证。

公开核验有助于交易对方独立检查 Pix，无需 API 密钥或人工确认。

从哪里开始接入

第一个实用功能可从预览开始：一次调用，不执行交易，即可用于界面展示。之后再基于已测试的接口契约实现实际执行。

接入常见问题