# LYNX: API de pagamentos PIX (BRL)

> LYNX é uma plataforma brasileira de pagamentos via PIX para desenvolvedores.
> Você pode: receber por PIX (QR Code dinâmico + copia-e-cola), criar checkouts
> hospedados (links de pagamento), enviar saques (PIX de saída) e receber
> notificações em tempo real por webhooks assinados.
> API REST, respostas em JSON, envelope consistente { "data": ..., "error": ... }.
> Todos os valores monetários são INTEIROS em CENTAVOS (ex.: 4990 = R$ 49,90).
> IMPORTANTE: só existem os endpoints listados abaixo. NÃO há SDK oficial, nem
> recursos de clientes, produtos ou cupons na API. Use HTTP puro em qualquer linguagem.

Documentação: https://lynxpix.cc/docs
Painel do desenvolvedor: https://lynxpix.cc/app/developer

## URL base
https://lynxpix.cc/api/v1

## Autenticação
Envie sua chave em CADA requisição:
- Header: `Authorization: Bearer <SUA_CHAVE>`  (ou `X-API-Key: <SUA_CHAVE>`)
- Chaves de teste começam com `lynx_test_` (sandbox; não move dinheiro real).
- Chaves de produção começam com `lynx_live_` (dinheiro real; use apenas no servidor).
- Cada chave tem ESCOPOS (permissões) e pode ter EXPIRAÇÃO. Gere em Painel → API.

## Escopos (permissões)
PIX:CREATE    : criar cobranças PIX (QR Code)
PIX:READ      : consultar cobranças PIX
BOLETO:CREATE : emitir boletos híbridos (linha digitável + Pix do mesmo título)
BOLETO:READ   : consultar boletos
BOLETO:PAY    : consultar e PAGAR boletos/tributos de terceiros (débito do saldo)
BILLING:CREATE: criar checkouts / links de pagamento
BILLING:READ  : listar checkouts
WITHDRAW:CREATE: criar saques (PIX de saída)
STORE:READ    : ler dados da conta
TRANSACTION:READ: listar transações
Requisição sem o escopo necessário retorna 403.

## Convenções
- Sucesso: { "data": {...}, "error": null }
- Erro:    { "data": null, "error": "mensagem legível" } + status HTTP apropriado
- Dinheiro sempre em centavos (integer). Ex.: 4990 = R$ 49,90.
- Status de cobrança: PENDING | PAID | EXPIRED | FAILED.
- Status de saque: PENDING | PAID | FAILED.

# ==========================================================================
# ENDPOINTS (todos reais e executáveis)
# ==========================================================================

## GET /v1/store   (escopo STORE:READ)
Dados da conta e modo atual.
Resposta:
{ "data": { "id": "usr_123", "name": "Minha Loja", "email": "loja@exemplo.com", "mode": "test", "devMode": true, "balance": 128040, "available": 128040, "tier": "starter" }, "error": null }
Exemplo:
curl https://lynxpix.cc/api/v1/store \
  -H "Authorization: Bearer lynx_test_sua_chave"

## POST /v1/pixQrCode/create   (escopo PIX:CREATE)
Cria uma cobrança PIX (QR dinâmico + copia-e-cola). O valor cai na sua conta ao pagar.
Body:
{ "amountCents": 4990, "description": "Pedido #1234", "expiresIn": 3600,
  "customer": { "name": "João Silva", "email": "joao@exemplo.com", "cellphone": "11999999999", "taxId": "123.456.789-00" },
  "metadata": { "orderId": "1234" } }
- amountCents é OBRIGATÓRIO, inteiro, mínimo 200 (R$ 2,00).
- passFee (opcional): se true, a taxa é somada ao valor pago pelo pagador (você recebe o valor cheio).
Resposta:
{ "data": { "id": "chg_9f8a2c1e", "kind": "pixQrCode", "status": "PENDING", "amount": 4990, "netAmount": 4960,
  "brCode": "00020126850014br.gov.bcb.pix...6304AB12", "brCodeBase64": "data:image/png;base64,iVBORw0KG...",
  "expiresAt": "2026-07-01T13:00:00Z", "createdAt": "2026-07-01T12:00:00Z", "devMode": true }, "error": null }
