XRPL Module

The xrpl module provides XRPL blockchain integration for onramp/offramp operations, trustlines management, and issued currency support.

Import

const xrpl = await brdzSDK.xrpl;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint	Implementation
`getIssuerByCurrency`	Get issuer data by currency	✅	`GET /xrpl/issuer/:currency`	⚠️ SDK Only
`getAllIssuers`	Get all active issuers	✅	`GET /xrpl/issuer`	⚠️ SDK Only
`createIssuer`	Add new issuer	✅	`POST /xrpl/issuer`	⚠️ SDK Only
`getTrustlines`	Get user trustlines	✅	`GET /xrpl/trustlines/:userId`	⚠️ SDK Only
`createTrustline`	Create trustline	✅	`POST /xrpl/trustlines`	⚠️ SDK Only
`initOnramp`	Initialize XRPL onramp	✅	`POST /xrpl/onramp/init`	✅ Full Support
`getOnrampStatus`	Check onramp status	✅	`GET /xrpl/onramp/status/:txid`	✅ Full Support

getIssuerByCurrency

Get issuer information for a specific currency on XRPL.

Syntax

const result = await xrpl.getIssuerByCurrency(currency);

Parameters

Parameter	Type	Required	Description
`currency`	`string`	✅	Currency code (e.g., "USDC")

Returns

Promise<{
  // Response structure based on xrplIssuerModel.getIssuerByCurrency
  id?: number;
  issuer_address: string;
  currency_code: string;
  created_at?: string;
  updated_at?: string;
}>

Example

try {
  const issuer = await xrpl.getIssuerByCurrency('USDC');
  console.log('Issuer Address:', issuer.issuer_address);
  console.log('Currency:', issuer.currency_code);
} catch (error) {
  console.error('Failed to get issuer:', error.message);
}

HTTP Endpoint

Method: GET
URL: https://api.brdz.link/api/xrpl/issuer/:currency
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

⚠️ Note: Backend implementation not available. SDK method calls endpoint but may receive 404.

getAllIssuers

Get list of all active currency issuers on XRPL.

Syntax

const result = await xrpl.getAllIssuers();

Parameters

None.

Returns

Promise<Array<{
  id: number;
  issuer_address: string;
  currency_code: string;
  created_at: string;
  updated_at: string;
}>>

Example

try {
  const issuers = await xrpl.getAllIssuers();
  console.log('Total Issuers:', issuers.length);
  
  issuers.forEach(issuer => {
    console.log(`${issuer.currency_code}: ${issuer.issuer_address}`);
  });
} catch (error) {
  console.error('Failed to get issuers:', error.message);
}

HTTP Endpoint

Method: GET
URL: https://api.brdz.link/api/xrpl/issuer
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

⚠️ Note: Backend implementation not available. SDK method calls endpoint but may receive 404.

createIssuer

Syntax

const result = await xrpl.createIssuer(data);

Parameters

Parameter	Type	Required	Description
`data`	`object`	✅	Issuer creation data
`data.currency_code`	`string`	✅	Currency code (e.g., "USDC")
`data.issuer_address`	`string`	✅	XRPL issuer address

Returns

Promise<{
  id: number;
  issuer_address: string;
  currency_code: string;
  created_at: string;
  updated_at: string;
}>

Example

try {
  const newIssuer = await xrpl.createIssuer({
    currency_code: 'USDC',
    issuer_address: 'r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos'
  });
  
  console.log('Issuer created:', newIssuer.id);
  console.log('Address:', newIssuer.issuer_address);
} catch (error) {
  console.error('Failed to create issuer:', error.message);
}

HTTP Endpoint

Method: POST
URL: https://api.brdz.link/api/xrpl/issuer
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

⚠️ Note: Backend implementation not available. SDK method calls endpoint but may receive 404.

getTrustlines

Get all trustlines for a specific user.

Syntax

