Guides

Transaction Lifecycle

How cross-chain transactions progress through multiple steps

Cross-chain transactions are not instantaneous. Each transaction goes through multiple steps and wait periods before completion.

Steps

A bridging transaction is broken down into a series of steps. Each step is one of:

Transaction — an on-chain transaction that needs to be submitted (by the caller or automatically by a relayer)
Wait — a wait period for on-chain confirmations or protocol finalization
Info — informational context (e.g. links or status messages)

Some bridges complete in seconds, others can take minutes, hours, or even days depending on the underlying protocol and chains involved.

The steps for a given bridge are known upfront — the Routes endpoint includes the expected steps for each route so you know what to expect before initiating. Once a transaction is in flight, the Activity endpoint provides detailed, real-time status for each step including progress, confirmations, and gas costs.

Transaction step statuses

Status	Meaning
`ready`	The transaction can be submitted now. Call Step Transaction to get the transaction data.
`not-ready`	A future transaction step that isn't actionable yet (e.g. waiting for a prior step to complete).
`auto`	The transaction will be submitted automatically by a relayer — no action required.
`done`	The transaction has been submitted and confirmed on-chain.

Wait step statuses

Status	Meaning
`not-started`	The wait period hasn't begun yet (a prior step needs to complete first).
`in-progress`	The wait period is active. Includes `startedAt` and `expectedDuration` fields.
`done`	The wait period is complete.

Progressing a transaction

When a transaction step has status ready, you can progress the bridge by calling the Step Transaction endpoint. This returns the transaction data (calldata, target address, value) that needs to be signed and submitted on-chain.

The flow is:

Poll the Activity endpoint to get the current steps
Find the step with transactionType: "ready"
Call POST /v1/get_step_transaction with the activity id, the step's action and provider, and the submitter address
Sign and submit the returned transaction on-chain
Continue polling activity until the bridge is complete

The response shape from Step Transaction varies by VM — EVM transactions return to, data, and value, while SVM transactions return serialized transaction data. See Step Transaction for the full response schema.

Polling with `nextCheckTimestamp`

Each activity item includes a nextCheckTimestamp field (unix milliseconds, or null). Use this to determine when to poll the Activity endpoint next.

If nextCheckTimestamp is in the future, there's no point polling before that time — the status won't have changed.
If nextCheckTimestamp is in the past or null, you can poll immediately.
Once all steps are done, nextCheckTimestamp will be null — the transaction is complete.

This avoids unnecessary API calls during long wait periods (e.g. the 7-day challenge period on optimistic rollups) while still ensuring you catch state changes promptly.

Wait Periods

Between transaction steps there are often wait periods. These can range from a few seconds for fast bridges to days for protocols that use optimistic verification (e.g. Optimism and Arbitrum native bridges have a 7 day challenge period).

Each in-progress wait step includes startedAt (unix ms) and expectedDuration (ms) so you can track progress or estimate completion time.