Exemplos:
curl -X POST https://lynxpix.cc/api/v1/pixQrCode/create \
  -H "Authorization: Bearer lynx_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":4990,"description":"Pedido #1234","customer":{"name":"João Silva"}}'
// Node.js
const res = await fetch("https://lynxpix.cc/api/v1/pixQrCode/create", {
  method: "POST",
  headers: { "Authorization": "Bearer lynx_test_sua_chave", "Content-Type": "application/json" },
  body: JSON.stringify({ amountCents: 4990, description: "Pedido #1234" })
});
const { data, error } = await res.json();
# Python
import requests
res = requests.post("https://lynxpix.cc/api/v1/pixQrCode/create",
  headers={"Authorization": "Bearer lynx_test_sua_chave"},
  json={"amountCents": 4990, "description": "Pedido #1234"})
print(res.json())

## GET /v1/pixQrCode/check?id=chg_xxx   (escopo PIX:READ)
Consulta o status de uma cobrança. Query: id (obrigatório).
Resposta:
{ "data": { "id": "chg_9f8a2c1e", "status": "PAID", "amount": 4990, "paidAt": "2026-07-01T12:03:11Z",
  "payer": { "name": "Maria Souza", "document": "123.456.789-00", "bank": "NU PAGAMENTOS" },
  "endToEndId": "E18935924202607011203apiv1x9f8a2" }, "error": null }

## POST /v1/pixQrCode/simulate-payment   (escopo PIX:CREATE, SOMENTE chaves de teste)
Marca a cobrança como paga e dispara o webhook pixQrCode.paid: sem mover dinheiro real.
Body: { "id": "chg_9f8a2c1e" }
Resposta: { "data": { "id": "chg_9f8a2c1e", "status": "PAID", "paidAt": "2026-07-01T12:03:11Z", "devMode": true }, "error": null }
Obs.: com chave lynx_live_ retorna 403.

## POST /v1/boleto/create   (escopo BOLETO:CREATE)
Emite um boleto bancário registrado e HÍBRIDO: o pagador paga a linha digitável em qualquer banco/lotérica
OU o Pix Copia e Cola do MESMO título — qualquer um dos dois liquida a mesma cobrança.
A taxa só é cobrada quando o boleto é pago; boleto emitido e não pago não gera cobrança nenhuma.
Body:
{ "amountCents": 15000,                    // obrigatório, mínimo 500 (R$ 5,00)
  "description": "Pedido #1234",           // opcional
  "payer": {                               // obrigatório: dados REAIS (título registrado)
    "name": "João da Silva",               // nome completo, sai impresso no boleto
    "document": "12345678909",             // CPF (11) ou CNPJ (14), só números
    "cep": "01310100" },                   // 8 dígitos
  "dueDays": 3,                            // opcional, 1 a 5 (padrão 3)
  "passFee": false,                        // opcional: se true, taxa somada ao valor do boleto
  "metadata": { "orderId": 123 } }         // opcional
Resposta 200:
{ "data": { "id": "bol_9f8a2c1e", "kind": "boleto", "method": "BOLETO", "status": "PENDING",
  "amount": 15000, "netAmount": 14330,
  "boleto": { "ourNumber": "600000064",
    "digitableLine": "74891160090000642205902991121050115340000000500",
    "barcode": "74891153400000005001160000006422050299112105",
    "dueDate": "2026-07-18T02:59:59Z" },
  "brCode": "00020126910014br.gov.bcb.pix...",   // Pix Copia e Cola do próprio boleto
  "brCodeBase64": "data:image/png;base64,...",
  "pdfUrl": "https://.../api/boleto/bol_9f8a2c1e/pdf",   // PDF pronto do boleto (público, sem auth)
  "expiresAt": "2026-07-18T02:59:59Z", "createdAt": "2026-07-15T12:00:00Z" }, "error": null }
