smom-dbis-138/docs/bridge/API_DOCUMENTATION.md

Bridge API Documentation

Overview

The Bridge API provides endpoints for initiating, tracking, and managing cross-chain transfers from Chain 138 to EVM chains, XRPL, and Hyperledger Fabric networks.

Base URL

https://api.bridge.chain138.example.com

Authentication

Most endpoints require authentication via API key:

Authorization: Bearer <api_key>

Endpoints

1. Get Bridge Quote

Get a quote for bridging tokens to a destination chain.

Endpoint: POST /api/bridge/quote

Request Body:

{
  "token": "0x0000000000000000000000000000000000000000",
  "amount": "1000000000000000000",
  "destinationChainId": 137,
  "destinationType": 0,
  "destinationAddress": "0x..."
}

Response:

{
  "transferId": "0x...",
  "routes": [
    {
      "chainId": 137,
      "chainName": "Polygon",
      "provider": "thirdweb",
      "estimatedTime": 300,
      "fee": "1000000000000000",
      "healthScore": 9500
    }
  ],
  "recommendedRoute": {
    "chainId": 137,
    "chainName": "Polygon",
    "provider": "thirdweb",
    "estimatedTime": 300,
    "fee": "1000000000000000",
    "healthScore": 9500
  },
  "totalFee": "1000000000000000",
  "minReceived": "999000000000000000",
  "estimatedTime": 300,
  "slippage": "50",
  "riskLevel": 0,
  "sourceSwapQuote": "998000000000000000",
  "destinationSwapQuote": "997000000000000000"
}

When EnhancedSwapRouter is configured, the response may include sourceSwapQuote and destinationSwapQuote (best Dodoex-inclusive swap quote on source and destination chain).

1b. Swap + Bridge + Swap Quote (full path)

Get a combined quote for swapping on source chain, bridging, then swapping on destination chain.

Endpoint: POST /api/bridge/quote

Request Body (extended for swap+bridge+swap):

{
  "sourceToken": "0x...",
  "destinationToken": "0x...",
  "sourceChainId": 138,
  "destinationChainId": 137,
  "amount": "1000000000000000000",
  "destinationAddress": "0x..."
}

Response: Same as Get Bridge Quote; minReceived reflects the full path when source/destination swap routers are configured. Use sourceSwapQuote and destinationSwapQuote for per-leg amounts. Initiate flow: (1) source tx: swap + bridge via SwapBridgeSwapCoordinator.swapAndBridge, (2) destination tx: claim + swap via BridgeSwapCoordinator.bridgeAndSwap or coordinator contract.

2. Initiate XRPL Bridge

Initiate a bridge transfer to XRPL.

Endpoint: POST /api/bridge/xrpl/initiate

Request Body:

{
  "amount": "1000000000000000000",
  "destinationAddress": "rXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "destinationTag": 12345,
  "token": "0x0000000000000000000000000000000000000000"
}

Response:

{
  "transferId": "0x...",
  "status": "INITIATED",
  "timestamp": 1234567890
}

3. Get Transfer Status

Get the current status of a bridge transfer.

Endpoint: GET /api/bridge/status/:transferId

Response:

{
  "transferId": "0x...",
  "status": "EXECUTING",
  "depositor": "0x...",
  "asset": "0x0000000000000000000000000000000000000000",
  "amount": "1000000000000000000",
  "destinationType": 0,
  "destinationData": "0x...",
  "timestamp": 1234567890,
  "timeout": 3600,
  "refunded": false,
  "executionData": {
    "txHash": "0x...",
    "blockNumber": 12345
  },
  "route": {
    "chainId": 137,
    "chainName": "Polygon",
    "provider": "thirdweb",
    "estimatedTime": 300,
    "fee": "1000000000000000",
    "healthScore": 9500
  },
  "isRefundable": false,
  "refundDeadline": 1234567890
}

4. Get XRPL Quote

Get a quote for bridging to XRPL.

Endpoint: POST /api/bridge/xrpl/quote

Request Body:

{
  "token": "0x0000000000000000000000000000000000000000",
  "amount": "1000000000000000000",
  "destinationAddress": "rXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "destinationTag": 12345
}

