Order tracking

How to follow an order to completion with GET /v1/orders/{provider}/{id} or sdk.watch(), and what id to use per provider.

The endpoint#

Text

GET /v1/orders/{provider}/{id}
→ { provider, id, state, srcTxHash?, dstTxHash? }

provider is the provider field of the quote you executed. state is one of:

State	Meaning	Final?
`pending`	In flight — source confirmed, destination not yet delivered.	no
`filled`	Delivered to the recipient.	yes
`refunded`	Not filled; funds returned to the sender.	yes
`failed`	Failed. Check the source transaction.	yes
`unknown`	The provider cannot tell (yet), or does not track this kind of order.	no

Which id to pass#

Provider	`id`
`relay`	Source (deposit) transaction hash, or Relay's request id
`debridge`	Source transaction hash (EVM hash or Solana signature), or a DLN order id
`lifi`	Source transaction hash
`jupiter`, `zerox`	Anything — always `unknown`; see below

Same-chain swaps (Jupiter, 0x) settle in the transaction itself, so there is nothing to track off-chain. Confirm the transaction on chain (waitForTransactionReceipt on EVM, confirmTransaction / getSignatureStatuses on Solana). If it succeeded, the swap is done.

Polling with the SDK#

TypeScript

for await (const s of lh.watch("relay", srcTxHash, { intervalMs: 3000, timeoutMs: 30 * 60_000 })) {
  render(s.state, s.dstTxHash);
}

watch() yields only when the state changes and stops at filled, refunded or failed, or after timeoutMs (30 minutes by default).

Tips#

Right after broadcasting, providers may answer unknown (or pending) until they index the source transaction. Keep polling; do not treat unknown as failure.
Link the user to the explorer: every chain in GET /v1/chains has an explorerTx prefix.
Status calls go to the provider, so they can fail with PROVIDER_ERROR, PROVIDER_TIMEOUT or RATE_LIMITED. Retry with backoff.

Coming soon

webhooks (order.created, order.fulfilled, order.refunded…) signed with HMAC so you do not have to poll, and order history by address.