Regras: pagamento parcial não é aceito; boleto vencido é cancelado automaticamente (sem protesto);
pagamento pelo Pix confirma em segundos, pela linha digitável em outro banco pode levar 1 dia útil.
Confirmação: webhook boleto.paid (mesmo formato dos demais eventos).

## GET /v1/boleto/check?id=bol_xxx   (escopo BOLETO:READ)
Consulta o status de um boleto. Query: id (obrigatório). PENDING não é falha: compensação fora do Pix leva até 1 dia útil.

## POST /v1/boleto/simulate-payment   (escopo BOLETO:CREATE, SOMENTE chaves de teste)
Marca o boleto como pago e dispara o webhook boleto.paid: sem mover dinheiro real.

## POST /v1/boleto/query   (escopo BOLETO:PAY)
Consulta um boleto bancário ou tributo/convênio (água, luz, telefone, DARF, IPVA) que VOCÊ quer pagar,
a partir da linha digitável (47/48 dígitos) ou do código de barras (44). Somente leitura, não move saldo.
Body: { "barcode": "34191790010104351004791020150008291070026000" }
Resposta (data): { quoteId, type ("boleto"|"tributo"), bank, beneficiary, dueDate, payable,
  paymentWindow: { open, reason? },
  amounts: { original, interest, fine, discount, rebate, final },   // final = valor do dia, em centavos
  fees: { providerCents, lynxCents, totalCents },
  totalDebitCents,                        // final + taxas = o que sai do seu saldo
  quoteExpiresInSeconds }                 // ~300s; o quoteId trava o valor cotado
Regras: consulte SEMPRE antes de pagar (o valor muda com a data: juros/multa/desconto).
Tributo/convênio vem com bank e beneficiary null (a base de convênios não registra esses dados).

## POST /v1/boleto/pay   (escopo BOLETO:PAY)
Paga o boleto cotado: debita valor + taxas do saldo na hora; a liquidação é assíncrona.
Body: { "quoteId": "bq_...", "externalId": "seu-id-idempotente" }
Resposta (data): { id, status: "PENDING", method: "BOLETO", amountCents, feeCents, totalDebitCents }
Acompanhe por GET /v1/transaction/list ou pelos webhooks withdraw.done / withdraw.failed.
Se falhar, o débito (valor + taxa) é estornado integralmente.
Regras: pagamento parcial não é aceito; cada título só pode ser pago uma vez (409 se já pago);
horário: boletos bancários em dias úteis até 22h, contas/tributos até 18h (fora disso: 400, nada debitado);
valor máximo R$ 30.000,00 por título.
Body: { "id": "bol_9f8a2c1e" }

