Lexxen Hub · Pix ⇄ cripto

Documentação da API

Guia completo para integrar com a API do Lexxen Hub: on-ramp (Pix → cripto), off-ramp (venda de cripto → Pix/BRL) e transferências entre carteiras. O cliente paga em BRL via Pix e a stablecoin (USDC ou USDT) cai direto em uma wallet_address informada.

Copiar para IA (.md) Postman

Base URL

https://cashout.lexxen.com/api/v1

Versão

Formato

JSON · ISO 8601

Base URL

Todos os endpoints são relativos a esta base. O path usado na assinatura vai sem a barra inicial.

Base URL

https://cashout.lexxen.com/api/v1

Sandbox e produção usam a mesma URL. O que muda é a chave: lxn_test_… ativa o sandbox (providers simulados, nenhum dinheiro real se move); lxn_… é produção. Use o seletor Sandbox / Produção no topo para alternar os exemplos.

Fluxo recomendado

Valide o endereço (opcional)

POST /wallets/validate antes de cobrar.

Crie a cotação

POST /quotes → guarde o quote_id e mostre o resumo.

Crie o pedido

POST /orders com o quote_id → gere o QR pelo pix_copy_paste.

Acompanhe o status

GET /orders/{id} e/ou o webhook transaction.completed.

Autenticação

Toda requisição deve ser assinada com HMAC-SHA256. Inclua os headers abaixo em todas as chamadas.

Headers obrigatórios

X-API-KeyA api_key do tenant: lxn_… em produção ou lxn_test_… no sandbox (mesma URL, providers simulados).

X-TimestampTimestamp Unix em segundos (válido por ±60s).

X-SignatureAssinatura HMAC-SHA256 (saída em hex).

Content-Typeapplication/json

Acceptapplication/json

Gerando a assinatura

A assinatura é HMAC-SHA256 sobre timestamp + METHOD + path + body — o timestamp vem PRIMEIRO.

payload = TIMESTAMP + METHOD + PATH + BODY
signature = HMAC-SHA256(payload, api_secret) // hex

Regras

METHOD em MAIÚSCULAS (POST/GET).
path sem barra inicial e sem query string.
body = corpo cru exatamente como enviado (string vazia em GET).
Timestamp válido por ±60s · assinatura de uso único (anti-replay ~120s).

Segurança

Nunca exponha o api_secret no frontend. Assine sempre no servidor.

$timestamp = (string) time();
$method = 'POST';
$path = 'api/v1/quotes'; // sem barra, sem query
$body = json_encode($data);

$payload = $timestamp . strtoupper($method) . $path . $body;
$sig = hash_hmac('sha256', $payload, $apiSecret);

const crypto = require('crypto');
const timestamp = Math.floor(Date.now()/1000).toString();
const sig = crypto
  .createHmac('sha256', apiSecret)
  .update(timestamp + method + path + body)
  .digest('hex');

import hmac, hashlib

sig = hmac.new(
    api_secret.encode(),
    (timestamp + method + path + body).encode(),
    hashlib.sha256
).hexdigest()

Tipos

asset (stablecoin)

USDTUSDC

network (rede)

polygonethereumtronsolana

display_status do pedido

awaiting_paymentawaiting_depositprocessingcompletedexpiredfailed

awaiting_payment = on-ramp aguardando o Pix; awaiting_deposit = off-ramp aguardando o depósito on-chain.

POST https://cashout.lexxen.com/api/v1/quotes

Quote — trava a cotação

Crie uma cotação para travar o preço da stablecoin antes de gerar o Pix. A cotação vale por aproximadamente 5 minutos — guarde o quote_id e use-o em POST /orders.

Validade

~5 minutos

Resposta

FLAT (sem envelope)

Autenticação

HMAC-SHA256

Corpo da requisição

Envie os dados da compra em JSON. Informe amount_brl (valor em reais) ou crypto_receive (quanto de cripto deseja receber) — nunca os dois ao mesmo tempo.

Dica

Para checkout com preço fixo em reais, use amount_brl. Para entregar um valor exato em cripto, use crypto_receive.

Request body

{
  "amount_brl": 200,
  "asset": "USDT",
  "network": "polygon",
  "wallet_address": "0x8f3…a91"
}

Parâmetros

Clique em cada campo para ver detalhes e valores aceitos.

