API Reference - Polygon Developer Docs

The Bridge Hub API exposes interactive OpenAPI documentation at the /docs endpoint. You can browse endpoints and test API calls directly in the browser.

The Bridge Hub API is a read-only REST API. All endpoints use the 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
    }
  ]
}

GET /token-metadata

Get token metadata including name, symbol, and decimals for tokens tracked by Bridge Hub.

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

Pagination

The Bridge Hub API uses cursor-based pagination for the /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="

Cursor-based pagination provides several benefits over offset-based approaches:

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

Error response format

All error responses follow a consistent structure:

{
  "status": "error",
  "message": "Invalid query parameter: status must be one of BRIDGED, READY_TO_CLAIM, CLAIMED"
}

Error messages describe the problem without exposing sensitive internal details. If you receive a 500 response, retry the request after a short delay. For persistent errors, check the /health-check endpoint to verify service availability.

​GET /transactions

​Parameters

​Example request

​Example response

​Response fields

​GET /claim-proof

​Parameters

​Example request

​Example response

​Response fields

​GET /token-mappings

​Example request

​Example response

​GET /token-metadata

​Example request

​Example response

​GET /health-check

​Example request

​Example response

​Pagination

​Error handling

​Status codes

​Error response format

GET /transactions

Parameters

Example request

Example response

Response fields

GET /claim-proof

Parameters

Example request

Example response

Response fields

GET /token-mappings

Example request

Example response

GET /token-metadata

Example request

Example response

GET /health-check

Example request

Example response

Pagination

Error handling

Status codes

Error response format