## POST /v1/billing/create   (escopo BILLING:CREATE)
Cria um checkout hospedado (link de pagamento) e retorna a URL pronta.
Body: { "title": "Curso de PIX", "amountCents": 9990, "description": "...", "openAmount": false, "passFee": false }
- Use amountCents (>=200) para valor fixo, OU openAmount:true para o cliente escolher o valor.
- passFee:true repassa a taxa ao pagador.
PERSONALIZAÇÃO TOTAL (todos opcionais: os mesmos campos do editor do painel, mesma sanitização):
- layout: "full" (página de venda, padrão) | "simple" (link de cobrança enxuto)
- collectFields: { "name": bool, "email": bool, "whatsapp": bool, "cpf": bool }: quais dados pedir ao pagador (todos false = checkout anônimo)
- ctaText, accentColor (#hex), imageUrl (banner 16:9), logoUrl, merchantDisplayName
- gallery: [até 8 URLs], videoUrl (YouTube, incorporado), badges: [até 6 selos de 40 chars]
- benefits: [{ "icon": "zap|check|star|shield|gift|clock|heart|trophy|book|download|video|infinity|award|users|chat|rocket", "text": "..." }] (máx 10)
- guarantee: { "enabled", "days", "text" } · testimonials: [{ "name", "text", "rating" }] · faq: [{ "q", "a" }] · scarcity: { "enabled", "minutes" }
- orderBump: { "enabled", "title", "description", "priceCents", "imageUrl" }
- delivery: { "type": "link|whatsapp|both|file", "accessUrl", "message", "autoRedirect", "fileId", "fileName" } · supportWhatsapp (DDI+DDD)
  ENTREGA AUTOMÁTICA: o link/arquivo só é revelado ao comprador APÓS o pagamento confirmar.
  type "link": accessUrl é o link secreto (área de membros, Drive); autoRedirect true redireciona em 5s.
  type "file": suba o arquivo antes em POST /v1/files/upload (multipart, máx 15MB) e use o "id" em fileId.
- quickAmounts: [centavos] e askNote: bool (só com openAmount:true)
Resposta:
{ "data": { "id": "chk_1a2b3c", "url": "https://lynx.app/pay/curso-de-pix-25ff60", "title": "Curso de PIX",
  "amount": 9990, "openAmount": false, "status": "active", "devMode": true }, "error": null }

## POST /v1/billing/single-use/create   (escopo BILLING:CREATE)
Cria uma cobrança de USO ÚNICO: URL exclusiva que aceita UM único pagamento PIX.
Ciclo de vida: PENDING → PAID (primeiro pagamento confirmado) ou EXPIRED (prazo vencido).
Depois de PAID a URL continua acessível mas mostra "Esta cobrança já foi paga." (sem QR Code);
o bloqueio do segundo pagamento é ATÔMICO no servidor.
Headers opcionais: Idempotency-Key: fatura_123456 → reenvios com a mesma chave devolvem o
checkout JÁ criado (retry seguro por timeout: nunca duplica a cobrança).
Body:
{ "title": "Renovação do plano", "amountCents": 5000, "description": "Renovação mensal",
  "externalReference": "fatura_123456", "expiresIn": 2592000, "passFee": false,
  "customer": { "name": "João", "email": "joao@email.com", "cellphone": "11999998888", "taxId": "12345678900" },
  "metadata": { "clienteId": "123", "usuario": "cliente123" } }
- amountCents >= 200 (R$ 2,00); respeita o limite por transação da conta.
- expiresIn em segundos (padrão 2592000 = 30 dias; mín 300, máx 90 dias).
- PERSONALIZAÇÃO TOTAL: aceita TODOS os campos de personalização do /v1/billing/create
  (layout "simple" padrão | "full", collectFields, ctaText, accentColor, imageUrl, logoUrl,
  merchantDisplayName, gallery, videoUrl, benefits, badges, guarantee, testimonials, faq,
  scarcity, orderBump, delivery, supportWhatsapp): veja a lista completa na seção acima.
- externalReference: sua referência de fatura: volta no check e no webhook para conciliação.
Resposta:
{ "data": { "id": "chk_single_1a2b3c", "url": "https://lynx.app/pay/fatura-123456-9f8a2c",
  "status": "PENDING", "singleUse": true, "amount": 5000, "externalReference": "fatura_123456",
  "expiresAt": "2026-08-21T15:00:00Z", "createdAt": "2026-07-22T15:00:00Z" }, "error": null }

## GET /v1/billing/single-use/check?id=chk_single_1a2b3c   (escopo BILLING:READ)
Consulta o status da cobrança de uso único (retaguarda do webhook; a confirmação primária é billing.paid).
Resposta (paga):
{ "data": { "id": "chk_single_1a2b3c", "status": "PAID", "amount": 5000, "netAmount": 4950,
  "externalReference": "fatura_123456", "paidAt": "2026-07-22T15:05:20Z",
  "payer": { "name": "João Silva", "document": "12345678900", "bank": "NU PAGAMENTOS" },
  "endToEndId": "E123456789...", "metadata": { "clienteId": "123" } }, "error": null }
- status possíveis: PENDING | PAID | EXPIRED (EXPIRED é definitivo: crie outra cobrança).

## Uso único pelo PAINEL (sem API)
Os 3 modelos de página do painel (Vendas) podem ser criados como USO ÚNICO:
Link rápido, Link de cobrança e Página de venda → opção "Uso único" na criação.
- Mesma máquina de estados da API: PENDING → PAID (1º pagamento) | EXPIRED (validade vencida).
- Bloqueio ATÔMICO no servidor: um único QR compartilhado por link; o segundo pagamento é
  rejeitado (409) e a página passa a mostrar "Esta cobrança já foi paga.".
- Validade configurável na criação: 24h, 3 dias, 7 dias, 30 dias (padrão) ou 90 dias.
- A opção não pode ser alterada depois de criada (protege o bloqueio atômico).
- Compatível com "Repassar taxa" e com os parâmetros ocultos de rastreio (seção abaixo):
  https://lynx.app/pay/{slug}?cliente=joao&pedido=A77 grava o rastreio em metadata mesmo em uso único.
- O card em Vendas mostra o estado: "Uso único" (aguardando), "Pago ✓" ou "Expirado".

## Parâmetros ocultos de rastreio nos links de pagamento
Qualquer link /pay/{slug} (checkout reutilizável OU uso único) aceita query string arbitrária:
  https://lynx.app/pay/abc123?cliente=joao_silva&plano=mensal&id_gestor=4471
- Invisíveis para o pagador; gravados na transação em metadata.
- Aparecem para o lojista em: detalhes da transação, pedidos da página, extrato, exportações CSV/PDF
  e no webhook billing.paid dentro de data.metadata.
- Limites: máx 10 parâmetros; chave até 40 chars (A-Za-z0-9_.-); valor até 200 chars (sanitizado no servidor).
- SOMENTE rastreio: nunca alteram valor/taxa/destinatário, mesmo com nomes como "valor" ou "amount".
- Atenção: visíveis na URL do pagador: nunca inclua dados sensíveis.

## Webhook billing.paid (payload)
data inclui: id, kind, status, amount, netAmount, paidAt, payer { name, document, bank },
endToEndId, singleUse (true para cobranças de uso único), externalReference e metadata
(metadata da criação + parâmetros ocultos do link). Use externalReference/metadata para conciliar.

## GET /v1/billing/list   (escopo BILLING:READ)
Lista os checkouts criados via API (mais recentes primeiro).
Resposta: { "data": [ { "id": "chk_1a2b3c", "url": "https://lynx.app/pay/...", "title": "Curso de PIX", "amount": 9990, "openAmount": false, "sales": 3, "status": "active" } ], "error": null }

## POST /v1/withdraw/create   (escopo WITHDRAW:CREATE)
Envia um PIX de saída do seu saldo. Em teste é simulado; em produção valida saldo e limites.
Body: { "amountCents": 5000, "pixKey": "joao@exemplo.com", "pixKeyType": "EMAIL", "beneficiaryName": "João Silva", "description": "..." }
- pixKeyType: CPF | CNPJ | EMAIL | PHONE | EVP.
- recipientDocument (opcional): CPF/CNPJ do titular da chave, somente dígitos. Se informado, o saque é recusado caso não pertença ao dono da chave (proteção extra). Omita para sacar sem validação de documento.
- passFee (opcional): se true, o destino recebe o valor cheio e a taxa é somada por cima (debitada do seu saldo).
Resposta: { "data": { "id": "wd_1a2b3c", "kind": "withdraw", "status": "PAID", "amount": 5000, "devMode": true }, "error": null }

## GET /v1/transaction/list   (escopo TRANSACTION:READ)
Lista cobranças e saques feitos pela API (mais recentes primeiro).
Resposta: { "data": [ { "id": "chg_9f8a2c1e", "kind": "pixQrCode", "status": "PAID", "amount": 4990, "paidAt": "..." } ], "error": null }

# ==========================================================================
# MÓDULO DE VENDAS (escopos STORE:READ / STORE:MANAGE)
# ==========================================================================

## POST /v1/files/upload   (escopo STORE:MANAGE)
Upload de arquivo de ENTREGA AUTOMÁTICA (multipart/form-data, campo "file", máx 15MB).
curl -X POST https://lynxpix.cc/api/v1/files/upload -H "Authorization: Bearer lynx_test_sua_chave" -F "file=@ebook.pdf"
Resposta: { "data": { "id": "file_9f8a2c", "filename": "ebook.pdf", "contentType": "application/pdf", "size": 482133 }, "error": null }
Fluxo: 1) suba o arquivo → pegue o id; 2) crie o checkout com
delivery: { "type": "file", "fileId": "file_9f8a2c", "fileName": "ebook.pdf", "message": "Obrigado!" }.
O download só é liberado ao comprador com o pedido PAGO; o arquivo só funciona em checkouts SEUS.

