Convert API

A Convert API permite trocar entre as moedas mantidas no saldo do seu comércio ao preço de mercado atual — o mesmo motor que alimenta a aba Swap do painel do comércio, agora disponível a partir do seu backend.

Obter cotação de conversão

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Executar conversão

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Erros

Em caso de falha, a resposta tem state: 1 e um error_code — compartilhado por /v1/convert/price e /v1/convert:

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

Conversão automática de pagamentos recebidos

A conversão automática é uma configuração de projeto para faturas recebidas e créditos de carteira estática. Ela é configurada no painel do comerciante, não adicionando campos a /v1/payment. Cada regra seleciona uma ou mais moedas de origem e uma moeda de destino.

Quando a conversão é concluída, as informações do pagamento e os webhooks do comerciante podem incluir:

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

Os domínios de valores são intencionalmente separados:

• payment_amount — o que foi detectado na cadeia na moeda de pagamento de origem;
• merchant_amount — o valor líquido de origem atribuível ao comerciante antes da conversão;
• convert.amount — o valor creditado em convert.to_currency;
• convert.rate e convert.commission — o resultado da conversão realizada, não um preço que você deve recalcular localmente.

Falha na conversão automática e fallback

A conversão ocorre após o recebimento do pagamento na blockchain. Disponibilidade de mercado, tamanhos mínimos de pedido, limites de precisão, tempos limites de câmbio e liquidez executável insuficiente podem atrasar ou impedir a conversão.

• Depósitos abaixo do mínimo global/projeto contornam o pipeline de conversão e creditam a moeda de origem.
• Falhas transitórias podem ser re-tentadas de forma assíncrona.
• Depósitos grandes ou não negociáveis podem retornar a um crédito na moeda de origem depois que a política de re-tentativa for esgotada.
• Um pagamento, portanto, pode ser válido mesmo quando a conversão para a moeda desejada não ocorreu.

Sua integração deve persistir o pagamento verificado primeiro, e então reconciliar a moeda efetivamente creditada a partir das informações de pagamento, o bloco opcional convert e os saldos do comerciante. Não bloqueie o reconhecimento do webhook de pagamento enquanto espera pelos seus próprios sistemas de análise ou notificação.

Testes de aceitação de conversão automática

Teste pelo menos: conversão direta bem-sucedida, conversão por ponte/multi-salto, poeira abaixo do mínimo, tentativa transitória, retorno para a moeda de origem, pagamento insuficiente, pagamento excessivo, webhook duplicado, convert ausente, e reconciliação após um timeout ambíguo.

Casos extremos de conversão manual

• /v1/convert/price é uma pré-visualização indicativa; o movimento do mercado pode alterar o resultado da execução.
• amount_type: from corrige a solicitação do lado da origem, enquanto amount_type: to solicita um valor do lado do destino. Não troque o significado ao apresentar a interface de confirmação.
• Um par sem mercado direto pode ser roteado através de uma moeda intermediária. Se apenas uma das etapas for concluída, partially_completed relata o crédito intermediário.
• Se uma chamada de execução expirar, reconcilie antes de tentar novamente. Uma ordem de mercado pode ser executada mesmo quando sua resposta HTTP é perdida.
• Trate failed como um estado a ser reconciliado, não como permissão para aplicar uma entrada de saldo compensatório local; a plataforma é responsável pela contabilidade de débito/reembolso.