Response:

{
  "fee": "2000000000000000",
  "minReceived": "998000000000000000",
  "estimatedTime": 60,
  "route": {
    "chainId": 0,
    "chainName": "XRPL",
    "provider": "cacti-xrpl",
    "estimatedTime": 60,
    "fee": "2000000000000000",
    "healthScore": 8000
  }
}

Admin Endpoints

5. Get Bridge Metrics

Get aggregated bridge metrics.

Endpoint: GET /api/admin/metrics

Response:

{
  "totalTransfers": 1000,
  "successRate": 98.5,
  "avgSettlementTime": 285,
  "refundRate": 1.2,
  "liquidityFailures": 5
}

6. List Transfers

List recent transfers with optional filters.

Endpoint: GET /api/admin/transfers

Query Parameters:

• limit (optional): Number of results (default: 50)
• offset (optional): Pagination offset (default: 0)
• status (optional): Filter by status
• depositor (optional): Filter by depositor address

Response:

{
  "transfers": [
    {
      "transferId": "0x...",
      "status": "COMPLETED",
      "depositor": "0x...",
      "amount": "1000000000000000000",
      "destinationType": 0,
      "timestamp": 1234567890
    }
  ],
  "total": 1000,
  "limit": 50,
  "offset": 0
}

7. Pause Bridge Operations

Pause bridge operations globally or for specific token/destination.

Endpoint: POST /api/admin/pause

Request Body:

{
  "type": "global",
  "id": null
}

Types:

• global: Pause all operations
• token: Pause specific token (provide token address in id)
• destination: Pause specific destination (provide chainId in id)

Response:

{
  "success": true,
  "message": "Bridge paused successfully"
}

8. Initiate Refund

Manually initiate a refund for a failed transfer.

Endpoint: POST /api/admin/refund/:transferId

Response:

{
  "success": true,
  "transferId": "0x...",
  "status": "REFUND_PENDING"
}

Error Responses

All endpoints may return error responses in the following format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Codes

• INVALID_REQUEST: Invalid request parameters
• TRANSFER_NOT_FOUND: Transfer ID not found
• INSUFFICIENT_BALANCE: Insufficient balance for transfer
• INVALID_ROUTE: No valid route available
• BRIDGE_PAUSED: Bridge operations are currently paused
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions
• INTERNAL_ERROR: Internal server error

Rate Limiting

API requests are rate-limited:

• Public endpoints: 100 requests per minute per IP
• Admin endpoints: 1000 requests per minute per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

WebSocket Events

Real-time transfer status updates are available via WebSocket:

Connection: wss://api.bridge.chain138.example.com/ws

Subscribe to transfer:

{
  "action": "subscribe",
  "transferId": "0x..."
}

Event:

{
  "event": "transfer_status_update",
  "transferId": "0x...",
  "status": "EXECUTING",
  "timestamp": 1234567890
}

SDK Examples

JavaScript/TypeScript

import { BridgeClient } from '@chain138/bridge-sdk';

const client = new BridgeClient({
  apiUrl: 'https://api.bridge.chain138.example.com',
  apiKey: 'your-api-key'
});

// Get quote
const quote = await client.getQuote({
  token: '0x0000000000000000000000000000000000000000',
  amount: '1000000000000000000',
  destinationChainId: 137,
  destinationType: 0,
  destinationAddress: '0x...'
});

// Initiate transfer
const transfer = await client.initiateTransfer(quote);

Python

from chain138_bridge import BridgeClient

client = BridgeClient(
    api_url='https://api.bridge.chain138.example.com',
    api_key='your-api-key'
)

# Get quote
quote = client.get_quote(
    token='0x0000000000000000000000000000000000000000',
    amount='1000000000000000000',
    destination_chain_id=137,
    destination_type=0,
    destination_address='0x...'
)

# Initiate transfer
transfer = client.initiate_transfer(quote)

Support

For API support, contact:

• Email: api-support@chain138.example.com
• Documentation: https://docs.bridge.chain138.example.com
• Status: https://status.bridge.chain138.example.com