## GET|POST /v1/products   (GET: STORE:READ · POST: STORE:MANAGE)
Catálogo de produtos. POST sem id cria; com id edita; { "id", "delete": true } exclui.
Body: { "title": "Curso de PIX", "description": "...", "priceCents": 9990, "imageUrl": "...", "status": "active|archived" }

## GET|POST /v1/coupons   (GET: STORE:READ · POST: STORE:MANAGE)
Cupons de desconto dos checkouts. POST sem id cria; com id edita; { "id", "delete": true } exclui.
Body: { "code": "BEMVINDO10", "type": "percent|fixed", "percent": 10, "fixedCents": 0,
  "applyScope": "subtotal|base", "appliesTo": "all|selected", "checkoutIds": [], "maxUses": 100,
  "minAmountCents": 0, "expiresAt": "2026-12-31", "status": "active|paused" }

## GET|POST /v1/themes   (GET: STORE:READ · POST: STORE:MANAGE)
Temas reutilizáveis de checkout. POST sem id cria; { "id", "setDefault": true } define padrão; { "id", "delete": true } exclui.
Body: { "name": "Tema da loja", "config": { "accentColor": "#7C3AED", "ctaText": "Comprar agora", ... }, "isDefault": true }

## GET|PUT /v1/tracking   (GET: STORE:READ · PUT: STORE:MANAGE)
Pixels de rastreamento globais aplicados a TODOS os checkouts. String vazia remove.
Body (PUT): { "metaPixelId": "1234567890", "googleAdsId": "AW-123456789", "googleAdsLabel": "...", "utmifyPixelId": "" }

