AgentPay-mcp

Instructions

Implementation Reference

• src/tools/session.ts:562-657 (handler)

  The handler function for x402_session_status, which either lists all active sessions or provides detailed info for a specific session_id.

  export async function handleX402SessionStatus(
    input: X402SessionStatusInput
  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
    try {
      const now = Math.floor(Date.now() / 1000);
  
      if (input.session_id) {
        // Detailed view for a specific session
        const lookup = lookupSession(input.session_id);
  
        if (!lookup.found) {
          return {
            content: [
              textContent(
                `❌ Session not found: "${input.session_id}"\n\n` +
                `Use x402_session_status (no arguments) to list active sessions.`
              ),
            ],
            isError: true,
          };
        }
  
        const { session, expired } = lookup;
        const ttlRemaining = Math.max(0, session.expiresAt - now);
        const decoded = decodeSessionToken(session.sessionToken);
  
        let out = expired
          ? `⏰ **Session Expired**\n\n`
          : `🔐 **Session Details**\n\n`;
  
        out += `  Session ID:    ${session.sessionId}\n`;
        if (session.label) out += `  Label:         ${session.label}\n`;
        out += `  Status:        ${expired ? '❌ Expired' : '✅ Active'}\n`;
        out += `  Endpoint:      ${session.endpoint}\n`;
        out += `  Scope:         ${session.scope}\n`;
        out += `  Wallet:        ${session.walletAddress}\n\n`;
  
        out += `⏱️  **Timing**\n`;
        out += `  Created:       ${new Date(session.createdAt * 1000).toISOString()}\n`;
        out += `  Expires:       ${new Date(session.expiresAt * 1000).toISOString()}\n`;
        if (!expired) out += `  TTL Remaining: ${formatTtl(ttlRemaining)}\n`;
        out += `  Last Used:     ${session.lastUsedAt > 0 ? new Date(session.lastUsedAt * 1000).toISOString() : 'Never'}\n`;
        out += `  Call Count:    ${session.callCount}\n\n`;
  
        out += `💳 **Session Payment**\n`;
        out += `  TX Hash:       ${session.paymentTxHash}\n`;
        out += `  Amount:        ${session.paymentAmount} (base units)\n`;
        out += `  Recipient:     ${session.paymentRecipient}\n`;
        out += `  Token:         ${session.paymentToken === '0x0000000000000000000000000000000000000000' ? 'ETH (native)' : session.paymentToken}\n\n`;
  
        if (decoded) {
          out += `🔏 **Token Info**\n`;
          out += `  Protocol:      ${decoded.payload.version}\n`;
          out += `  Signature:     ${decoded.signature.slice(0, 20)}...${decoded.signature.slice(-8)}\n`;
        }
  
        return { content: [textContent(out)] };
      }
  
      // List all active sessions
      const active = listActiveSessions();
  
      if (active.length === 0) {
        return {
          content: [
            textContent(
              `📋 **Active Sessions**\n\n` +
              `No active sessions. Use x402_session_start to establish a session.\n\n` +
              `ℹ️  Sessions are stored in-process and survive for their configured TTL.\n` +
              `   Default TTL: 3600 seconds (1 hour). Set SESSION_TTL_SECONDS to override.`
            ),
          ],
        };
      }
  
      let out = `📋 **Active x402 Sessions** (${active.length})\n\n`;
  
      for (const session of active) {
        const ttlRemaining = Math.max(0, session.expiresAt - now);
        const ttlBar = ttlProgressBar(ttlRemaining, session.expiresAt - session.createdAt);
  
        out += `─────────────────────────────────────\n`;
        out += `  ID:       ${session.sessionId}\n`;
        if (session.label) out += `  Label:    ${session.label}\n`;
        out += `  Endpoint: ${session.endpoint}\n`;
        out += `  Scope:    ${session.scope}\n`;
        out += `  TTL:      ${formatTtl(ttlRemaining)} ${ttlBar}\n`;
        out += `  Calls:    ${session.callCount}\n`;
        out += `  Payment:  ${session.paymentAmount} base units → TX ${session.paymentTxHash.slice(0, 18)}...\n`;
        out += '\n';
      }
  
      out += `\nUse x402_session_fetch with a session_id to make free calls within a session.\n`;
      out += `Use x402_session_status with session_id="..." for full session details.`;
  
      return { content: [textContent(out)] };

• src/tools/session.ts:531-539 (schema)

  The Zod schema defining the input for the x402_session_status tool.

  export const X402SessionStatusSchema = z.object({
    session_id: z
      .string()
      .optional()
      .describe(
        'Specific session ID to inspect. ' +
        'Omit to list all active sessions.'
      ),
  });

• src/tools/session.ts:543-560 (registration)

  The tool object definition including the name, description, and input schema for x402_session_status.

  export const x402SessionStatusTool = {
    name: 'x402_session_status',
    description:
      'Check the status of x402 V2 payment sessions. ' +
      'Without arguments, lists all active sessions with TTL remaining. ' +
      'With a session_id, shows full details for that session including ' +
      'call count, payment info, and the signed session token.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        session_id: {
          type: 'string',
          description: 'Specific session ID to inspect. Omit to list all active sessions.',
        },
      },
      required: [],
    },
  };