Valor em BRL a ser comprado. Informe este campo ou crypto_receive, nunca ambos. ex: 200

A stablecoin que o cliente vai receber.

USDCUSDT

A rede blockchain de destino da stablecoin.

polygonethereumtronsolana

Endereço da carteira que vai receber a stablecoin. ex: 0x8f3…a91

Valide antes com POST /wallets/validate.

Exemplos de código

A requisição precisa ser assinada com HMAC-SHA256 na ordem timestamp + METHOD + path + body. O path vai sem barra inicial e sem query string.

Segurança

Nunca exponha o api_secret no frontend. Assine sempre no servidor — a assinatura é de uso único (anti-replay ~120s) e o timestamp vale ±60s.

curl -X POST https://cashout.lexxen.com/api/v1/quotes \
  -H "X-API-Key: lxn_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…" \
  -H "Content-Type: application/json" \
  -d '{"amount_brl":200,"asset":"USDT","network":"polygon","wallet_address":"0x8f3…a91"}'

const crypto = require('crypto');
const ts = Math.floor(Date.now()/1000).toString();
const method = 'POST', path = 'api/v1/quotes';
const body = JSON.stringify({ amount_brl:200, asset:'USDT', network:'polygon', wallet_address:'0x8f3…a91' });
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts+method+path+body).digest('hex');

await fetch('https://cashout.lexxen.com/api/v1'+'/quotes', {
  method, headers: {
    'X-API-Key': apiKey, 'X-Timestamp': ts,
    'X-Signature': sig, 'Content-Type': 'application/json'
  }, body
});

$ts = (string) time();
$method = 'POST'; $path = 'api/v1/quotes';
$body = json_encode([
  'amount_brl'=>200, 'asset'=>'USDT',
  'network'=>'polygon', 'wallet_address'=>'0x8f3…a91'
]);
$sig = hash_hmac('sha256', $ts.$method.$path.$body, $apiSecret);
// envie via cURL com os headers X-API-Key / X-Timestamp / X-Signature

import time, hmac, hashlib, json, requests
ts = str(int(time.time()))
method, path = 'POST', 'api/v1/quotes'
body = json.dumps({"amount_brl":200,"asset":"USDT","network":"polygon","wallet_address":"0x8f3…a91"})
sig = hmac.new(api_secret.encode(), (ts+method+path+body).encode(), hashlib.sha256).hexdigest()
requests.post('https://cashout.lexxen.com/api/v1'+'/quotes',
  headers={'X-API-Key':api_key,'X-Timestamp':ts,'X-Signature':sig,
           'Content-Type':'application/json'}, data=body)

Resposta 200 OK

Importante

A resposta de POST /quotes é FLAT — sem o envelope data. Os demais endpoints usam { "data": … }.

200 — application/json

{
  "quote_id": "q_8a72…e1",
  "asset": "USDT",
  "network": "polygon",
  "amount_brl": "200.00",
  "amount_crypto": "38.74000000",
  "wallet_address": "0x8f3…a91",
  "price": "5.14970000",
  "fees": {
    "percent": "3.0000",
    "fixed": "1.00000000",
    "network": "2.00000000"
  },
  "expires_at": "2026-06-17T17:17:39+00:00"
}

Campos da resposta

Identificador da cotação. Use-o em POST /orders para gerar o Pix.

Valor líquido que cai na carteira do cliente — já com todas as taxas descontadas.

Cotação em BRL por unidade do asset.

Detalhamento das taxas aplicadas à operação.

percent string

Taxa percentual variável.

fixed string

Taxa fixa, em stablecoin.

network string

Taxa de rede/envio, em stablecoin.

Momento de expiração da cotação (~5 min). Depois disso, gere uma nova quote.

Erros

422

QUOTE_FAILEDFalha do provedor ao gerar a cotação, ou campos inválidos.

401

AUTHENTICATION_FAILEDAssinatura ou headers inválidos — confira a ordem do payload e o timestamp.

POST https://cashout.lexxen.com/api/v1/orders

Create Order — gera o Pix

Cria o pedido a partir de um quote_id e devolve o pix_copy_paste para gerar o QR.

Corpo da requisição

Envie o quote_id da cotação. O external_id é o seu identificador opcional para consultar depois.

Dica

Use o external_id para reconciliar com o id do seu sistema — depois consulte por ele em GET /orders/{external_id}.