# ==========================================================================
# WEBHOOKS
# ==========================================================================
Configure a URL em Painel → API → Webhooks. Enviamos um POST assinado a cada evento.
Eventos: pixQrCode.paid | pixQrCode.failed | boleto.paid | billing.paid | withdraw.done | withdraw.failed
Payload (id evt_... é ESTÁVEL entre retentativas: deduplique por ele):
{ "id": "evt_9f8a2c1e", "event": "pixQrCode.paid", "devMode": false, "createdAt": "2026-07-01T12:03:11Z",
  "data": { "id": "chg_9f8a2c1e", "kind": "pixQrCode", "status": "PAID", "amount": 4990, "netAmount": 4960,
    "paidAt": "2026-07-01T12:03:11Z", "payer": { "name": "Maria Souza", "document": "123.456.789-00", "bank": "NU PAGAMENTOS" },
    "endToEndId": "E18935924202607011203apiv1x9f8a2", "failureReason": null } }
Em *.paid/withdraw.done: data.status = "PAID" com paidAt, payer e endToEndId preenchidos.
Em *.failed: data.status = "FAILED"/"CANCELED" com failureReason.
Segurança em 2 camadas:
1) O secret (whsec_...) vai no header X-Lynx-Webhook-Secret (checagem rápida de igualdade).
2) O corpo é assinado com HMAC SHA-256 no header:
   X-Lynx-Signature: t=<timestamp>,v1=<hmac>