const result = await xrpl.getTrustlines(userId);

Parameters

Parameter	Type	Required	Description
`userId`	`string`	✅	User ID to get trustlines for

Returns

Promise<Array<{
  id: number;
  user_id: number;
  xrpl_address: string;
  currency_code: string;
  issuer_id: number;
  trustline_status: string;
  created_at: string;
  updated_at: string;
}>>

Example

try {
  const trustlines = await xrpl.getTrustlines('123');
  console.log('User Trustlines:', trustlines.length);
  
  trustlines.forEach(tl => {
    console.log(`${tl.currency_code}: ${tl.trustline_status}`);
  });
} catch (error) {
  console.error('Failed to get trustlines:', error.message);
}

HTTP Endpoint

Method: GET
URL: https://api.brdz.link/api/xrpl/trustlines/:userId
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

⚠️ Note: Backend implementation not available. SDK method calls endpoint but may receive 404.

createTrustline

Create a new trustline between user and currency issuer.

Syntax

const result = await xrpl.createTrustline(data);

Parameters

Parameter	Type	Required	Description
`data`	`object`	✅	Trustline creation data
`data.user_id`	`string`	✅	User ID
`data.currency`	`string`	✅	Currency code
`data.issuer_address`	`string`	✅	XRPL issuer address

Returns

Promise<{
  id: number;
  user_id: number;
  xrpl_address: string;
  currency_code: string;
  issuer_id: number;
  trustline_status: string;
  created_at: string;
  updated_at: string;
}>

Example

try {
  const trustline = await xrpl.createTrustline({
    user_id: '123',
    currency: 'USDC',
    issuer_address: 'r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos'
  });
  
  console.log('Trustline created:', trustline.id);
  console.log('Status:', trustline.trustline_status);
} catch (error) {
  console.error('Failed to create trustline:', error.message);
}

HTTP Endpoint

Method: POST
URL: https://api.brdz.link/api/xrpl/trustlines
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

⚠️ Note: Backend implementation not available. SDK method calls endpoint but may receive 404.

initOnramp

Initialize XRPL onramp transaction to convert fiat to USDC on XRPL.

Syntax

const result = await xrpl.initOnramp(data);

Parameters

Parameter	Type	Required	Description
`data`	`object`	✅	Onramp transaction data
`data.currency_code`	`string`	❌	Target currency (default: "USDC")
`data.amount`	`number`	❌	Direct USDC amount
`data.fiat_currency`	`string`	❌	Source fiat: IDR, SGD, USD, AUD, INR, VND
`data.fiat_amount`	`number`	❌	Fiat amount to convert

Returns

Promise<{
  message: string;
  data: {
    xrpl_tx: {
      id: number;
      user_id: number;
      tx_type: string;
      tx_hash: string;
      source_address: string;
      destination_address: string;
      currency_code: string;
      amount: string;
      status: string;
      raw_response: string;
      created_at: string;
      updated_at: string;
    };
    fx: {
      route: string;
      usdcIntermediate: number;
      result: number;
    } | null;
  };
}>

Example

try {
  // Option 1: Fiat conversion
  const onramp1 = await xrpl.initOnramp({
    fiat_currency: 'IDR',
    fiat_amount: 1500000
  });
  
  // Option 2: Direct USDC amount
  const onramp2 = await xrpl.initOnramp({
    amount: 100.5
  });
  
  console.log('Onramp initiated:', onramp1.message);
  console.log('TX Hash:', onramp1.data.xrpl_tx.tx_hash);
  console.log('FX Route:', onramp1.data.fx?.route);
} catch (error) {
  console.error('Onramp failed:', error.message);
}

HTTP Endpoint

Method: POST
URL: https://api.brdz.link/api/xrpl/onramp/init
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

✅ Full backend support available.

getOnrampStatus

Check the status of an XRPL onramp transaction.

Syntax

const result = await xrpl.getOnrampStatus(txid);

