swap_status

Instructions

Implementation Reference

• src/lib/swap.ts:270-308 (handler)

  Core handler function for swap_status. Takes a SwapClient, SwapStatusArgs (swap_handle, optional max_wait_seconds), and a Sleep function. Calls client.getRFQ to fetch the RFQ, handles forbidden/not-found via uniform error contract, then polls for bids (pollForQuotes) if the RFQ is open, or fetches quotes directly if closed. Selects the best bid and returns outcome with swap_handle, status, best_bid, bids_seen, still_open, and next guidance.

  export async function runSwapStatus(
    client: SwapClient, args: SwapStatusArgs, sleep: Sleep,
  ): Promise<ToolContent> {
    let rfq: SwapRfq | null;
    try {
      rfq = await client.getRFQ(args.swap_handle);
    } catch (err) {
      // Uniform not-found contract (same as runSwapExecute): a forbidden/unauthorized
      // RFQ (exists but caller is not a participant) must NOT be distinguishable from
      // a non-existent one, or swap_handle becomes an existence/participant oracle.
      const msg = err instanceof Error ? err.message : String(err);
      if (/forbidden|not a participant|unauthor|\b401\b|\b403\b/i.test(msg)) {
        return okContent({ outcome: 'SWAP_NOT_FOUND', swap_handle: args.swap_handle,
          next: 'Verify the swap_handle, or open a fresh swap with swap_quote.' });
      }
      throw err;
    }
    if (!rfq) {
      return okContent({ outcome: 'SWAP_NOT_FOUND', swap_handle: args.swap_handle,
        next: 'Verify the swap_handle, or open a fresh swap with swap_quote.' });
    }
    const open = RFQ_OPEN_STATES.has(rfq.status);
    const quotes = open
      ? await pollForQuotes(client, rfq.id, rfq.side, rfq.amount, args.max_wait_seconds ?? 15, sleep)
      : await client.getQuotes(rfq.id);
    const best = selectBestBid(quotes, rfq.side, rfq.amount);
    return okContent({
      swap_handle: rfq.id,
      status: best ? 'QUOTED' : 'OPEN',
      rfq_status: rfq.status,
      best_bid: bidView(best),
      bids_seen: quotes.length,
      still_open: open,
      next: best
        ? 'swap_execute with this swap_handle + your limit_price (or best_bid.quote_id).'
        : open ? 'Still waiting on bids. Call swap_status again, or swap_cancel.'
               : 'This swap is closed. Open a fresh one with swap_quote.',
    });
  }

• src/lib/swap.ts:268-268 (schema)

  TypeScript interface defining the input arguments for swap_status: swap_handle (string, required) and max_wait_seconds (number, optional).

  export interface SwapStatusArgs { swap_handle: string; max_wait_seconds?: number; }

• src/index.ts:356-371 (registration)

  MCP server tool registration for 'swap_status'. Registers the tool with a description, Zod schema for swap_handle (string) and max_wait_seconds (optional number), and wraps the handler calling runSwapStatus(swapClient, a, realSleep).

  // ─── swap_status ─────────────────────────────────────────────
  server.tool(
    'swap_status',
    [
      'Re-poll an open swap by its swap_handle — returns the current best sealed bid + how many bids are in. Read-only, stateless: the primary way to resume a swap after losing context (only the swap_handle is needed).',
      '',
      'USE WHEN: letting maker competition build before executing, or rebuilding an in-flight swap after a context reset. DO NOT USE WHEN: you need settlement-leg detail (use get_htlc) or your trade history (use list_my_trades).',
      '',
      'PARAM NOTES: returns best_bid (or null), bids_seen, still_open and rfq_status. When best_bid is present, swap_execute with the same limit_price (or best_bid.quote_id) to take it.',
    ].join('\n'),
    {
      swap_handle: z.string().describe('The swap_handle returned by swap_quote (the RFQ id).'),
      max_wait_seconds: z.number().optional().describe('Bounded wait for new bids this call. Default 15, capped 25.'),
    },
    wrapTool(async (a) => runSwapStatus(swapClient, a, realSleep)),
  );

• src/lib/swap.ts:89-102 (helper)

  pollForQuotes helper used by runSwapStatus. Polls client.getQuotes at 2.5s intervals (capped at 25s max) until an eligible bid is found or the wait window elapses. Returns all quotes.

  export async function pollForQuotes(
    client: SwapClient, rfqId: string, side: Side, requestedAmount: string,
    maxWaitSeconds: number, sleep: Sleep,
  ): Promise<SwapQuote[]> {
    const capped = Math.max(0, Math.min(MAX_WAIT_CAP_S, Math.floor(maxWaitSeconds || 0)));
    const iterations = Math.max(1, Math.ceil((capped * 1000) / POLL_INTERVAL_MS) + 1);
    let quotes: SwapQuote[] = [];
    for (let i = 0; i < iterations; i++) {
      quotes = await client.getQuotes(rfqId);
      if (selectBestBid(quotes, side, requestedAmount)) return quotes;
      if (i < iterations - 1) await sleep(POLL_INTERVAL_MS);
    }
    return quotes;
  }