# BRC Core API — LLM Integration Guide

> BRC is a 1:1 BRL-pegged token on the Liquid Network (Bitcoin sidechain).
> This file contains everything you need to integrate with the BRC API.

## Base URL

https://api.brctoken.xyz

## Authentication

All partner endpoints require the header:
X-API-Key: brc_live_...

Public endpoints (/v1/health, /v1/asset-info) require no authentication.

## Endpoints

### POST /v1/deposit
Request a BRL deposit (pending until PSP webhook or admin confirmation).

Request:
```json
{
  "amount": 1000,
  "railway": "pix"
}
```

Response (200):
```json
{
  "transaction_id": "uuid",
  "status": "pending",
  "amount": 1000,
  "railway": "pix",
  "message": "Aguardando confirmação"
}
```

Errors: 400 INVALID_AMOUNT, INVALID_RAILWAY | 401 Unauthorized | 403 Forbidden

---

### GET /v1/quote?brl_amount=1000
Get a conversion quote BRL → BRC. Quote is valid for 2 minutes.

Response (200):
```json
{
  "quote_id": "uuid",
  "brl_amount": 1000,
  "brc_amount": 950,
  "fee": 50,
  "convert_fee_pct": 0.05,
  "convert_fee_fixed": 2.5,
  "valid_for_seconds": 120,
  "expires_at": "2026-01-01T00:02:00Z"
}
```

Errors: 400 Bad Request | 401 Unauthorized | 403 Forbidden

---

### POST /v1/convert
Convert BRL to BRC (mint). Requires a valid quote_id and a Liquid Network address.

Request:
```json
{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "address": "el1qq..."
}
```

Response (200):
```json
{
  "transaction_id": "uuid",
  "quote_id": "uuid",
  "brl_debited": 1000,
  "brc_minted": 950,
  "fee": 50,
  "address": "el1qq...",
  "liquid_txid": "hex...",
  "brl_balance": 4000,
  "brc_balance": 4750,
  "status": "confirmed"
}
```

Errors: 400 INVALID_AMOUNT, INVALID_ADDRESS, INVALID_QUOTE, INSUFFICIENT_BRL_BALANCE | 401 Unauthorized | 403 Forbidden | 502 Bad Gateway | 503 Service Unavailable

---

### POST /v1/withdraw
Redeem BRC (burn) and receive BRL via PIX.

Request:
```json
{
  "brc_amount": 947.5
}
```

Response (200):
```json
{
  "transaction_id": "uuid",
  "brc_burned": 947.5,
  "pix_amount": 947.5,
  "fee": 0,
  "liquid_txid": "hex...",
  "brc_balance": 3802.5,
  "status": "confirmed"
}
```

Errors: 400 Bad Request | 401 Unauthorized | 403 Forbidden | 502 Bad Gateway | 503 Service Unavailable

---

### GET /v1/balance
Get BRL and BRC ledger balances for the authenticated partner.

Response (200):
```json
{
  "brl_balance": 5000,
  "brc_balance": 4750
}
```

---

### GET /v1/me
Get the authenticated partner's profile, including fees.

Response (200):
```json
{
  "id": "uuid",
  "name": "Parceiro X",
  "email": "contato@parceiro.com",
  "status": "active",
  "liquid_address": "el1qq...",
  "webhook_url": "https://parceiro.com/webhook",
  "brl_balance": 5000,
  "brc_balance": 4750,
  "fees": {
    "deposit_fee_pct": 0,
    "deposit_fee_fixed": 0,
    "convert_fee_pct": 0.05,
    "convert_fee_fixed": 2.5,
    "withdraw_fee_pct": 0,
    "withdraw_fee_fixed": 0
  }
}
```

---

### GET /v1/transactions?limit=50&offset=0
List the partner's transactions. Supports pagination via limit (max 200) and offset.

Response (200):
```json
{
  "total": 42,
  "limit": 50,
  "offset": 0,
  "transactions": [
    {
      "id": "uuid",
      "type": "convert",
      "status": "confirmed",
      "brl_amount": 1000,
      "brc_amount": 950,
      "fee_amount": 50,
      "railway": "pix",
      "liquid_address": "el1qq...",
      "liquid_txid": "hex...",
      "pix_tx_id": "",
      "quote_id": "uuid",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:01:00Z"
    }
  ]
}
```

---

### GET /v1/health (public)
Check API and elementsd node status.

Response (200):
```json
{
  "status": "ok",
  "elements": {
    "status": "ok",
    "network": "liquidv1",
    "block_height": 123456,
    "synced": true
  }
}
```

Response (503 — degraded):
```json
{
  "status": "degraded",
  "elements": {
    "status": "unavailable",
    "error": "connection refused"
  }
}
```

---

### GET /v1/asset-info (public)
Get BRC asset metadata from the Elements node.

Response (200):
```json
{
  "asset_id": "hex...",
  "reissuance_token": "hex...",
  "network": "liquidv1",
  "node_version": "23.x",
  "node_block_height": 123456
}
```

## Error Format

All errors follow this envelope:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

Common codes: INVALID_AMOUNT, INVALID_ADDRESS, INVALID_QUOTE, INVALID_RAILWAY, INSUFFICIENT_BRL_BALANCE, INVALID_CREDENTIALS, PARTNER_SUSPENDED

## Typical Integration Flow

1. POST /v1/deposit → deposit BRL (status: pending)
2. Wait for deposit confirmation (webhook or admin)
3. GET /v1/quote?brl_amount=X → get quote (valid 2 min)
4. POST /v1/convert → mint BRC to a Liquid address
5. POST /v1/withdraw → burn BRC and receive BRL via PIX
6. GET /v1/balance → check balances at any time
7. GET /v1/transactions → list transaction history

## Notes

- All amounts are JSON numbers (also accepts decimal strings).
- Quotes expire after 2 minutes.
- PIX cash-in is instant; BRC minting on Liquid takes ~2 min finality.
- Cash-out (BRC → BRL via PIX) is processed in seconds.
- Liquid addresses start with "el1qq..." (confidential) or "ex1q..." (unblinded).
- Contact: contato@brctoken.xyz