The Bridge Hub API exposes interactive OpenAPI documentation at the /docs endpoint. You can browse endpoints and test API calls directly in the browser.
GET method, and all responses are returned as application/json.
GET /transactions
Query bridge transactions with filtering and cursor-based pagination.
Parameters
| Parameter | Type | Required | Description |
|---|
status | string | No | Filter by status: BRIDGED, READY_TO_CLAIM, CLAIMED |
sourceNetworkIds | string | No | Comma-separated source network IDs |
destinationNetworkIds | string | No | Comma-separated destination network IDs |
fromAddress | string | No | Filter by sender address |
receiverAddress | string | No | Filter by receiver address |
limit | integer | No | Results per page (default: 50) |
startAfter | string | No | Cursor for pagination |
Example request
curl "https://bridge-hub.example.com/transactions?status=READY_TO_CLAIM&limit=2"
Example response
{
"data": [
{
"hubUID": "tx-0001",
"sourceNetwork": 1,
"destinationNetwork": 2442,
"transactionHash": "0xabc123...",
"blockNumber": 19500000,
"timestamp": 1710000000,
"leafType": "ASSET",
"originTokenNetwork": 1,
"originTokenAddress": "0x0000000000000000000000000000000000000000",
"receiverAddress": "0xdef456...",
"fromAddress": "0x789abc...",
"amount": "1000000000000000000",
"depositCount": 42,
"leafIndexForProof": 42,
"globalIndex": "42",
"status": "READY_TO_CLAIM",
"lastUpdatedAt": 1710000300,
"claimTransactionHash": null,
"claimBlockNumber": null,
"claimTimestamp": null
}
],
"nextStartAfterCursor": "eyJsYXN0SWQiOiJ0eC0wMDAxIn0="
}
Response fields
| Field | Type | Description |
|---|
hubUID | string | Unique business key for the transaction |
sourceNetwork | number | Source chain ID |
destinationNetwork | number | Destination chain ID |
transactionHash | string | Source transaction hash |
blockNumber | number | Block number on the source chain |
timestamp | number | Unix timestamp of the bridge event |
leafType | string | ASSET or MESSAGE |
originTokenNetwork | number | Network ID where the token originates |
originTokenAddress | string | Token contract address on the origin network |
receiverAddress | string | Address that will receive funds on destination |
fromAddress | string | Sender address on the source chain |
amount | string | Transfer amount (BigInt encoded as string) |
depositCount | number | Deposit counter from the bridge event |
leafIndexForProof | number | Leaf index in the merkle tree |
globalIndex | string | Global index (encoded as string) |
status | string | BRIDGED, READY_TO_CLAIM, or CLAIMED |
lastUpdatedAt | number | Unix timestamp of last status update |
claimTransactionHash | string or null | Claim transaction hash (populated after claim) |
claimBlockNumber | number or null | Block number of the claim transaction |
claimTimestamp | number or null | Unix timestamp of the claim |
GET /claim-proof
Generate a merkle proof for claiming a bridge transaction. This endpoint proxies to the source chain’s AggKit Bridge Service to retrieve the proof data needed to submit a claim on the destination chain.
Parameters
| Parameter | Type | Required | Description |
|---|
sourceNetworkId | integer | Yes | Source chain network ID |
depositCount | integer | Yes | Deposit counter from bridge event |
leafIndex | integer | Yes | Leaf index in merkle tree |
Example request
curl "https://bridge-hub.example.com/claim-proof?sourceNetworkId=1&depositCount=42&leafIndex=42"
Example response
{
"proof_local_exit_root": ["0x...", "0x..."],
"proof_rollup_exit_root": ["0x...", "0x..."],
"l1_info_tree_leaf": {
"l1InfoTreeIndex": 100,
"rer": "0x...",
"mer": "0x...",
"innerBlock": 19500000,
"innerTimestamp": 1710000000
},
"bridge_tx_metadata": "0x..."
}
Response fields
| Field | Type | Description |
|---|
proof_local_exit_root | string[] | Merkle proof siblings for the local exit root |
proof_rollup_exit_root | string[] | Merkle proof siblings for the rollup exit root |
l1_info_tree_leaf | object | L1 info tree leaf data used in claim verification |
bridge_tx_metadata | string | Encoded metadata for the bridge transaction |
GET /token-mappings
Get token address mappings between networks. Returns the relationship between original token addresses and their wrapped counterparts on destination networks.
Example request
curl "https://bridge-hub.example.com/token-mappings"
Example response
{
"data": [
{
"originNetwork": 1,
"originTokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"wrappedTokenAddress": "0x37eAA0eF3549a5bB7D431be78a3D99BD6fd6b57D",
"destinationNetwork": 2442
}
]
}
Example request
curl "https://bridge-hub.example.com/token-metadata"
Example response
{
"data": [
{
"tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"networkId": 1,
"name": "USD Coin",
"symbol": "USDC",
"decimals": 6
}
]
}
GET /health-check
Returns the service health status.
Example request
curl "https://bridge-hub.example.com/health-check"
Example response
{
"status": "success",
"data": {
"status": "success",
"message": "All services are working correctly"
}
}
/transactions endpoint.
- Make an initial request with an optional
limit parameter.
- If more results exist, the response includes a
nextStartAfterCursor value.
- Pass that value as the
startAfter parameter in your next request to retrieve the following page.
# First page
curl "https://bridge-hub.example.com/transactions?limit=50"
# Next page (using the cursor from the previous response)
curl "https://bridge-hub.example.com/transactions?limit=50&startAfter=eyJsYXN0SWQiOiJ0eC0wMDUwIn0="
- Stable results. Concurrent inserts or updates do not cause skipped or duplicated entries between pages.
- Consistent performance. Fetching page 1,000 is as fast as fetching page 1, since the database seeks directly to the cursor position.
- No deep pagination issues. There is no growing cost as you move further through the result set.
Error handling
The API uses standard HTTP status codes and returns structured error responses.
Status codes
| Code | Meaning | Description |
|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Invalid or missing query parameters |
| 404 | Not Found | Requested resource does not exist |
| 500 | Server Error | An unexpected error occurred on the server |
{
"status": "error",
"message": "Invalid query parameter: status must be one of BRIDGED, READY_TO_CLAIM, CLAIMED"
}
500 response, retry the request after a short delay. For persistent errors, check the /health-check endpoint to verify service availability.
