Bridge Transaction Status

After submitting a crosschain transaction via the Route or Bundle API, the bridge delivery is asynchronous. Enso provides protocol-specific status endpoints to track delivery progress on the destination chain.

Quick Reference

Bridge Protocol	Status Endpoint	Status Field
Stargate	`GET /api/v1/stargate/bridge/check`	`status`
CCIP	`GET /api/v1/ccip/bridge/check`	`status`
Relay	`GET /api/v1/relay/bridge/check`	`status`

All endpoints accept two query parameters:

chainId — source chain ID (number)
txHash — source transaction hash (string, 0x + 64 hex characters)

Rate limit: All bridge status endpoints are limited to 1 request per 10 seconds per API key (or per IP if unauthenticated). Exceeding this returns HTTP 429. Enforce a minimum 10-second interval between polls.

Status Lifecycle

Bridge transactions progress through a unified status lifecycle:

pending — Source transaction confirmed, bridge protocol hasn’t picked it up yet
inflight — Bridge protocol is processing the cross-chain message
delivered — Tokens and callbacks successfully delivered on the destination chain
failed — Bridge or callback execution failed (check error and ensoDestinationEvent for details)
unknown — Status could not be determined

Identifying the Bridge Protocol

Route API
Bundle API

When using the Route API, the response tells you which bridge was automatically selected:

Check the route array for the hop where action === "bridge" — its protocol field contains the bridge protocol
The bridgingEstimates array provides the protocol name and estimated delivery time

const route = await ensoClient.getRouteData({
  fromAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  chainId: 1,
  destinationChainId: 8453,
  tokenIn: ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
  tokenOut: ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
  amountIn: ["1000000000"],
  slippage: "300",
  routingStrategy: "delegate",
});

// Extract bridge protocol from the route hops
const bridgeHop = route.route.find((hop) => hop.action === "bridge");
const bridgeProtocol = bridgeHop?.protocol; // "stargate" | "ccip" | "relay"

// Get estimated delivery time (useful for initial polling delay)
const estimatedSeconds = route.bridgingEstimates?.[0]?.estimatedSeconds;

When using the Bundle API, you already know the bridge protocol — it’s the protocol field you specified in your bridge action:

const bundle = await client.getBundleData(
  { chainId: 1, fromAddress: "0x...", routingStrategy: "router" },
  [
    {
      protocol: "stargate", // <-- This is your bridge protocol
      action: "bridge",
      args: {
        primaryAddress: "0x...",
        destinationChainId: 42161,
        tokenIn: "0x...",
        amountIn: "1000000000",
        receiver: "0x...",
      },
    },
  ]
);

Status Check Endpoints

Stargate

GET /api/v1/stargate/bridge/check — Check Stargate (LayerZero) bridge transaction status.

const API_KEY = process.env.ENSO_API_KEY;
const chainId = 1; // Source chain
const txHash = "0x80f1faf..."; // Source transaction hash

const response = await fetch(
  `https://api.enso.finance/api/v1/stargate/bridge/check?chainId=${chainId}&txHash=${txHash}`,
  {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }
);
const data = await response.json();

console.log(data.status); // "pending" | "inflight" | "delivered" | "failed" | "unknown"
console.log(data.destinationTxHash); // Destination tx hash when delivered

Response fields:

Field	Type	Description
`status`	`string`	`pending` / `inflight` / `delivered` / `failed` / `unknown`
`sourceChainId`	`number`	Source chain ID
`sourceTxHash`	`string`	Source transaction hash
`destinationChainId`	`number?`	Destination chain ID (when known)
`destinationTxHash`	`string?`	Destination tx hash (when delivered)
`isMultiBridge`	`boolean?`	`true` for multi-hop bridge transactions
`hops`	`array?`	Individual hop details for multi-bridge transactions
`layerZeroMessage`	`object?`	LayerZero message pathway and timing details
`ensoSourceEvent`	`object \| null`	Enso execution event on source chain
`ensoDestinationEvent`	`object \| null`	Enso callback execution event on destination
`ensoMetadata`	`object?`	Request metadata (tokenIn, tokenOut, amountIn)
`error`	`string?`	Error message if something went wrong

Multi-hop support: Stargate supports multi-hop transactions (up to 5 sequential bridges). When isMultiBridge is true, the hops array contains per-hop status tracking with individual sourceChainId, destinationChainId, status, and layerZeroMessage fields.

CCIP (Chainlink)

GET /api/v1/ccip/bridge/check — Check Chainlink CCIP bridge transaction status.

const API_KEY = process.env.ENSO_API_KEY;
const chainId = 56; // Source chain (e.g., BNB Chain)
const txHash = "0x80f1faf..."; // Source transaction hash

