API Reference - Polygon Developer Docs

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:

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

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

Generates the cryptographic proofs required to claim bridged assets. Pass the entire proof object returned to your claim contract function. 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
    }
  }
}

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"

Fee Estimation

Two read-only endpoints estimate what a bridging transaction costs, without sending it. Both are derived from recently indexed on-chain claims and bridges, priced at the live gas price of the network the transaction runs on. The estimate is fail-closed: when it cannot be computed honestly, the endpoint returns an HTTP error, never a default or partial value. Both endpoints are routed through the aggkit proxy the same way as every other /bridge/v1/* route: the proxy forwards the request to the bridge service of the network selected by network_id. Every wei value in a response is a decimal string, because wei exceeds float64 precision. The estimates cover execution gas × gas price only. Chains served by these endpoints do not charge senders an L1 data fee, so the result reflects what the user or sponsor pays.

`GET /claim-fee-estimate` - Estimate claim cost

Estimates the cost of claimAsset on a destination network. Use it to quote sponsored claims (a sponsor pays the claim on behalf of the user) or price a claim in a bridging UI. Parameters:

Parameter	Type	Required	Description
`network_id`	integer	✅	Destination network the claim runs on: `0` for L1, or the instance’s L2 network id.
`origin_network`	integer	✅	Network the token is bridged from.
`origin_token_address`	string	✅	Token address on the origin network. `0x0000...0000` means the origin’s native gas token.

Example Requests:

# Claim on L1 of the origin's native gas token
curl "http://localhost:5577/bridge/v1/claim-fee-estimate?network_id=0&origin_network=0&origin_token_address=0x0000000000000000000000000000000000000000"

# Claim on L2 (network_id = 1) of an L1 ERC20
curl "http://localhost:5577/bridge/v1/claim-fee-estimate?network_id=1&origin_network=0&origin_token_address=0x3355789c8b6b7e4d3c2f1a0b9e8d7c6b5a49ff21"

Response:

{
  "network_id": 1,
  "origin_network": 0,
  "origin_token_address": "0x3355789c8b6b7e4d3c2f1a0b9e8d7c6b5a49ff21",
  "token_class": "wrapped_erc20",
  "wrapper_exists": true,
  "applicable": "repeat_claim",
  "gas_price": {
    "base_fee": "15000000000",
    "priority_fee": "2000000000",
    "gas_price": "17000000000",
    "block_number": 123
  },
  "first_claim": null,
  "repeat_claim": {
    "gas_units": 110000,
    "cost": "1870000000000000",
    "sample_count": 37,
    "source": "class"
  },
  "unavailable": {
    "first_claim": "wrapper already deployed; the first-claim estimate does not apply"
  },
  "computed_at": 1760000000
}

Response Fields:

token_class classifies the token from the destination’s point of view:
- origin_native_erc20 when the token already lives on the destination network (origin_network equals the destination).
- gas_token when the token is the origin’s native gas token (0x0) or the destination’s own custom gas token.
- wrapped_erc20 otherwise.
wrapper_exists reports whether the destination already holds a deployed wrapper for the token. It is null when no wrapper applies (origin_native_erc20 and gas_token never deploy one). false means the next claim deploys the wrapper.
The first claim of a token deploys its wrapper and later claims do not, so the two scenarios get separate estimates. applicable names which one this request resolves to, chosen from wrapper_exists:
- first_claim: wrapper deployment estimate.
- repeat_claim: estimate after the wrapper exists.
Exactly one of first_claim / repeat_claim is populated. The other is null, and unavailable holds the reason, keyed by the non-applicable estimate’s name. The applicable estimate is never listed in unavailable: if it cannot be computed, the endpoint returns 503 instead of this body.
gas_price is the snapshot the estimate is priced with. base_fee and priority_fee are null on chains without EIP-1559, where gas_price comes from eth_gasPrice. gas_price itself is always present. All three are decimal strings in wei.
computed_at is the Unix timestamp (seconds) when the estimate was computed.

`GET /bridge-fee-estimate` - Estimate bridge cost

Estimates the cost of bridgeAsset out of an origin network. Parameters:

Parameter	Type	Required	Description
`network_id`	integer	✅	Origin network the bridge transaction runs on: `0` for L1, or the instance’s L2 network id.
`token_address`	string	✅	Token address on the origin network. `0x0000...0000` means the native gas token.

Example Requests:

# Bridge out of L1: the native gas token
curl "http://localhost:5577/bridge/v1/bridge-fee-estimate?network_id=0&token_address=0x0000000000000000000000000000000000000000"

# Bridge out of L2 (network_id = 1): an ERC20 native to the L2
curl "http://localhost:5577/bridge/v1/bridge-fee-estimate?network_id=1&token_address=0x3355789c8b6b7e4d3c2f1a0b9e8d7c6b5a49ff21"

Response:

{
  "network_id": 0,
  "token_address": "0x0000000000000000000000000000000000000000",
  "mechanism": "native",
  "gas_price": {
    "base_fee": "15000000000",
    "priority_fee": "2000000000",
    "gas_price": "17000000000",
    "block_number": 123
  },
  "estimate": {
    "gas_units": 65000,
    "cost": "1105000000000000",
    "sample_count": 42,
    "source": "mechanism"
  },
  "computed_at": 1760000000
}

The bridge estimate is coarser than the claim one: it is per bridging mechanism, with no per-token breakdown. mechanism is derived on-chain from the origin network’s bridge contract and is one of:

native — the network’s native gas token, bridged via msg.value (requested with token_address=0x0).
erc20_lock — an ERC20 native to the origin network, locked in the bridge contract.
wrapped_burn — a wrapped token burned on its origin network.

On success estimate is always populated with source: "mechanism". There is no nullable field here: either the response holds an estimate, or the endpoint returns 503.

The estimate object

first_claim, repeat_claim, and the bridge endpoint’s estimate share the same shape:

Field	Type	Description
`gas_units`	uint64	p90 `gasUsed` of observed transactions in the bucket, or the maximum when the bucket holds fewer than 10 samples. This is observed usage, not a gas limit: when sending the transaction, set a gas limit with headroom over it.
`cost`	string (wei)	`gas_units × gas_price.gas_price`, in the native gas token of the network where the transaction runs.
`sample_count`	int	How many observed transactions the bucket holds.
`source`	string	The bucket granularity: `token` (per-token repeat-claim), `class` (token-class fallback), or `mechanism` (bridge side).

How estimates are computed

The estimator pages through the latest 200 indexed claims or bridges on the network, keeps only successful transactions sent directly to the bridge contract whose receipt holds exactly one ClaimEvent or BridgeEvent, and buckets them. Claims are bucketed into first claims (receipts that deploy a wrapper) and repeat claims, with repeat claims keyed per token and by token class. Bridges are bucketed by mechanism only. The reported statistic is p90 of gasUsed, or the maximum when a bucket has fewer than 10 samples. The repeat-claim estimate uses the per-token bucket when the token has at least 3 samples, otherwise its token-class bucket.

Gas price is read live and cached for 5 seconds: the latest block baseFee plus eth_maxPriorityFeePerGas on EIP-1559 chains, eth_gasPrice on chains without a base fee. Gas-unit statistics are cached for 60 seconds. Token facts (wrapper existence, token mappings, the network’s gas-token identity) are read on-chain from the bridge contract and reused for 30 seconds per token on the request path. Message leaves (claimMessage / bridgeMessage) and batched multi-event transactions are not sampled, so these estimates cover only direct, single-event claims and bridges.

Fee estimation errors

Status	Meaning
`400`	Invalid input: missing or malformed parameter, a `network_id` that is neither `0` nor the instance’s L2 network id, or (claim only) `origin_network` equal to the destination network together with `origin_token_address` `0x0`.
`503`	Estimate genuinely unavailable: no estimator is configured for the network, no sample exists for the applicable bucket (for example, a young chain that has not seen a first claim of this token class), a required RPC call failed, or the relevant syncer is halted.
`500`	Unexpected failure.

No server-side margin is added. cost is exactly gas_units × gas_price at quote time. Callers should buffer for gas-price movement between the quote and the transaction, and for gas-unit variance: gas_units is the observed usage of comparable transactions, not a cap on what any given transaction will use.

A bucket with no observed transactions returns 503 by design. Treat it as “no quote for this route” rather than as an outage.

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

​API Base URL

​Health & Status

​GET / - Service Health Check

​GET /sync-status - Component Synchronization Status

​Bridge Transaction Queries

​GET /bridges - Query Bridge Transactions

​Claim Tracking

​GET /claims - Query Claim Transactions

​Proof Generation

​GET /claim-proof - Generate Claim Proof

​Additional Utilities

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

​GET /token-mappings - Token Information

​Fee Estimation

​GET /claim-fee-estimate - Estimate claim cost

​GET /bridge-fee-estimate - Estimate bridge cost

​The estimate object

​How estimates are computed

​Fee estimation errors

​Error Handling

API Base URL

Health & Status

`GET /` - Service Health Check

`GET /sync-status` - Component Synchronization Status

Bridge Transaction Queries

`GET /bridges` - Query Bridge Transactions

Claim Tracking

`GET /claims` - Query Claim Transactions

Proof Generation

`GET /claim-proof` - Generate Claim Proof

Additional Utilities

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

`GET /token-mappings` - Token Information

Fee Estimation

`GET /claim-fee-estimate` - Estimate claim cost

`GET /bridge-fee-estimate` - Estimate bridge cost

The estimate object

How estimates are computed

Fee estimation errors

Error Handling