Brix API: Developer Portal

Welcome to the official Brix API portal! Here you'll find the detailed documentation to integrate your partner bot or external application with our services. Our HTTP API lets you perform currency conversion, query user data and expand integrations with the Brix ecosystem, kyu~!

Authentication & How to Get a Token

Authentication across the entire Brix API is standardized through the Authorization HTTP header with the unique validation token provided exclusively for your bot or application.

Header	Value
Authorization	brix_SEU_TOKEN_AQUI

---

Currency Conversion API ( /api/pix )

This API allows bidirectional currency conversion between your partner bot and the Brix ecosystem. Your users can convert their currency into Braixencoin, and Brix can also trigger requests to your bot to convert Braixencoin back into your currency.

Endpoint (/api/pix)

Brix receives conversion requests via HTTP POST at the central endpoint:

Testing Mechanism (Sandbox)

Brix has a built-in testing system to make implementing currency conversion easier:

Request Body (JSON)

The system uses universal English terms, maintaining compatibility with various systems by presenting a single field identification standard.

Field	Type	Required	Description
user_id	String / Int	Yes	Discord user ID that will receive the conversion.
amount	Integer	Yes	Amount of currency to convert.
ref_id	String (24)	Yes	Unique reference ID for the transaction. Used to prevent duplicate processing if the request is resent. Suggested pattern: 24 characters.
currency	String	No	Source currency name. If omitted, the registered default is used.
currency_icon	URL	No	Image URL (PNG/JPG) used as the currency icon in the DM.

cURL Example (Production)

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"
         }'

Conversion Fees and Limits

Brix's conversion system was built to be simple, transparent and fair:

API Responses & Errors

Success (200 OK)

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

• modo_teste: true indicates the request was processed as a test (invalid/missing token).

Common Errors

Code	Description
400 Bad Request	Invalid or malformed JSON.
400 Bad Request	Missing required fields (user_id, amount, ref_id).
400 Bad Request	user_id must be numeric and greater than 0.
400 Bad Request	amount must be an integer, greater than 0 and less than 10,000,000.
400 Bad Request	Invalid or too long currency (max. 50 characters).
400 Bad Request	currency_icon must be a valid URL (http/https) and up to 300 characters.
400 Bad Request	ref_id must be a valid string (24 alphanumeric characters, _ or -).
400 Bad Request	Too many metadata fields (max. 20 fields).
400 Bad Request	Metadata too large (key up to 50 chars, value up to 500 chars).
429 Too Many Requests	Too many requests from the same IP (global rate limit).
429 Too Many Requests	Too many requests for the same user (rate limit per user_id).
200 OK	Duplicate transaction detected (same ref_id), successfully ignored.
500 Internal Error	Unexpected error in the server's internal processing.

Return Webhook (Brix → Partner)

Brix can also trigger requests to your bot when a user uses the /bc transferir command. In this flow, Braixencoins are converted back into your system's currency.

To receive transfers from Brix, you must provide a webhook URL during partnership registration. Brix will send a POST to that address using the same validation token in the Authorization header.

Payload Sent by Brix to your Webhook

Field	Type	Description
user_id	String	Discord user ID that made the transfer.
amount	Integer	Amount of Braixencoins sent.
bot_name	String	Always "Brix" — identifies the origin of the transfer.
ref_id	String (24)	Unique transaction ID generated by Brix. Use it to prevent duplicate processing.
currency_icon	URL	URL of the BraixenCoin image to be displayed in your bot's DMs.

JSON Receipt Example

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

---

User Lookup API ( /api/user )

Provides lookup of public account information and balances of Brix users (such as Braixencoins, twigs, reputation score, level/XP and premium subscription status) for integration with external applications.

Endpoint (/api/user)

Sandbox Mode in /api/user

Request Parameters

Parameter	Type	Location	Description
user_id	Integer / String	Query String (GET) or JSON Body (POST)	Numeric Discord ID of the user to look up. Required in production.

JSON Response (/api/user)

Example of the JSON response returned in real time directly by the /api/user route of the system:

{
  "status": "Carregando dados da API..."
}

Field	Type	Description
id	Integer	Numeric Discord user ID.
braixencoin	Integer	User's current Braixencoin balance.
graveto	Integer	User's current twig balance.
xpg	Integer	Experience score / level.
rep	Integer	Accumulated reputation score.
descricao	String	"About me" text set in the user's profile.
premium.ativo	Boolean	Indicates whether the user has an active Premium subscription.
premium.expiracao	String / null	Subscription expiration date (DD/MM/YYYY) if applicable.