Request body

{
  "quote_id": "q_8a72…e1",
  "external_id": "pedido-loja-123"
}

Parâmetros

Clique em cada campo para ver detalhes e valores aceitos.

O quote_id retornado por POST /quotes. Precisa estar válido (não expirado e não usado).

Seu identificador do pedido. Permite consultar depois por ele em GET /orders/{external_id}.

Exemplos de código

Assine com path = api/v1/orders e o body cru.

curl -X POST https://cashout.lexxen.com/api/v1/orders \
  -H "X-API-Key: lxn_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"q_8a72…e1","external_id":"pedido-loja-123"}'

const path = 'api/v1/orders';
const body = JSON.stringify({ quote_id, external_id });
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts + 'POST' + path + body).digest('hex');

await fetch('https://cashout.lexxen.com/api/v1'+'/orders', { method:'POST', headers, body });

Resposta 201

Importante

Diferente de /quotes, esta resposta usa o envelope data.

201 — application/json

{ "data": {
  "uuid": "ord_3f1…77",
  "external_id": "pedido-loja-123",
  "display_status": "awaiting_payment",
  "asset": "USDT",
  "network": "polygon",
  "amount_brl": "200.00",
  "amount_crypto": "38.74000000",
  "wallet_address": "0x8f3…a91",
  "pix_copy_paste": "00020126…",
  "provider_transaction_id": "…",
  "receipt": null,
  "error_message": null,
  "finished_at": null,
  "created_at": "2026-06-17T17:12:00+00:00"
} }

Campos da resposta

Identificador único do pedido. Use em GET /orders/{uuid}.

Status legível do pedido.

awaiting_paymentprocessingcompletedfailed

Código Pix copia-e-cola. Gere o QR a partir desta string.

Comprovante on-chain quando o pedido conclui. null enquanto pendente.

Erros

404

QUOTE_NOT_FOUNDO quote_id informado não existe.

422

QUOTE_NOT_USABLECotação expirada ou já usada · ou TENANT_CUSTOMER_NOT_CONFIGURED.

502

Bad GatewayErro do provedor upstream ao criar o pedido.

POST https://cashout.lexxen.com/api/v1/orders/{id}/pay-from-balance

Pay from Balance — paga com saldo

Liquida o Pix de um pedido on-ramp debitando o seu saldo na Lexxen, em vez de pagar o copia-e-cola externamente. Sem corpo: o valor e o EMV saem do próprio pedido.

Pré-condições

Atenção

O pagamento por saldo precisa estar habilitado para a sua conta. Solicite à equipe Lexxen a configuração da sua conta bancária. Enquanto não estiver habilitado, a rota responde 422 BANKING_CORE_NOT_CONFIGURED.

O pedido é on-ramp e está em awaiting_payment.

O pedido tem EMV — em pix_copy_paste ou, quando null, no deposit_address de Pix das deposit_instructions.

Ainda não foi pago por saldo — idempotente: um pagamento por pedido.

O pagamento por saldo está habilitado para a sua conta (solicite à equipe Lexxen).

Parâmetros

O uuid do pedido on-ramp a pagar.

Exemplos de código

POST sem corpo. Assine com path = api/v1/orders/{uuid}/pay-from-balance e body vazio.

curl -X POST https://cashout.lexxen.com/api/v1/orders/ord_3f1…77/pay-from-balance \
  -H "X-API-Key: lxn_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…"

const path = 'api/v1/orders/ord_3f1…77/pay-from-balance';
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts + 'POST' + path + '').digest('hex');

await fetch('https://cashout.lexxen.com/api/v1'+'/orders/ord_3f1…77/pay-from-balance', { method:'POST', headers });

Resposta 200

Importante

Mesmo recurso do POST /orders (envelope data). O pedido segue em awaiting_payment até a confirmação do Pix pela Lexxen (webhook) → processing → completed — igual ao pagamento externo.

200 — application/json

{ "data": {
  "uuid": "ord_3f1…77",
  "display_status": "awaiting_payment",
  "asset": "USDT",
  "network": "polygon",
  "amount_brl": "500.00",
  "amount_crypto": "92.50000000",
  "wallet_address": "0xabc…123",
  "created_at": "2026-06-17T14:50:00+00:00"
} }

Erros

404

