get_htlc

Instructions

Implementation Reference

• src/index.ts:125-144 (registration)

  Registration of the 'get_htlc' tool via server.tool(). Registers the name, description, schema (tradeId: z.string()), and the handler.

  server.tool(
    'get_htlc',
    [
      '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.',
    ].join('\n'),
    {
      tradeId: z.string().describe('Trade ID to query HTLC legs for. An unknown ID returns an empty array, not an error.'),
    },
    wrapTool(async ({ tradeId }) => {
      const result = await hl.getHTLCs(tradeId);
      return okContent(result);
    }),
  );

• src/index.ts:137-139 (schema)

  Input schema for get_htlc: a single 'tradeId' string parameter described as 'Trade ID to query HTLC legs for.'

  {
    tradeId: z.string().describe('Trade ID to query HTLC legs for. An unknown ID returns an empty array, not an error.'),
  },

• src/index.ts:140-143 (handler)

  Handler function for get_htlc. Calls hl.getHTLCs(tradeId) via the @hashlock-tech/sdk and wraps the result using okContent().

  wrapTool(async ({ tradeId }) => {
    const result = await hl.getHTLCs(tradeId);
    return okContent(result);
  }),

• src/lib/result.ts:8-10 (helper)

  okContent helper used by the handler to serialize the result as JSON text content.

  export function okContent(value: unknown): ToolContent {
    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
  }

• src/lib/errors.ts:85-95 (helper)

  wrapTool helper used to wrap the handler, converting thrown errors into structured error envelopes.

  export function wrapTool<A extends unknown[]>(
    handler: (...args: A) => Promise<ToolContent>,
  ): (...args: A) => Promise<ToolContent> {
    return async (...args: A) => {
      try {
        return await handler(...args);
      } catch (err) {
        return toErrorEnvelope(err);
      }
    };
  }