Skip to main content

​
API Base URL

All Bridge Service endpoints follow this structure: 
{base_url}/bridge/v1/{endpoint}

​
Health & Status

​
GET / - Service Health Check

Example Request: 
curl "http://localhost:5577/"
Response: 
{
  "status": "healthy",
  "version": "1.0.0",
  "network_id": 1,
  "uptime": "2h15m30s",
  "last_processed_block": 15234567
}
Response Fields:
  • status: Service health indicator
  • version: API version for compatibility checks
  • network_id: Primary network being served
  • uptime: Service runtime duration
  • last_processed_block: Latest indexed block number

​
GET /sync-status - Component Synchronization Status

Example Request: 
curl "http://localhost:5577/bridge/v1/sync-status"
Response: 
{
  "l1_sync": {
    "current_block": 15234567,
    "synced_block": 15234560,
    "is_synced": true
  },
  "l2_sync": {
    "current_block": 8765432,
    "synced_block": 8765432,
    "is_synced": true
  },
  "bridge_sync": {
    "l1_bridges_indexed": 12345,
    "l2_bridges_indexed": 6789,
    "last_update": "2024-09-24T10:30:45Z"
  }
}

​
Bridge Transaction Queries

​
GET /bridges - Query Bridge Transactions

Parameters:
ParameterTypeRequiredDescriptionExample
network_idinteger✅Origin network ID (0=L1, 1=L2, etc.)0
page_numberinteger❌Page number (default: 1)1
page_sizeinteger❌Page size (default: 100, max: 1000)10
deposit_countinteger❌Filter by specific deposit count42
from_addressstring❌Filter by sender address0xf39F...
network_idsarray❌Filter by destination network IDs1,2
Example Request Patterns: 
# Get recent bridges for a user
curl "http://localhost:5577/bridge/v1/bridges?network_id=0&from_address=0xf39F...&page_size=10"

# Find specific transaction by deposit count
curl "http://localhost:5577/bridge/v1/bridges?network_id=0&deposit_count=42"

# Check ready-to-claim transactions
curl "http://localhost:5577/bridge/v1/bridges?network_id=0&ready_for_claim=true"
Response Structure: 
{
  "bridges": [
    {
      "tx_hash": "0x8d1b60d0eaab6f609955bdd371e8004f47349cc809ff1bee81dc9d37237a031c",
      "deposit_count": 42,
      "origin_network": 0,
      "destination_network": 1,
      "origin_address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
      "destination_address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
      "amount": "1000000000000000000",
      "block_timestamp": 1695563045,
      "ready_for_claim": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150
  }
}
Key Response Fields:
  • tx_hash: Bridge transaction identifier
  • deposit_count: Sequential index for proof generation
  • amount: Bridge amount in wei/token units
  • ready_for_claim: Whether transaction can be claimed
  • block_timestamp: When the bridge occurred

​
Claim Tracking

​
GET /claims - Query Claim Transactions

Key Parameters:
ParameterTypeRequiredDescription
network_idinteger✅Network where claims occurred
from_addressstring❌Filter by claimer address
page_sizeinteger❌Results per page (default: 100)
Example Usage: 
# Check claims on a specific network
curl "http://localhost:5577/bridge/v1/claims?network_id=1&page_size=10"

# Find claims by specific user
curl "http://localhost:5577/bridge/v1/claims?network_id=1&from_address=0x7099..."
Response: 
{
  "claims": [
    {
      "tx_hash": "0xa9fa5418144f7c8c1b78cd0e5560d6550411667ef937b554636a613f933b3d9f",
      "global_index": "0x000000000000000000000000000000000000000000000000000000000000002a",
      "amount": "1000000000000000000",
      "block_timestamp": 1695563145,
      "bridge_tx_hash": "0x8d1b60d0eaab6f609955bdd371e8004f47349cc809ff1bee81dc9d37237a031c"
    }
  ]
}

​
Proof Generation

​
GET /claim-proof - Generate Claim Proof

Generates the cryptographic proofs required to claim bridged assets. Pass the entire proof object returned to your claim contract function. Required Parameters:
ParameterTypeDescriptionExample
network_idintegerOrigin network of bridge transaction0
deposit_countintegerDeposit count from bridge event42
leaf_indexintegerL1 Info Tree index for proof15
Example Request: 
curl "http://localhost:5577/bridge/v1/claim-proof?network_id=0&deposit_count=42&leaf_index=15"
Response Structure: 
{
  "proof": {
    "smtProofLocalExitRoot": ["0x...", "0x...", "0x..."],
    "smtProofRollupExitRoot": ["0x...", "0x..."],
    "l1InfoTreeLeaf": {
      "globalExitRoot": "0x...",
      "blockNumber": 15234567,
      "timestamp": 1695563045
    }
  }
}

​
Additional Utilities

​
GET /l1-info-tree-index - Get L1 Info Tree Index

Returns the L1 Info Tree index required for the leaf_index parameter in /claim-proof. 
curl "http://localhost:5577/bridge/v1/l1-info-tree-index?network_id=0&deposit_count=42"
Response: 
{
  "l1_info_tree_index": 15,
  "block_number": 15234567,
  "global_exit_root": "0x..."
}

​
GET /token-mappings - Token Information

Get token mapping information for cross-chain token relationships. Use Case: Display token information and cross-chain mappings in bridge interfaces. 
curl "http://localhost:5577/bridge/v1/token-mappings"

​
Error Handling

Common Error Scenarios:
Error CodeWhen It HappensWhat To Do
INVALID_NETWORK_IDUsing unsupported network IDCheck supported networks via / endpoint
BRIDGE_NOT_FOUNDTransaction not yet indexedWait for indexing to complete
PROOF_NOT_AVAILABLEL1 finality not reachedWait for L1 confirmation
RATE_LIMIT_EXCEEDEDToo many requestsImplement backoff and retry
Example Error Response: 
{
  "error": {
    "code": "INVALID_NETWORK_ID",
    "message": "Network ID 999 is not supported"
  }
}