Parameters

Parameter	Type	Required	Description
`txid`	`string`	✅	XRPL transaction hash or onramp ID

Returns

Promise<{
  txid: string;
  status: string;
}>

Example

try {
  const status = await xrpl.getOnrampStatus('F3E6D7C8B9A0123456789ABCDEF012345');
  
  console.log('Transaction ID:', status.txid);
  console.log('Status:', status.status);
} catch (error) {
  console.error('Failed to get status:', error.message);
}

HTTP Endpoint

Method: GET
URL: https://api.brdz.link/api/xrpl/onramp/status/:txid
Headers: Authorization: Bearer <JWT_TOKEN>, x-api-key required

✅ Full backend support available.

Complete XRPL Integration Example

Basic Onramp Flow

class XRPLManager {
  constructor(sdk) {
    this.sdk = sdk;
  }

  async performOnramp(fiatCurrency, fiatAmount) {
    const xrpl = await this.sdk.xrpl;
    
    try {
      // Initialize onramp with fiat conversion
      const onramp = await xrpl.initOnramp({
        fiat_currency: fiatCurrency,
        fiat_amount: fiatAmount
      });
      
      console.log('Onramp initiated:', onramp.message);
      console.log('USDC Amount:', onramp.data.xrpl_tx.amount);
      console.log('FX Route:', onramp.data.fx?.route);
      
      // Monitor transaction status
      const txHash = onramp.data.xrpl_tx.tx_hash;
      if (txHash) {
        await this.monitorTransaction(txHash);
      }
      
      return onramp;
    } catch (error) {
      throw new Error(`Onramp failed: ${error.message}`);
    }
  }

  async monitorTransaction(txHash) {
    const xrpl = await this.sdk.xrpl;
    
    const checkStatus = async () => {
      try {
        const status = await xrpl.getOnrampStatus(txHash);
        console.log(`Transaction ${txHash}: ${status.status}`);
        
        if (status.status === 'tesSUCCESS') {
          console.log('Transaction completed successfully!');
          return true;
        } else if (status.status === 'PENDING') {
          console.log('Transaction still pending...');
          return false;
        } else {
          console.log('Transaction failed or unknown status');
          return true;
        }
      } catch (error) {
        console.error('Status check failed:', error.message);
        return false;
      }
    };
    
    // Poll every 10 seconds
    const pollInterval = setInterval(async () => {
      const completed = await checkStatus();
      if (completed) {
        clearInterval(pollInterval);
      }
    }, 10000);
    
    // Stop polling after 5 minutes
    setTimeout(() => {
      clearInterval(pollInterval);
      console.log('Stopped monitoring transaction');
    }, 300000);
  }

  async getIssuerInfo(currency) {
    const xrpl = await this.sdk.xrpl;
    
    try {
      const issuer = await xrpl.getIssuerByCurrency(currency);
      return issuer;
    } catch (error) {
      console.warn('Issuer endpoint not implemented on backend');
      // Fallback to environment variables for USDC
      if (currency === 'USDC') {
        return {
          currency_code: 'USDC',
          issuer_address: 'r9wxh8hwJcaQnC4ypWqZqpoYY4MS9Shmos'
        };
      }
      throw error;
    }
  }
}

// Usage Example
const xrplManager = new XRPLManager(brdzSDK);

// Perform IDR to USDC onramp
xrplManager.performOnramp('IDR', 1500000)
  .then(result => {
    console.log('Onramp successful:', result);
  })
  .catch(error => {
    console.error('Onramp failed:', error.message);
  });

Network Configuration

XRPL Testnet

Based on project configuration:

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

Supported Currencies

From fxRateService.js SUPPORTED_CURRENCIES:

IDR (Indonesian Rupiah)
SGD (Singapore Dollar)
USD (US Dollar)
AUD (Australian Dollar)
INR (Indian Rupee)
USDC (USD Coin)
VND (Vietnamese Dong)