ORDER_NOT_FOUNDNão existe pedido com esse uuid.

422

ORDER_NOT_PAYABLE · ORDER_NOT_AWAITING_PAYMENT · ORDER_EMV_UNAVAILABLE · BANKING_CORE_NOT_CONFIGUREDPedido não é on-ramp · não está aguardando pagamento · sem EMV de Pix · pagamento por saldo não habilitado para a conta.

409

ORDER_ALREADY_PAIDPagamento por saldo já iniciado para este pedido.

422

BANKING_CORE_REJECTEDBanking core recusou (ex.: saldo insuficiente). A mensagem é repassada.

502

BANKING_CORE_UNAVAILABLEBanking core indisponível.

GET https://cashout.lexxen.com/api/v1/orders/{idOrExternalId}

Get Status — status do pedido

Retorna o pedido (envelope data) com o display_status atualizado. Aceita o uuid OU o seu external_id.

Parâmetros

O uuid do pedido ou o external_id enviado na criação.

Exemplos de código

Em GET o body é string vazia na assinatura.

curl https://cashout.lexxen.com/api/v1/orders/ord_3f1…77 \
  -H "X-API-Key: lxn_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…"

const path = 'api/v1/orders/ord_3f1…77';
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts + 'GET' + path + '').digest('hex');

Resposta 200

Mesmo objeto de POST /orders (envelope data), com o status atualizado.

200 — application/json

{ "data": {
  "uuid": "ord_3f1…77",
  "display_status": "completed",
  "amount_crypto": "38.74000000",
  "receipt": "0xabc…",
  "finished_at": "2026-06-17T17:18:02+00:00"
} }

Erros

404

ORDER_NOT_FOUNDNão existe pedido com esse uuid/external_id.

GET https://cashout.lexxen.com/api/v1/orders

List Orders — lista com filtros

Lista paginada de pedidos, com filtro por status e intervalo de datas.

Query parameters

statusFiltra por display_status.

fromData inicial (YYYY-MM-DD).

toData final (YYYY-MM-DD).

limitItens por página (máx 100).

pageNúmero da página.

Resposta 200

Atenção

A query string NÃO entra no path assinado (path = api/v1/orders).

200 — application/json

{
  "data": [ /* …orders… */ ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 42,
    "last_page": 3
  }
}

POST https://cashout.lexxen.com/api/v1/wallets/validate

Validate Wallet — valida endereço

Verifica se um endereço é válido para a rede e se está em blocklist. Útil antes de criar a cotação.

Corpo da requisição

Envie o address e a network de destino.

Request body

{
  "address": "0x8f3…a91",
  "network": "polygon"
}

Resposta 200

Envelope data com o resultado da validação.

200 — application/json

{ "data": {
  "address": "0x8f3…a91",
  "blockchain": "polygon",
  "is_blocklisted": false
} }

Campos da resposta

true indica endereço em lista de bloqueio — não prossiga com a operação.

Erros

422

WALLET_VALIDATION_FAILEDFalha do provedor ao validar o endereço, ou campos inválidos (address/network).

POST https://cashout.lexxen.com/api/v1/sell/quotes

Off-ramp · venda

Sell Quote — trava a cotação de venda

O cliente deposita stablecoin on-chain e recebe BRL via Pix. Informe amount_crypto (quanto vender) ou amount_brl (quanto receber).

Corpo da requisição

O holder indica de quem é a carteira de origem: self (padrão) ou other.

Dica

A resposta traz o amount_brl líquido (já com taxas) — mostre-o como o valor que o cliente vai receber.

Request body

{
  "amount_crypto": 100,
  "asset": "USDT",
  "network": "polygon",
  "holder": "self"  // opcional: self (padrão) ou other
}

Parâmetros

Quantidade de cripto a vender. Informe este campo ou amount_brl.

A stablecoin que o cliente vai receber.

USDCUSDT

De quem é a carteira de origem: self (padrão) ou other.

Resposta 200 OK

Importante

Assim como /quotes, a resposta de venda é FLAT (sem envelope data).

200 — application/json

{
  "quote_id": "q_3b91…d0",
  "direction": "off_ramp",
  "asset": "USDT",
  "network": "polygon",
  "amount_crypto": "100.00000000",
  "amount_brl": "535.00",
  "quotation": "5.40000000",
  "holder": "self",
  "fees": {
    "percent": "1.5000",
    "fixed": "0.50000000",
    "shipping_brl": "3.50"
  },
  "expires_at": "2026-06-17T15:00:00+00:00"
}

