XRPL API

Interact with the XRP Ledger for onramp/offramp operations with issued currencies like USDC. Support for fiat-to-crypto conversion via FX rates and XRPL transaction management.

Initialize Onramp

POST/api/xrpl/onramp/init

Initialize XRPL Onramp

Convert fiat currency to USDC on XRPL. Supports direct USDC amount or fiat conversion via FX rates. Creates trustline automatically if needed and sends USDC from issuer to BRDZ wallet.

Parameters

currency_codestring

Target currency code (default: USDC)

amountnumber

Direct USDC amount (alternative to fiat conversion)

fiat_currencystring

Source fiat currency: IDR, SGD, USD, AUD, INR, VND

fiat_amountnumber

Fiat amount to convert to USDC

Request Body

{
  "currency_code": "USDC",
  "fiat_currency": "IDR",
  "fiat_amount": 1500000
}

Response

200Onramp initiated successfully

{
  "message": "Onramp initiated",
  "data": {
    "xrpl_tx": {
      "id": 1,
      "user_id": 123,
      "tx_type": "ONRAMP",
      "tx_hash": "F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345",
      "source_address": "r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos",
      "destination_address": "rUrLo6FbWL4AtnZC1i6buB55VuAXZKVLNh",
      "currency_code": "USDC",
      "amount": "100.500000",
      "status": "tesSUCCESS",
      "raw_response": "{\"txResult\":{\"hash\":\"F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345\",\"meta\":{\"TransactionResult\":\"tesSUCCESS\"}},\"fxContext\":{\"route\":\"IDR → USDC → USDC\",\"fiat_currency\":\"IDR\",\"fiat_amount\":1500000,\"usdc_amount\":100.5}}",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "fx": {
      "route": "IDR → USDC → USDC",
      "usdcIntermediate": 100.5,
      "result": 100.5
    }
  }
}

400Invalid request parameters

{
  "error": "Provide either amount (USDC) OR fiat_currency + fiat_amount"
}

404Issuer not found

{
  "error": "Issuer not found for given currency_code"
}

curl -X POST https://api.brdz.link/api/xrpl/onramp/init \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "currency_code": "USDC",
  "fiat_currency": "IDR",
  "fiat_amount": 1500000
}'

Get Onramp Status

GET/api/xrpl/onramp/status/{txid}

Get Onramp Status

Check the status of an XRPL onramp transaction using the transaction ID.

Parameters

txidstringrequired

XRPL transaction hash or onramp ID (path parameter)

Response

200Transaction status retrieved

{
  "txid": "F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345",
  "status": "validated"
}

400Missing transaction ID

{
  "error": "txid is required"
}

curl -X GET https://api.brdz.link/api/xrpl/onramp/status/F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Initialize Offramp

POST/api/xrpl/offramp/init

Initialize XRPL Offramp

Convert USDC to fiat or send USDC to another XRPL address. Supports both on-chain transfers and fiat payout to BRDZ wallet or bank.

Parameters

currency_codestring

Source currency code (default: USDC)

amountnumber

USDC amount (alternative to usdc_amount)

usdc_amountnumber

USDC amount to convert or send

destination_addressstring

XRPL address for on-chain transfer

target_fiatstring

Target fiat currency: IDR, SGD, USD, AUD, INR, VND

payout_typestring

Payout method: BRDZ_WALLET or BANK (default: BRDZ_WALLET)

destination_bankstring

Bank details for BANK payout type

receiver_user_idnumber

User ID for BRDZ_WALLET payout

receiver_currencystring

Currency for receiver wallet

wallet_idnumber

Wallet ID for BRDZ_WALLET payout

Request Body

{
  "currency_code": "USDC",
  "usdc_amount": 100.5,
  "target_fiat": "IDR",
  "payout_type": "BRDZ_WALLET",
  "wallet_id": 456
}

Response

200Offramp initiated successfully

{
  "message": "Offramp (fiat payout) initiated",
  "data": {
    "xrpl_tx": {
      "id": 2,
      "user_id": 123,
      "tx_type": "OFFRAMP_FIAT",
      "tx_hash": null,
      "source_address": "rUrLo6FbWL4AtnZC1i6buB55VuAXZKVLNh",
      "destination_address": "BRDZ_WALLET",
      "currency_code": "USDC",
      "amount": "100.500000",
      "status": "PENDING",
      "raw_response": "{\"fx\":{\"route\":\"USDC → USDC → IDR\",\"usdcIntermediate\":100.5,\"result\":1500000},\"payout_type\":\"BRDZ_WALLET\",\"destination_bank\":null}",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "payout": {
      "target_fiat": "IDR",
      "fiat_amount": 1500000,
      "payout_type": "BRDZ_WALLET",
      "destination_bank": null
    }
  }
}

400Invalid offramp parameters

{
  "error": "For fiat payout, provide usdc_amount and target_fiat"
}

curl -X POST https://api.brdz.link/api/xrpl/offramp/init \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "currency_code": "USDC",
  "usdc_amount": 100.5,
  "target_fiat": "IDR",
  "payout_type": "BRDZ_WALLET",
  "wallet_id": 456
}'

Get Offramp Status

GET/api/xrpl/offramp/status/{txid}

Get Offramp Status

