Pix do Brix: Api de Conversão de Moedas

Integre seu bot parceiro ao ecossistema do Brix e permita a conversão bidirecional de moedas. Seus usuários podem converter sua moeda em Braixencoin, e o Brix também pode disparar solicitações para o seu bot converter Braixencoin de volta para a sua moeda.

Como Obter um Token

Para se integrar ao sistema do Brix, você precisará de um token de validação único gerado exclusivamente para o seu bot. Esse token é utilizado nos dois sentidos da comunicação.

---

Parceiro → Brix

Seu bot envia uma solicitação ao Brix para que o usuário receba Braixencoin em troca da moeda do seu sistema.

Endpoint

O Brix recebe as solicitações via HTTP POST no endpoint central:

Autenticação

A autenticação é feita pelo cabeçalho Authorization com o token fornecido pelo desenvolvedor.

Header	Valor
Authorization	brix_SEU_TOKEN_AQUI

Mecanismo de Testes (Sandbox)

O Brix possui um sistema de testes integrado para facilitar a implementação:

Corpo da Requisição (JSON)

O sistema usa termos em inglês universal, mantendo compatibilidade com diversos sistemas por apresentar um padrão único de identificação de campos.

Campo	Tipo	Requerido	Descrição
user_id	String / Int	Sim	ID do usuário no Discord que receberá a conversão.
amount	Inteiro	Sim	Quantidade de moedas a converter.
ref_id	String (24)	Sim	ID único de referência para a transação. Usado para evitar processamento duplicado caso a requisição seja reenviada. Padrão sugerido: 24 caracteres.
currency	String	Não	Nome da moeda de origem. Se omitido, usa o padrão cadastrado.
currency_icon	URL	Não	URL de imagem (PNG/JPG) usada como ícone da moeda na DM.

Exemplo cURL (Produção)

curl -X POST https://brixbot.xyz/api/pix \
     -H "Authorization: brix_seu_token_real" \
     -H "Content-Type: application/json" \
     -d '{
           "user_id": "123456789012345678",
           "amount": 654,
           "currency": "MinhaMoeda",
           "currency_icon": "https://meusite.com/moeda.png",
           "ref_id": "xN7pL9qY2mR5kH4vC8wB3jF1"
         }'

Taxas e limites de conversão

O sistema de conversão do Brix foi feito para ser simples, transparente e justo

Respostas da API

Sucesso (200 OK)

'{
    "~kyuuu": true,
    "modo_teste": false
}'

• modo_teste: true indica que a requisição foi processada como teste (token inválido/ausente).

Erros Comuns

Código	Descrição
400 Bad Request	JSON inválido ou mal formatado.
400 Bad Request	Campos obrigatórios ausentes (user_id, amount, ref_id).
400 Bad Request	user_id deve ser numérico e maior que 0.
400 Bad Request	amount deve ser inteiro, maior que 0 e menor que 10.000.000.
400 Bad Request	currency inválida ou muito longa (máx. 50 caracteres).
400 Bad Request	currency_icon deve ser uma URL válida (http/https) e até 300 caracteres.
400 Bad Request	ref_id deve ser uma string válida (24 caracteres alfanuméricos, _ ou -).
400 Bad Request	Metadados excessivos (máx. 20 campos).
400 Bad Request	Metadados muito grandes (chave até 50 chars, valor até 500 chars).
429 Too Many Requests	Muitas requisições pelo mesmo IP (rate limit global).
429 Too Many Requests	Muitas requisições para o mesmo usuário (rate limit por user_id).
200 OK	Transação duplicada detectada (mesmo ref_id), ignorada com sucesso.
500 Internal Error	Erro inesperado no processamento interno do servidor.

---

Brix → Parceiro

O Brix também pode disparar solicitações para o seu bot quando um usuário utiliza o comando /bc transferir. Nesse fluxo, Braixencoin são convertidos de volta para a moeda do seu sistema.

Webhook de Retorno

Para receber transferências do Brix, você deve fornecer um webhook URL durante o cadastro da parceria. O Brix enviará um POST para esse endereço com o mesmo token de validação.

O header de autenticação enviado pelo Brix usa o mesmo token gerado pelo brix no momento do cadastro de seu bot.

Header	Valor
Authorization	brix_SEU_TOKEN_AQUI

Payload Enviado pelo Brix

Campo	Tipo	Descrição
user_id	String	ID do usuário no Discord que realizou a transferência.
amount	Inteiro	Quantidade de Braixencoins enviados.
bot_name	String	Sempre "Brix" — identifica a origem da transferência.
ref_id	String (24)	ID único da transação gerado pelo Brix (string de 24 caracteres). Utilize-o para evitar processamento duplicado em caso de retentativas.
currency_icon	URL	URL com a imagem (ícone) da BraixenCoin para ser exibida nas DMs/mensagens do seu bot.

Exemplo de Recebimento

Veja como o payload chegará no seu webhook:

'{
    "user_id": "123456789012345678",
    "amount": 654,
    "bot_name": "Brix",
    "ref_id": "sT6vM2bN8pK1xH4jL9cQ5wR3",
    "currency_icon": "https://brixbot.xyz/cdn/icon_braixencoin.png"
}'