Campos da resposta

BRL líquido a receber — já com todas as taxas descontadas.

Cotação em BRL por unidade do asset.

Taxa de saque Pix, em BRL.

Erros

422

QUOTE_FAILEDFalha do provedor ao gerar a cotação, ou campos inválidos.

POST https://cashout.lexxen.com/api/v1/sell/orders

Create Sell Order — gera o payout

Cria a venda a partir de um quote_id, com o sender.address (origem on-chain) e a receiver.pix_key. Devolve o deposit_address.

Corpo da requisição

O sender.address é a origem on-chain da cripto; o receiver.pix_key é a chave Pix que vai receber os reais.

Dica

Após criar, oriente o cliente a enviar a cripto para o deposit_address e depois chame /sell/orders/{id}/confirm.

Request body

{
  "quote_id": "q_3b91…d0",
  "external_id": "venda-loja-123",
  "sender": {
    "address": "0x… (origem on-chain)"
  },
  "receiver": {
    "pix_key": "[email protected]",
    "document": "12345678900"  // opcional
  }
}

Parâmetros

O quote_id de uma cotação de venda (direção off_ramp) válida.

Endereço on-chain de onde a cripto será enviada.

Chave Pix que vai receber os reais (e-mail, CPF/CNPJ, telefone ou chave aleatória).

Seu identificador da venda e, opcionalmente, o documento do recebedor para conformidade.

Resposta 201

Importante

O pedido nasce em awaiting_deposit. Envie a cripto para o deposit_address.

201 — application/json

{ "data": {
  "uuid": "sell_9c2…aa",
  "external_id": "venda-loja-123",
  "direction": "off_ramp",
  "display_status": "awaiting_deposit",
  "asset": "USDT",
  "network": "polygon",
  "amount_crypto": "100.00000000",
  "amount_brl": "535.00",
  "sender_address": "0x…",
  "pix_key": "[email protected]",
  "deposit_address": "0x… (envie a cripto para cá)",
  "transaction_hash": null,
  "finished_at": null,
  "created_at": "2026-06-17T17:12:00+00:00"
} }

Erros

404

QUOTE_NOT_FOUNDO quote_id informado não existe.

422

QUOTE_NOT_USABLECotação expirada, já usada ou de outra direção · ou TENANT_CUSTOMER_NOT_CONFIGURED.

502

Bad GatewayErro do provedor upstream ao criar a venda.

POST https://cashout.lexxen.com/api/v1/sell/orders/{id}/confirm

Confirm — confirma o depósito on-chain

Depois de depositar a cripto no deposit_address, confirme informando o transaction_hash. Só funciona enquanto a venda está em awaiting_deposit.

Corpo da requisição

O amount é opcional — informe a quantidade efetivamente depositada se diferir da cotação.

Request body

{
  "transaction_hash": "0x… (hash do depósito)",
  "amount": 100  // opcional
}

Resposta 200

Recurso da venda atualizado, com display_status → processing.

Erros

404

ORDER_NOT_FOUNDNão existe venda com esse uuid/external_id.

422

PAYOUT_NOT_CONFIRMABLEA venda não está aguardando depósito.

GET https://cashout.lexxen.com/api/v1/sell/orders/{idOrExternalId}

Get Sell Status — status da venda

Retorna a venda (envelope data) com o status atualizado. Aceita o uuid OU o seu external_id — apenas vendas (off_ramp).

Parâmetros

O uuid da venda ou o external_id enviado na criação.

Resposta 200

Mesmo objeto de POST /sell/orders (envelope data), com o display_status atualizado.

404

ORDER_NOT_FOUNDNão existe venda com esse uuid/external_id.

GET https://cashout.lexxen.com/api/v1/sell/orders

List Sell Orders — lista de vendas

Lista paginada de vendas (off_ramp), com os mesmos filtros do on-ramp.

Query parameters

statusFiltra por display_status.

from · toIntervalo de datas (YYYY-MM-DD).

limit · pagePaginação (limit máx 100).

Resposta 200

Atenção

A query string NÃO entra no path assinado (path = api/v1/sell/orders). Resposta paginada com data + meta.

