> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Bridge Hub REST API: endpoints, parameters, and response formats for querying bridge transactions.

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

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

```bash theme={null}
curl "https://bridge-hub.example.com/transactions?status=READY_TO_CLAIM&limit=2"
```

### Example response

```json theme={null}
{
  "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

```bash theme={null}
curl "https://bridge-hub.example.com/claim-proof?sourceNetworkId=1&depositCount=42&leafIndex=42"
```

### Example response

```json theme={null}
{
  "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

```bash theme={null}
curl "https://bridge-hub.example.com/token-mappings"
```

### Example response

```json theme={null}
{
  "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

```bash theme={null}
curl "https://bridge-hub.example.com/token-metadata"
```

### Example response

```json theme={null}
{
  "data": [
    {
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "networkId": 1,
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6
    }
  ]
}
```

## GET /health-check

Returns the service health status.

### Example request

```bash theme={null}
curl "https://bridge-hub.example.com/health-check"
```

### Example response

```json theme={null}
{
  "status": "success",
  "data": {
    "status": "success",
    "message": "All services are working correctly"
  }
}
```

## Pagination

The Bridge Hub API uses cursor-based pagination for the `/transactions` endpoint.

1. Make an initial request with an optional `limit` parameter.
2. If more results exist, the response includes a `nextStartAfterCursor` value.
3. Pass that value as the `startAfter` parameter in your next request to retrieve the following page.

```bash theme={null}
# 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:

```json theme={null}
{
  "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.