const response = await fetch(
  `https://api.enso.finance/api/v1/ccip/bridge/check?chainId=${chainId}&txHash=${txHash}`,
  {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }
);
const data = await response.json();

console.log(data.status); // "pending" | "inflight" | "delivered" | "failed" | "unknown"
console.log(data.sourceChainEstimatedTimeForFinalitySeconds); // Seconds until finality
console.log(data.destinationTxHash); // Destination tx hash when delivered

Response fields:

Field	Type	Description
`status`	`string`	`pending` / `inflight` / `delivered` / `failed` / `unknown`
`sourceChainId`	`number`	Source chain ID
`sourceTxHash`	`string`	Source transaction hash
`sourceChainIdFinality`	`number`	Required finality time in seconds for the source chain
`sourceChainEstimatedTimeForFinalitySeconds`	`number?`	Estimated seconds remaining until finality
`destinationChainId`	`number?`	Destination chain ID
`destinationTxHash`	`string?`	Destination tx hash (when delivered)
`ccipSendParamsDecoded`	`object?`	Decoded CCIP params: destination chain, token amounts with metadata, fees, gas limit
`ensoSourceEvent`	`object \| null`	Enso execution event on source chain
`ensoDestinationEvent`	`object \| null`	Enso callback execution event on destination
`error`	`string?`	Error message if something went wrong

Finality delay: CCIP waits for source chain finalization before delivering to the destination. This can range from sub-second (Avalanche) to 15-20 minutes (Ethereum, Optimism). Use sourceChainEstimatedTimeForFinalitySeconds to determine your initial polling delay. See Chainlink’s Finality By Blockchain for current times per chain.

Relay

GET /api/v1/relay/bridge/check — Check Relay bridge transaction status.

const API_KEY = process.env.ENSO_API_KEY;
const chainId = 1; // Source chain
const txHash = "0x94e5ea9..."; // Source transaction hash

const response = await fetch(
  `https://api.enso.finance/api/v1/relay/bridge/check?chainId=${chainId}&txHash=${txHash}`,
  {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }
);
const data = await response.json();

console.log(data.status); // "pending" | "inflight" | "delivered" | "failed" | "unknown"
console.log(data.destinationTxHash); // Destination tx hash when delivered

Response fields:

Field	Type	Description
`status`	`string`	`pending` / `inflight` / `delivered` / `failed` / `unknown`
`sourceChainId`	`number`	Source chain ID
`sourceTxHash`	`string`	Source transaction hash
`destinationChainId`	`number?`	Destination chain ID
`destinationTxHash`	`string?`	Destination tx hash (when delivered)
`relayRequest`	`object?`	Relay details: raw status, user, recipient, in/out txs, fee breakdown, timestamps
`ensoSourceEvent`	`object \| null`	Enso execution event on source chain
`ensoDestinationEvent`	`object \| null`	Enso callback execution event on destination
`error`	`string?`	Error message if something went wrong

Fee breakdown: relayRequest.fees provides a detailed breakdown in wei (gas, fixed, price), and relayRequest.feesUsd gives USD equivalents for each component.

Callback Execution Events

All three protocols include ensoSourceEvent and ensoDestinationEvent in their responses. These track whether Enso’s callback logic executed successfully on each chain.

Field	Value	Meaning
`ensoSourceEvent`	`null`	Source event not yet found
`ensoSourceEvent.success`	`true`	Source chain execution succeeded
`ensoSourceEvent.success`	`false`	Source chain execution failed — check `error` field
`ensoDestinationEvent`	`null`	Destination event not yet found (bridge still in transit)
`ensoDestinationEvent.success`	`true`	Destination callback executed successfully
`ensoDestinationEvent.success`	`false`	Destination callback failed — check `error` and `refundDetails`

When a callback fails, refundDetails provides information about where funds were sent:

{
  "refundDetails": {
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "1000000000",
    "recipient": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "isNative": false
  }
}

Resources

Crosschain Routing Guide — How to build crosschain transactions
Crosschain Bridges — Bridge protocol use cases and examples
Bridge Action Reference — Technical details on bridge parameters

Updated

Get Started

Examples

Reference

Quick Reference

Status Lifecycle

Identifying the Bridge Protocol

Status Check Endpoints

Callback Execution Events

Resources

Get Started

Examples

Reference

​Quick Reference

​Status Lifecycle

​Identifying the Bridge Protocol

​Status Check Endpoints

​Callback Execution Events

​Resources

Quick Reference

Status Lifecycle

Identifying the Bridge Protocol

Status Check Endpoints

Callback Execution Events

Resources