GET https://cashout.lexxen.com/api/v1/wallets

Carteiras

List Wallets — carteiras + saldos

Lista as carteiras gerenciadas do cliente, com o saldo de cada uma. Use o wallet_id retornado como sender no POST /wallet-transfers.

Query parameters

networkFiltro opcional: polygon / ethereum / tron / solana.

limitItens por página (máx 100, padrão 25).

afterCursor — use o meta.cursor da página anterior.

Resposta 200

Lista cursor-paginada: o meta.cursor aponta para a próxima página.

200 — application/json

{
  "data": [{
    "wallet_id": "wlt_2a…f1",
    "name": "Minha carteira",
    "network": "polygon",
    "address": "0x8f3…a91",
    "is_external": false,
    "balances": [
      { "currency": "USDT", "balance": "150.00" }
    ]
  }],
  "meta": { "cursor": "…" }
}

Erros

422

INVALID_NETWORKRede inválida · ou TENANT_CUSTOMER_NOT_CONFIGURED.

502

WALLETS_LIST_FAILEDErro do provedor upstream ao listar carteiras.

POST https://cashout.lexxen.com/api/v1/wallet-transfers

Create Transfer — wallet → wallet

Transfere stablecoin entre carteiras gerenciadas (ou para um endereço externo) na mesma rede — sem cotação. O destino pode ser outro wallet_id OU um address.

Corpo da requisição

O sender é o wallet_id da carteira de origem. O receiver é outra carteira (wallet_id) OU um endereço on-chain (address), sempre na mesma rede.

Importante

A transferência já sai em processing (fundos em custódia) e segue para completed ou failed.

Request body

{
  "amount": 50,
  "asset": "USDT",
  "network": "polygon",
  "sender": "wlt_2a…f1",
  "receiver": {
    "wallet_id": "wlt_7c…b3"  // OU "address": "0x…"
  },
  "external_id": "transf-123"  // opcional (máx 36)
}

Parâmetros

Valor, stablecoin e rede da transferência. Origem e destino precisam estar na mesma network.

O wallet_id da carteira de origem (de GET /wallets).

Destino: wallet_id (carteira gerenciada) ou address (endereço on-chain).

Seu identificador da transferência (máx 36 caracteres).

Resposta 201

Envelope data com a transferência criada (direction: wallet_transfer).

201 — application/json

{ "data": {
  "uuid": "wtr_5d…c2",
  "external_id": "transf-123",
  "direction": "wallet_transfer",
  "display_status": "processing",
  "asset": "USDT",
  "network": "polygon",
  "amount": "50.00000000",
  "sender_wallet_id": "wlt_2a…f1",
  "receiver_wallet_id": "wlt_7c…b3",
  "receiver_address": "0x…",
  "transaction_hash": null,
  "finished_at": null,
  "created_at": "2026-06-17T17:12:00+00:00"
} }

Erros

422

INSUFFICIENT_BALANCEO saldo da origem não cobre valor + taxa.

422

SELF_TRANSFER_NOT_ALLOWEDOrigem e destino são iguais · ou TENANT_CUSTOMER_NOT_CONFIGURED.

502

Bad GatewayErro do provedor upstream ao transferir.

GET https://cashout.lexxen.com/api/v1/wallet-transfers/{idOrExternalId}

Get Transfer — status da transferência

Retorna a transferência (envelope data) com o display_status atualizado. Aceita o uuid OU o seu external_id.

Resposta 200

Mesmo objeto de POST /wallet-transfers (envelope data), com o status atualizado.

404

TRANSFER_NOT_FOUNDNão existe transferência com esse uuid/external_id.

GET https://cashout.lexxen.com/api/v1/wallet-transfers

List Transfers — lista de transferências

Lista paginada de transferências, com filtro por status e intervalo de datas.

Query parameters

statusFiltra por display_status.

from · toIntervalo de datas (YYYY-MM-DD).

limit · pagePaginação (limit máx 100).

Resposta 200

Atenção

A query string NÃO entra no path assinado (path = api/v1/wallet-transfers). Resposta paginada com data + meta.

GET https://cashout.lexxen.com/api/v1/balance

Balance — saldo unificado

Saldo consolidado do tenant em Pix (BRL) e cripto numa única chamada. Cada bloco é resolvido de forma independente: se um provedor falhar, aquele bloco vem null e o outro continua válido. Somente leitura — não movimenta dinheiro.

