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
CCIP	`GET /api/v1/ccip/bridge/check`	`status`
CCTP	`GET /api/v1/cctp/bridge/check`	`status`
Relay	`GET /api/v1/relay/bridge/check`	`status`
Stargate	`GET /api/v1/stargate/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" | "cctp"

// 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

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.

CCTP (Circle)

GET /api/v1/cctp/bridge/check — Check Circle CCTP v2 bridge transaction status.

const API_KEY = process.env.ENSO_API_KEY;
const chainId = 8453; // Source chain (e.g., Base)
const txHash = "0x4ac72089..."; // Source transaction hash

const response = await fetch(
`https://api.enso.finance/api/v1/cctp/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.cctpTransferType); // "fast" | "standard" (executed mode)
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 (resolved from CCTP domain)
`destinationTxHash`	`string?`	Destination tx hash (when minted)
`cctpTransferType`	`"fast" \| "standard"?`	Reflects `finalityThresholdExecuted` (may differ from requested type)
`depositForBurn`	`object?`	Raw `depositForBurn` params — present only when the source call had no hookData
`depositForBurnDecoded`	`object?`	Decoded `depositForBurn`: token metadata, chain IDs, `maxFee` vs `feeExecuted`, finality info
`depositForBurnWithHook`	`object?`	Raw `depositForBurnWithHook` params — present only when hookData is non-empty
`depositForBurnWithHookDecoded`	`object?`	Decoded form including `hookData.forwardingService` (true when bytes match Circle’s `cctp-forward` magic)
`ensoSourceEvent`	`object \| null`	Enso execution event on source chain
`error`	`string?`	Error message if the check failed

Fast vs Standard detection: After the burn is attested, cctpTransferType is set from finalityThresholdExecuted (≤ 1000 = fast, ≥ 2000 = standard). This is the actual path Circle took — it can differ from your requested cctpTransferType if Fast allowance was exhausted or the source chain didn’t support Fast.

Manual claim: If a transfer gets stuck, call GET /api/v1/cctp/bridge/claim to get a ready-to-submit receiveMessage transaction for the destination chain. Both endpoints are rate-limited to 1 request per 10 seconds.

Upstream source: this endpoint is backed by Circle’s Iris GET /v2/messages/{sourceDomainId} — Enso wraps it with on-chain enrichment (token metadata, chain IDs decoded from CCTP domains, executed-fee vs requested-fee). See Circle’s supported blockchains matrix for which chains support Fast Transfer.

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.

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.

Callback Execution Events

Stargate, CCIP, and Relay include both ensoSourceEvent and ensoDestinationEvent in their responses — these track whether Enso’s callback logic executed successfully on each chain. CCTP returns only ensoSourceEvent (no Enso callback runs on the destination because CCTP doesn’t support post-bridge actions — the mint is a pure Circle receiveMessage).

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

Documentation Index

​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