Off-Ramp Cripto Instantâneo - Bullring Finance API Doc

Cenário

Um usuário deseja vender Bitcoin (via Lightning Network) e receber dinheiro em sua conta bancária local (por exemplo, PIX no Brasil) imediatamente usando um fluxo único e simplificado.

Fluxo de Trabalho

1. Adicionar Conta Bancária de Beneficiário

Primeiro, adicione a conta bancária de destino como um beneficiário. É para lá que os fundos serão enviados após o recebimento da criptomoeda.

Consulte a referência da API Adicionar Beneficiário para obter detalhes completos.

curl --request POST \
  --url https://api.bullring.finance/v1/ramp/{subaccountId}/banking/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "account_id": "667.136.083-96",
  "account_type": "cpf",
  "currency": "BRL"
}'

Resposta:

{
  "id": "343bb162-d0ae-46ef-a5bb-13505eb52c89",
  "account_id": "667.136.083-96",
  "account_type": "cpf",
  "currency": "BRL",
  "status": "active",
  "created_at": "2025-11-25T12:00:00.000Z"
}

2. Iniciar Off-Ramp Cripto

Inicie o off-ramp especificando o destinatário (ID do beneficiário) e o valor na moeda de destino. A API gerará uma fatura Lightning que o usuário precisa pagar.

Consulte a referência da API Off-Ramp Cripto para obter detalhes completos.

curl --request POST \
  --url https://api.bullring.finance/v1/ramp/{subaccountId}/banking/offramp/initiate \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "recipient_id": "343bb162-d0ae-46ef-a5bb-13505eb52c89",
  "amount": 88
}'

Resposta:

{
  "success": true,
  "data": {
    "id": "d79c9799-bb8e-4c17-9d5a-79fefa34484f",
    "lightningInvoice": "lntbs190270n1p5jtvf2pp53pk7mdfvc9d8szp7m0kpym4q5j8axwy6zk7j8ylk03j6vn24cv6sdqqcqzpuxqzfvsp5phce46p7sk0dyejc2wnn0c0vcehdwa8p4fugj734rvy6eed7g2ds9qxpqysgqlas9q8el7l57vn7ht84tqha22c53s5797uqtv70lsn55xa9rhe53l0z2ashzeq9jcz54wkczzyqznqeunthfw4cnyjp3v2y7vha6yxspe0u76h",
    "lightningInvoiceId": "d0abc66e-9ab3-43b7-bb07-09465a048d54",
    "targetAmount": 88,
    "targetCurrency": "brl",
    "lightningAmount": 1656,
    "lightningCurrency": "stablesats",
    "exchangeRate": 0.18822915501882292,
    "lightningFee": 0,
    "withdrawalFee": 0.64,
    "targetAmountReceivable": 87.34,
    "totalFees": 0.64,
    "bankAccount": {
      "id": "343bb162-d0ae-46ef-a5bb-13505eb52c89",
      "bankName": null,
      "accountId": "667.136.083-96",
      "currency": "BRL"
    },
    "expiresAt": null,
    "status": "pending",
    "createdAt": "2025-11-25T13:37:46.829Z"
  },
  "message": "Lightning invoice generated. Pay to receive funds in your bank account."
}

Campos Principais da Resposta:

lightningInvoice - A fatura Lightning que o usuário precisa pagar
lightningAmount - A quantidade de satoshis a pagar
targetAmountReceivable - O valor que o usuário receberá (após taxas)
totalFees - Total de taxas cobradas pela transação

3. Usuário Paga Fatura Lightning

O usuário paga a fatura Lightning usando sua carteira Bitcoin Lightning. Assim que a fatura é paga, a Bullring processa automaticamente o saque para a conta bancária do beneficiário.

4. Verificar Status do Off-Ramp

Você pode verificar o status da transação de off-ramp a qualquer momento usando o ID do off-ramp.

Consulte a referência da API Obter Status do Off-Ramp para obter detalhes completos.

curl --request GET \
  --url https://api.bullring.finance/v1/ramp/{subaccountId}/banking/offramp/{offrampId}/status \
  --header 'Authorization: Bearer <token>'

Resposta:

{
  "success": true,
  "data": {
    "id": "6b32169e-c20e-49c9-aa7f-b73fe863c231",
    "status": "pending",
    "targetAmount": 12,
    "targetCurrency": "brl",
    "lightningAmount": 226,
    "withdrawalId": null,
    "invoicePaidAt": null,
    "withdrawalInitiatedAt": null,
    "completedAt": null,
    "errorMessage": null,
    "createdAt": "2025-11-25T13:48:02.667Z",
    "updatedAt": "2025-11-25T13:48:02.667Z",
    "lightningCurrency": "stablesats",
    "exchangeRate": 0.18822916,
    "lightningFee": 0,
    "withdrawalFee": 0.11,
    "targetAmountReceivable": 53.09,
    "totalFees": 0.11
  }
}

Valores de Status:

pending - Aguardando pagamento da fatura Lightning
processing - Fatura paga, saque sendo processado
completed - Fundos enviados com sucesso para o beneficiário
failed - Transação falhou (veja errorMessage para detalhes)

Vantagens

Este fluxo de off-ramp simplificado oferece vários benefícios:

Chamada de API Única: Gere a fatura Lightning e inicie o saque em uma única solicitação
Processamento Automático: Assim que a fatura Lightning é paga, o saque é processado automaticamente
Taxas de Câmbio em Tempo Real: Obtenha a taxa de câmbio atual e as taxas antecipadamente
Integração Simples: Não é necessário gerenciar fluxos separados de depósito e saque

​Cenário

​Fluxo de Trabalho

​1. Adicionar Conta Bancária de Beneficiário

​2. Iniciar Off-Ramp Cripto

​3. Usuário Paga Fatura Lightning

​4. Verificar Status do Off-Ramp

​Vantagens

Cenário

Fluxo de Trabalho

1. Adicionar Conta Bancária de Beneficiário

2. Iniciar Off-Ramp Cripto

3. Usuário Paga Fatura Lightning

4. Verificar Status do Off-Ramp

Vantagens