Exemplos de código

GET sem corpo. Assine com path = api/v1/balance e body vazio.

curl https://cashout.lexxen.com/api/v1/balance \
  -H "X-API-Key: lxn_live_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…"

const path = 'api/v1/balance';
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts + 'GET' + path + '').digest('hex');

Resposta 200

available = saldo livre menos as taxas pendentes (max(0, …)).

No bloco crypto, apenas ativos com free > 0 são listados (8 casas decimais).

pix e/ou crypto podem vir null se o provedor correspondente estiver indisponível.

200 — application/json

{ "data": {
  "pix": { "balance": 1000.00, "pending_fees": 12.50, "available": 987.50 },
  "crypto": {
    "balances": [
      { "asset": "USDT", "free": "150.00000000", "pending_fees": "2.00000000", "available": "148.00000000" }
    ]
  }
} }

GET https://cashout.lexxen.com/api/v1/balance/banking

Banking Balance — saldo no banking core

Consulta direto o saldo da conta do tenant no banking core (Lexxen), sem passar pelos provedores de Pix/cripto do GET /balance. É a mesma conta usada no POST /orders/{id}/pay-from-balance — útil para saber quanto há disponível antes de pagar um pedido por saldo. Somente leitura.

Pré-condições

Atenção

Requer o Account ID do banking core configurado para a empresa (painel admin → editar empresa). Enquanto não estiver configurado, a rota responde 422 BANKING_CORE_NOT_CONFIGURED.

Exemplos de código

GET sem corpo. Assine com path = api/v1/balance/banking e body vazio.

curl https://cashout.lexxen.com/api/v1/balance/banking \
  -H "X-API-Key: lxn_live_…" \
  -H "X-Timestamp: 1718643000" \
  -H "X-Signature: 9f86d0818…"

const path = 'api/v1/balance/banking';
const sig = crypto.createHmac('sha256', apiSecret)
  .update(ts + 'GET' + path + '').digest('hex');

Resposta 200

Importante

O JSON do banking core é repassado em data sem transformação. Os saldos vêm por moeda em balances, com valores em centavos: available é o disponível e blocked é o bloqueado.

200 — application/json

{ "data": {
  "balances": {
    "BRL": { "available": 150000, "blocked": 2500 }
  }
} }

Erros

422

BANKING_CORE_NOT_CONFIGUREDEmpresa sem Account ID do banking core.

422

BANKING_CORE_REJECTEDBanking core recusou (mensagem repassada).

502

BANKING_CORE_UNAVAILABLEBanking core indisponível.

Eventos

Webhooks

Quando um pedido conclui (on-ramp ou off-ramp), a Lexxen dispara um webhook para a URL configurada pelo tenant. O payload inclui direction e, na venda, o transaction_hash.

Eventos

transaction.completedQuando a operação completa.

transaction.failedEm caso de falha.

Payload

Segurança

O webhook é assinado (HMAC) com o secret do tenant no header configurado. Valide antes de processar.

POST → sua URL

{
  "event": "transaction.completed",
  "order_uuid": "ord_3f1…77",
  "external_id": "pedido-loja-123",
  "direction": "on_ramp",
  "status": "completed",
  "asset": "USDT",
  "network": "polygon",
  "amount_brl": "200.00",
  "amount_crypto": "38.74000000",
  "wallet_address": "0x8f3…a91",
  "transaction_hash": null,  // preenchido na venda (off-ramp)
  "provider": "UNBLOCKPAY"
}

Referência

Códigos de erro

Todas as respostas são JSON. Os corpos de erro trazem um código para você tratar no seu código.

401Authentication failed — assinatura ou headers inválidos.

404ORDER_NOT_FOUND · QUOTE_NOT_FOUND · TRANSFER_NOT_FOUND

422QUOTE_FAILED · QUOTE_NOT_USABLE · WALLET_VALIDATION_FAILED · INSUFFICIENT_BALANCE · PAYOUT_NOT_CONFIRMABLE · validação

502Erro do provedor upstream.

Todas as respostas seguem JSON, com timestamps em ISO 8601. IDs são UUIDs (também aceitamos external_id). A resposta de POST /quotes e POST /sell/quotes é FLAT; as demais usam envelope data.