Verificação (Node.js):
import crypto from "crypto";
function verify(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
Verificação (Python):
import hmac, hashlib
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=") for p in signature_header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts["v1"], expected)
Boas práticas: responda 2xx em poucos segundos; processe de forma assíncrona;
trate reentregas de forma IDEMPOTENTE (use o campo "id"); valide SEMPRE a assinatura antes de creditar.

# ==========================================================================
# MCP SERVER (para agentes de IA)
# ==========================================================================
Endpoint (Streamable HTTP / JSON-RPC 2.0): https://lynxpix.cc/api/mcp
Auth: header Authorization: Bearer <sua_chave> (respeita os escopos da chave)
Ferramentas (tools):
- get_store            (STORE:READ)        -> dados da conta e saldo
- create_pix_qrcode    (PIX:CREATE)        args: amountCents(int, obrig.), description?, customerName?
- check_pix_qrcode     (PIX:READ)          args: id(obrig.)
- simulate_pix_payment (PIX:CREATE, teste) args: id(obrig.)
- create_billing       (BILLING:CREATE)    args: title(obrig.), amountCents?, description?, openAmount?
- list_billings        (BILLING:READ)
- create_withdraw      (WITHDRAW:CREATE)    args: amountCents(obrig.), pixKey(obrig.), pixKeyType?, beneficiaryName?, description?
- list_transactions    (TRANSACTION:READ)

Config: Claude Desktop (claude_desktop_config.json) / Windsurf (~/.codeium/windsurf/mcp_config.json):
{ "mcpServers": { "lynx": { "command": "npx", "args": ["-y", "mcp-remote@latest", "https://lynxpix.cc/api/mcp", "--header", "Authorization:Bearer lynx_test_sua_chave"] } } }
Config: Cursor (~/.cursor/mcp.json):
{ "mcpServers": { "lynx": { "url": "https://lynxpix.cc/api/mcp", "headers": { "Authorization": "Bearer lynx_test_sua_chave" } } } }
Config: VS Code (.vscode/mcp.json):
{ "servers": { "lynx": { "type": "http", "url": "https://lynxpix.cc/api/mcp", "headers": { "Authorization": "Bearer lynx_test_sua_chave" } } } }
Config: Gemini CLI (~/.gemini/settings.json):
{ "mcpServers": { "lynx": { "httpUrl": "https://lynxpix.cc/api/mcp", "headers": { "Authorization": "Bearer lynx_test_sua_chave" } } } }
Teste rápido (listar ferramentas):
curl -X POST https://lynxpix.cc/api/mcp \
  -H "Authorization: Bearer lynx_test_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ==========================================================================
# ERROS (HTTP)
# ==========================================================================
200 OK | 400 parâmetros inválidos/faltando | 401 chave ausente/inválida/revogada/expirada |
403 sem o escopo necessário | 404 recurso não encontrado | 502 falha temporária no provedor PIX.
Formato: { "data": null, "error": "Chave de API inválida ou revogada." }

# ==========================================================================
# FLUXO RECOMENDADO (sandbox)
# ==========================================================================
1) Pegue a chave lynx_test_ em Painel → API.
2) POST /v1/pixQrCode/create           -> pegue o "id".
3) POST /v1/pixQrCode/simulate-payment { "id": "..." } -> dispara o webhook pixQrCode.paid.
4) Configure o webhook e valide a assinatura HMAC.
5) Troque para lynx_live_ ao ir para produção (nunca exponha a chave live no frontend).

## Suporte
Pelo painel da LYNX ou pela documentação em /docs.