API Reference

Complete REST API documentation for AggKit Bridge Service with examples and response formats

API Base URL

All Bridge Service endpoints follow a consistent structure that makes integration straightforward:

{base_url}/bridge/v1/{endpoint}

Health & Status

GET / - Service Health Check

Before integrating with the Bridge Service API, you’ll want to verify it’s running and healthy.

Use Case: Application health monitoring and service discovery.

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

When troubleshooting missing data or stale responses, check whether all underlying components are properly synchronized.

Use Case: Debugging data availability issues and monitoring sync lag.

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"
  }
}

What This Tells You: - L1/L2 Sync: How current the blockchain data is - Bridge Sync: Number of bridge events indexed and last update time - Is Synced: Whether there’s significant lag that might affect data freshness

Bridge Transaction Queries

GET /bridges - Query Bridge Transactions

The most commonly used endpoint for getting bridge transaction data. Perfect for building transaction histories, monitoring user activity, and tracking bridge status.

Common Use Cases: - “Show all bridges from this user’s address” - “Find bridge transactions between these networks” - “Get transaction history with pagination” - “Check if a specific bridge was processed”

Parameters:

Parameter	Type	Required	Description	Example
network_id	integer	✅	Origin network ID (0=L1, 1=L2, etc.)	0
page_number	integer	❌	Page number (default: 1)	1
page_size	integer	❌	Page size (default: 100, max: 1000)	10
deposit_count	integer	❌	Filter by specific deposit count	42
from_address	string	❌	Filter by sender address	0xf39F...
network_ids	array	❌	Filter by destination network IDs	1,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

Check which bridge transactions have been successfully claimed. Essential for verifying claim completion and avoiding duplicate claims.

Use Cases: - “Has this bridge been claimed yet?” - “Show all claims by this user” - “Verify claim completion”

Key Parameters:

Parameter	Type	Required	Description
network_id	integer	✅	Network where claims occurred
from_address	string	❌	Filter by claimer address
page_size	integer	❌	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

The most important endpoint for bridge applications - generates the cryptographic proofs required to claim bridged assets.

Use Case: Get all the proof data needed to execute a claim transaction on the destination chain.

Required Parameters:

Parameter	Type	Description	Example
network_id	integer	Origin network of bridge transaction	0
deposit_count	integer	Deposit count from bridge event	42
leaf_index	integer	L1 Info Tree index for proof	15

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
    }
  }
}

Usage: Pass the entire proof object to your claim contract function. The API handles all the complex Merkle tree calculations for you.

Additional Utilities

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

Find the L1 Info Tree index needed for proof generation from a bridge transaction.

Use Case: Get the leaf_index parameter required for /claim-proof endpoint.

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 Code	When It Happens	What To Do
INVALID_NETWORK_ID	Using unsupported network ID	Check supported networks via / endpoint
BRIDGE_NOT_FOUND	Transaction not yet indexed	Wait for indexing to complete
PROOF_NOT_AVAILABLE	L1 finality not reached	Wait for L1 confirmation
RATE_LIMIT_EXCEEDED	Too many requests	Implement backoff and retry

Example Error Response:

{
  "error": {
    "code": "INVALID_NETWORK_ID",
    "message": "Network ID 999 is not supported"
  }
}