# Bernie Bridge API — AI / LLM Skill

> Use this document to interact with the Bernie Bridge API programmatically.
> Base URL: `https://berniebridge.xyz/api/v1`

## Overview

The Bernie Bridge allows bridging assets between Ethereum, BNB Smart Chain, XRP Ledger, and BESC Hyperchain. This API lets you create deposit requests, track their status, and query referral data.

## Authentication

All endpoints except `GET /bridge/assets` require an API key.

```
X-API-Key: bb_live_<your_key>
```

Or:

```
Authorization: Bearer bb_live_<your_key>
```

Rate limit: 60 requests/minute per key. HTTP 429 when exceeded.

## Error Format

All errors return JSON:

```json
{ "error": "error_code", "detail": "Human-readable description" }
```

Codes: `unauthorized` (401), `rate_limit_exceeded` (429), `validation` (400), `not_found` (404), `rpc_error` (502), `not_configured` (503).

---

## Bridge API

### GET /bridge/assets

List supported assets and chains. **No authentication required.**

```bash
curl https://berniebridge.xyz/api/v1/bridge/assets
```

Response fields per asset: `id`, `symbol`, `besc_symbol`, `source_chain` (eth|bsc|xrpl), `source_chain_id`, `decimals`, `besc_decimals`, `lock_contract`, `token_contract`, `besc_mint_contract`, `is_native`, `xrpl_bridge_address`.

Response fields per chain: `id`, `name`, `chain_id`, `type` (evm|xrpl).

### POST /bridge/deposit

Create a bridge deposit. Returns a deposit address to send funds to.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| chain | string | yes | `"eth"`, `"bsc"`, or `"xrpl"` |
| asset | string | yes | `"ETH"`, `"BNB"`, `"USDT"`, or `"XRP"` |
| besc_recipient | string | yes | `0x` address on BESC to receive bridged tokens |
| referral_code | number | no | Referral code (defaults to API key's default) |

**Valid chain/asset combinations:**
- `eth`: ETH, USDT
- `bsc`: BNB, USDT
- `xrpl`: XRP

```bash
curl -X POST https://berniebridge.xyz/api/v1/bridge/deposit \
  -H "X-API-Key: bb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"chain":"eth","asset":"ETH","besc_recipient":"0xYourBescAddress"}'
```

**EVM response:**

```json
{
  "id": "uuid",
  "chain": "eth",
  "asset": "ETH",
  "deposit_address": "0xHdDerivedAddress",
  "besc_recipient": "0x...",
  "status": "awaiting_deposit",
  "expires_at": "2026-03-22T12:00:00.000Z",
  "instructions": "Send ETH to 0x... on ETH. The bridge will automatically process your deposit and mint bETH to 0x... on BESC."
}
```

**XRPL response** (includes `destination_tag` and `memo`):

```json
{
  "id": "uuid",
  "chain": "xrpl",
  "asset": "XRP",
  "deposit_address": "rUQZBoNywgL7CzuMXjp74wM5V3i4tvTfMD",
  "destination_tag": 1001,
  "memo": "BERNIE1|0xBescRecipient",
  "besc_recipient": "0x...",
  "status": "awaiting_deposit",
  "expires_at": "2026-03-22T12:00:00.000Z",
  "instructions": "Send XRP to r... with destination tag 1001 and memo: BERNIE1|0x..."
}
```

Deposits expire after 1 hour if no funds are received.

### GET /bridge/status/{id}

Get the current status of a deposit by its UUID.

```bash
curl https://berniebridge.xyz/api/v1/bridge/status/{deposit_id} \
  -H "X-API-Key: bb_live_your_key"
```

Response includes: `id`, `chain`, `asset`, `deposit_address`, `destination_tag`, `besc_recipient`, `referral_code`, `status`, `amount_received`, `deposit_tx_hash`, `forward_tx_hash`, `bridge_event_id`, `created_at`, `updated_at`, `expires_at`.

**Status flow:** `awaiting_deposit` → `deposited` → `forwarding` → `bridging` → `completed`

Other terminal states: `expired` (no funds received within TTL), `failed` (forwarding error).

### GET /bridge/deposits

List all deposits for your API key.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | no | Filter by status |
| limit | number | no | Max results (default 50, max 200) |
| offset | number | no | Pagination offset |

```bash
curl "https://berniebridge.xyz/api/v1/bridge/deposits?status=completed&limit=10" \
  -H "X-API-Key: bb_live_your_key"
```

---

## Referral API

### GET /referral/info?address=0x...

Get on-chain referral information for a BESC address.

```bash
curl "https://berniebridge.xyz/api/v1/referral/info?address=0xYourAddress" \
  -H "X-API-Key: bb_live_your_key"
```

Response:

```json
{
  "registered": true,
  "code": 42,
  "referrer": "0x...",
  "chain": ["0x..."],
  "level_rates": [100, 50, 25, 12, 6],
  "max_depth": 5
}
```

`level_rates` are in parts-per-million (PPM). Level 1 = 100 PPM = 0.01%.

### GET /referral/rewards?address=0x...

Get claimable referral rewards across all bridged asset contracts on BESC.

```bash
curl "https://berniebridge.xyz/api/v1/referral/rewards?address=0xYourAddress" \
  -H "X-API-Key: bb_live_your_key"
```

Response:

```json
{
  "address": "0x...",
  "rewards": {
    "bUSDT": "1500000",
    "bETH": "500000000000000",
    "bBNB": "0",
    "bXRP": "250000"
  }
}
```

Values are in the token's smallest unit (wei for bETH/bBNB, 6-decimal units for bUSDT/bXRP).

### GET /referral/stats?code=42

Get statistics for a referral code.

```bash
curl "https://berniebridge.xyz/api/v1/referral/stats?code=42" \
  -H "X-API-Key: bb_live_your_key"
```

Response: `code`, `code_formatted` (zero-padded), `address`, `registered`, `referrer`, `referral_chain`, `level_rates_ppm`, `total_registered_network`.

### GET /referral/resolve?code=42

Resolve a numeric referral code to its wallet address.

```bash
curl "https://berniebridge.xyz/api/v1/referral/resolve?code=42" \
  -H "X-API-Key: bb_live_your_key"
```

Response:

```json
{ "code": 42, "code_formatted": "000042", "address": "0x..." }
```

Returns 404 if the code is not registered.

---

## Typical Workflow

1. **Get supported assets:** `GET /bridge/assets` to see available chains and tokens.
2. **Create a deposit:** `POST /bridge/deposit` with chain, asset, and BESC recipient.
3. **Send funds:** Transfer the asset to the returned `deposit_address` (EVM) or bridge address with `destination_tag` (XRPL).
4. **Poll status:** `GET /bridge/status/{id}` until status is `completed`.
5. **Check rewards:** `GET /referral/rewards?address=...` to see accumulated referral earnings.

## Chains & Assets Reference

| Chain | ID | Assets | Type |
|-------|----|--------|------|
| Ethereum | 1 | ETH, USDT | EVM |
| BNB Smart Chain | 56 | BNB, USDT | EVM |
| XRP Ledger | — | XRP | XRPL |
| BESC Hyperchain | 2372 | bUSDT, bETH, bBNB, bXRP | EVM |

## Asset Decimals

| Asset | Source Decimals | BESC Decimals |
|-------|----------------|---------------|
| ETH / bETH | 18 | 18 |
| BNB / bBNB | 18 | 18 |
| USDT / bUSDT | 6 (ETH) / 18 (BSC) | 6 |
| XRP / bXRP | 6 (drops) | 6 |