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)
ready_for_manual_execution — Funds are recoverable, but the destination action needs manual completion: claim an attested CCTP transfer or retry a stored Stargate payload
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" | "ready_for_manual_execution" | "unknown"
console.log(data.sourceChainEstimatedTimeForFinalitySeconds); // Seconds until finality
console.log(data.destinationTxHash); // Destination tx hash when delivered

curl "https://api.enso.finance/api/v1/ccip/bridge/check?chainId=56&txHash=0x80f1faf..." \
  -H "Authorization: Bearer $ENSO_API_KEY"

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.transferType); // "fast" | "standard" (executed mode)
console.log(data.destinationTxHash); // Destination tx hash when delivered
console.log(data.forward); // Forwarding Service state for HyperCore deposits

curl "https://api.enso.finance/api/v1/cctp/bridge/check?chainId=8453&txHash=0x4ac72089..." \
  -H "Authorization: Bearer $ENSO_API_KEY"

Response fields:

Field	Type	Description
`status`	`string`	`pending` / `inflight` / `delivered` / `failed` / `ready_for_manual_execution` / `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)
`transferType`	`"fast" \| "standard"?`	Reflects `finalityThresholdExecuted` (may differ from requested type)
`delayReason`	`string?`	Reason Circle reports for delayed processing, such as `insufficient_fee`
`forward`	`object?`	Forwarding Service state for transfers using a forwarding hook, including HyperCore deposits
`forward.state`	`string`	Raw forwarding state, such as `PENDING`, `COMPLETED`, or `FAILED`
`forward.errorCode`	`string?`	Forwarding failure code, such as `INSUFFICIENT_FEE`
`forward.errorDetails`	`string?`	Human-readable forwarding failure details
`forward.txHash`	`string?`	Destination-chain forward transaction hash
`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, transferType is set from finalityThresholdExecuted (≤ 1000 = fast, ≥ 2000 = standard). This is the actual path Circle took — it can differ from your requested protocolArgs.transferType if Fast allowance was exhausted or the source chain didn’t support Fast.

Forwarding Service transfers: For a CCTP transfer with a forwarding hook, including a HyperCore deposit, status is delivered only after forward.state is complete. A Circle message marked complete can remain inflight while forwarding is pending, or return failed with the forwarding error details. Enso verifies the destination MessageTransmitter nonce before returning a non-delivered result, so a consumed nonce is reported as delivered even if Iris still has a stale forwarding failure state.

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. Transfers with a pinned destinationCaller, including HyperCore forwarding transfers, return claimable: false: only Circle’s forwarder can complete them. Both endpoints are rate-limited to 1 request per 10 seconds.

Attested plain transfers: ready_for_manual_execution means Circle has attested a transfer without a forwarding hook, but the destination receiveMessage mint has not run yet. Use the claim endpoint above. Enso keeps delivered when it cannot read the destination nonce, so temporary RPC failures do not falsely report that action is required.

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
console.log(data.refundTxHash); // Origin-chain refund payout when refunded

curl "https://api.enso.finance/api/v1/relay/bridge/check?chainId=1&txHash=0x94e5ea9..." \
  -H "Authorization: Bearer $ENSO_API_KEY"

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)
`refundChainId`	`number?`	Origin chain where Relay paid a refund instead of delivering
`refundTxHash`	`string?`	Refund payout transaction; no `destinationTxHash` is returned for this case
`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" | "ready_for_manual_execution" | "unknown"
console.log(data.destinationTxHash); // Destination tx hash when delivered

curl "https://api.enso.finance/api/v1/stargate/bridge/check?chainId=1&txHash=0x80f1faf..." \
  -H "Authorization: Bearer $ENSO_API_KEY"

Response fields:

Field	Type	Description
`status`	`string`	`pending` / `inflight` / `delivered` / `failed` / `ready_for_manual_execution` / `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.

Stored LayerZero payloads: ready_for_manual_execution means a LayerZero message is blocked or stored and needs a retry or clearance before delivery can continue. It does not mean the funds are lost.

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. The destination side is Circle receiveMessage execution, including HyperCore forwarding when requested, so there is no Enso destination callback event.

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

Build

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

Quick Reference

Status Lifecycle

Identifying the Bridge Protocol

Status Check Endpoints

Callback Execution Events

Resources