Check the status of an XRPL offramp transaction using the transaction ID.

Parameters

txidstringrequired

XRPL transaction hash or offramp ID (path parameter)

Response

200Transaction status retrieved

{
  "txid": "F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345",
  "status": "validated"
}

400Missing transaction ID

{
  "error": "txid is required"
}

curl -X GET https://api.brdz.link/api/xrpl/offramp/status/F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get XRPL Transaction History

GET/api/xrpl/history

Get XRPL Transaction History

Retrieve user's XRPL transaction history including onramp and offramp operations.

Response

200Transaction history retrieved

{
  "message": "XRPL transaction history fetched successfully",
  "count": 2,
  "history": [
    {
      "id": 2,
      "tx_type": "OFFRAMP_FIAT",
      "tx_hash": null,
      "source_address": "rUrLo6FbWL4AtnZC1i6buB55VuAXZKVLNh",
      "destination_address": "BRDZ_WALLET",
      "currency_code": "USDC",
      "amount": "100.500000",
      "status": "PENDING",
      "raw_response": "{\"fx\":{\"route\":\"USDC → USDC → IDR\",\"usdcIntermediate\":100.5,\"result\":1500000},\"payout_type\":\"BRDZ_WALLET\",\"destination_bank\":null}",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 1,
      "tx_type": "ONRAMP",
      "tx_hash": "F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345",
      "source_address": "r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos",
      "destination_address": "rUrLo6FbWL4AtnZC1i6buB55VuAXZKVLNh",
      "currency_code": "USDC",
      "amount": "100.500000",
      "status": "tesSUCCESS",
      "raw_response": "{\"txResult\":{\"hash\":\"F3E6D7C8B9A0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF012345\",\"meta\":{\"TransactionResult\":\"tesSUCCESS\"}},\"fxContext\":{\"route\":\"IDR → USDC → USDC\",\"fiat_currency\":\"IDR\",\"fiat_amount\":1500000,\"usdc_amount\":100.5}}",
      "created_at": "2024-01-15T10:25:00Z",
      "updated_at": "2024-01-15T10:25:00Z"
    }
  ]
}

curl -X GET https://api.brdz.link/api/xrpl/history \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

XRPL Network Configuration

Testnet Settings

Setting	Value
Network	wss://s.altnet.rippletest.net:51233
RPC	https://s.altnet.rippletest.net:51234
Issuer Address	r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos
BRDZ Address	rUrLo6FbWL4AtnZC1i6buB55VuAXZKVLNh

Supported Currencies

Based on fxRateService.js SUPPORTED_CURRENCIES:

Currency	Code	Country
Indonesian Rupiah	IDR	Indonesia
Singapore Dollar	SGD	Singapore
US Dollar	USD	United States
Australian Dollar	AUD	Australia
Indian Rupee	INR	India
USD Coin	USDC	Stablecoin
Vietnamese Dong	VND	Vietnam

Transaction Types

Based on xrplTransactionModel.js:

Type	Description
ONRAMP	Fiat to USDC conversion
OFFRAMP	USDC to another XRPL address
OFFRAMP_FIAT	USDC to fiat conversion

Transaction Status Values

Status	Description
PENDING	Transaction initiated
tesSUCCESS	XRPL transaction successful
SUCCESS_RECEIVED	Mock mode success status

FX Rate Service

Conversion Process

1. Live Rates: Fetched from Coinbase API
2. Route: All conversions go through USDC (Fiat → USDC → Fiat)
3. Precision: USDC amounts rounded to 6 decimals
4. Minimum: 0.000001 USDC minimum amount

Example Conversion

// IDR to USD via USDC
// 1,500,000 IDR → 100.5 USDC → 100.5 USD
{
  route: "IDR → USDC → USD",
  usdcIntermediate: 100.5,
  result: 100.5
}

Database Schema

xrpl_transactions Table

- id (serial primary key)
- user_id (integer)
- tx_type (varchar) - ONRAMP, OFFRAMP, OFFRAMP_FIAT
- tx_hash (varchar) - XRPL transaction hash
- source_address (varchar) - XRPL source address
- destination_address (varchar) - XRPL destination address
- currency_code (varchar) - USDC
- amount (decimal) - Transaction amount
- status (varchar) - PENDING, tesSUCCESS, etc.
- raw_response (text) - JSON response data
- created_at (timestamp)
- updated_at (timestamp)

xrpl_issuers Table

- id (serial primary key)
- issuer_address (varchar) - XRPL issuer address
- currency_code (varchar) - Currency code (USDC)
- created_at (timestamp)
- updated_at (timestamp)

xrpl_trustlines Table

- id (serial primary key)
- user_id (integer)
- xrpl_address (varchar) - User's XRPL address
- currency_code (varchar) - Currency code (USDC)
- issuer_id (integer) - Reference to xrpl_issuers
- trustline_status (varchar) - PENDING, ACTIVE
- created_at (timestamp)
- updated_at (timestamp)

---

FX Conversion

All fiat conversions go through USDC as intermediate currency. Rates are fetched live from Coinbase API.

Testnet Only

Current implementation uses XRPL Testnet. All addresses and transactions are for testing purposes only.

Mock Mode

When MOCK_MODE=true, transactions show SUCCESS_RECEIVED status for testing.