Skip to main content

API Base URL

All Bridge Service endpoints follow this structure:

Health & Status

GET / and GET /health - Service Health Check

Both paths return the same payload. Example Request:
Response:
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
  • api_revision: Integer counter bumped whenever the response shape of any bridge service endpoint changes in a client-visible way. Starts at 1 and is independent of version. Always present, regardless of status. Use it to gate client code paths that depend on a specific response shape.

GET /sync-status - Component Synchronization Status

Example Request:
Response:

Bridge Transaction Queries

GET /bridges - Query Bridge Transactions

Parameters: Example Request Patterns:
Response Structure:
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
  • block_finalized: Whether the block carrying this bridge is finalized and can no longer be reorged. See Block finality.

Claim Tracking

GET /claims - Query Claim Transactions

Key Parameters: Example Usage:
Response:
Claim entries carry block_finalized with the same semantics as /bridges. See Block finality.

Block finality

Every response tied to an on-chain block carries an optional block_finalized field so clients know whether the data can still be reorged out from under them. Values:
  • true: The block that produced this item is finalized on its chain; the item cannot be reorged.
  • false: The block is not finalized yet; the item may still be replaced by a reorg.
  • Omitted (field absent): Finality is unknown. Treat it as not finalized.
Finality is reported by the syncer that served the data. It is not computed by comparing block numbers against the chain’s finalized head, because a stored block can be reorged and replaced by a different block at the same height. The response reflects the block hash the item was indexed with: if that block is no longer the one on the canonical chain at that height, the field is omitted. Endpoints that carry block_finalized: Use this field to decide whether to show a transaction as confirmed, delay dependent actions, or wait before caching a result.

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: Example Request:
Response Structure:

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.
Response:

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.

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: Example Requests:
Response:
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: Example Requests:
Response:
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:

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

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: Example Error Response: