get_htlc
Retrieve per-leg HTLC settlement state for a trade: lock status, chain, timelock, and preimage reveal. Returns an array of HTLC legs; empty array means no HTLC recorded.
Instructions
Real-time trade observability — per-leg HTLC settlement state for a trade: which legs are locked, on which chain, with what timelock, and whether the preimage has been revealed. Read-only, safe to call at any time.
Returns an ARRAY of HTLC legs (one entry per locked leg, typically the initiator leg and the counterparty leg). An empty array means no HTLC has been recorded for this tradeId yet (or the tradeId does not exist) — treat empty as "nothing locked", not an error.
USE WHEN: showing trade/settlement status to the user, deciding the next settlement action (lock / claim / refund), polling for the counterparty leg, or rebuilding state after losing context. DO NOT USE WHEN: you need RFQ/quote status (this is settlement-leg state only) — use list_my_trades or list_open_rfqs instead.
INTERPRETING THE RESULT (per leg): role = INITIATOR | COUNTERPARTY; status = leg lifecycle; chainType = evm | bitcoin | sui; timelock = unix expiry of that leg; preimage non-null on a claimed initiator leg. Both legs ACTIVE = swap can complete (claim path). Initiator leg past timelock with counterparty leg absent = refund path.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tradeId | Yes | Trade ID to query HTLC legs for. An unknown ID returns an empty array, not an error. |