FX Conversion

Route: All conversions via USDC (Fiat → USDC → Fiat)
Source: Live rates from Coinbase API
Precision: 6 decimals for USDC
Minimum: 0.000001 USDC

Implementation Status

✅ Fully Implemented (Backend + SDK)

initOnramp - XRPL onramp with fiat conversion
getOnrampStatus - Transaction status monitoring

⚠️ SDK Only (No Backend Implementation)

getIssuerByCurrency - Get issuer by currency
getAllIssuers - Get all issuers
createIssuer - Create new issuer
getTrustlines - Get user trustlines
createTrustline - Create trustline

❌ Missing from SDK (Backend Available)

These methods exist in controller but not in SDK modules:

initOfframp - XRPL offramp operations
getOfframpStatus - Offramp status monitoring
getXRPLHistory - Transaction history

Error Handling

Common Errors

Error	Description	Solution
`404: Endpoint not found`	Backend not implemented	Use available endpoints only
`400: Invalid parameters`	Wrong parameter format	Check parameter requirements
`400: Currency not supported`	Unsupported fiat currency	Use IDR, SGD, USD, AUD, INR, VND
`400: Amount too small`	Below minimum USDC precision	Increase fiat amount
`500: Service error`	XRPL service issues	Retry or contact support

Error Handling Example

try {
  const onramp = await xrpl.initOnramp({
    fiat_currency: 'IDR',
    fiat_amount: 1500000
  });
} catch (error) {
  if (error.message.includes('Currency not supported')) {
    console.error('Use supported currencies: IDR, SGD, USD, AUD, INR, VND');
  } else if (error.message.includes('Amount too small')) {
    console.error('Increase fiat amount for minimum USDC precision');
  } else if (error.message.includes('Issuer not found')) {
    console.error('USDC issuer not configured properly');
  } else {
    console.error('Onramp failed:', error.message);
  }
}

XRPL Testnet

All operations use XRPL Testnet. Addresses and transactions are for testing only.

Implementation Status

Only initOnramp and getOnrampStatus have full backend support. Other methods are SDK placeholders.

FX Rates

All fiat conversions use live Coinbase API rates via USDC intermediate currency.

Import​

Methods Overview​

getIssuerByCurrency​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

getAllIssuers​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

createIssuer​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

getTrustlines​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

createTrustline​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

initOnramp​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

getOnrampStatus​

Syntax​

Parameters​

Returns​

Example​

HTTP Endpoint​

Complete XRPL Integration Example​

Basic Onramp Flow​

Network Configuration​

XRPL Testnet​

Supported Currencies​

FX Conversion​

Implementation Status​

✅ Fully Implemented (Backend + SDK)​

⚠️ SDK Only (No Backend Implementation)​

❌ Missing from SDK (Backend Available)​

Error Handling​

Common Errors​

Error Handling Example​

Import

Methods Overview

getIssuerByCurrency

Syntax

Parameters

Returns

Example

HTTP Endpoint

getAllIssuers

Syntax

Parameters

Returns

Example

HTTP Endpoint

createIssuer

Syntax

Parameters

Returns

Example

HTTP Endpoint

getTrustlines

Syntax

Parameters

Returns

Example

HTTP Endpoint

createTrustline

Syntax

Parameters

Returns

Example

HTTP Endpoint

initOnramp

Syntax

Parameters

Returns

Example

HTTP Endpoint

getOnrampStatus

Syntax

Parameters

Returns

Example

HTTP Endpoint

Complete XRPL Integration Example

Basic Onramp Flow

Network Configuration

XRPL Testnet

Supported Currencies

FX Conversion

Implementation Status

✅ Fully Implemented (Backend + SDK)

⚠️ SDK Only (No Backend Implementation)

❌ Missing from SDK (Backend Available)

Error Handling

Common Errors

Error Handling Example