x402 MCP Server

Instructions

Implementation Reference

• src/index.ts:696-738 (handler)

  The tool 'x402_transcribe_audio' is registered and implemented in src/index.ts. It handles both paid (via X402_PRIVATE_KEY) and free test modes.

  server.tool(
    "x402_transcribe_audio",
    `Transcribe an audio file from a URL using faster-whisper with auto language detection.
  Price: $0.05 USDC per transcription (paid mode) | Free test: returns fixture data.
  
  Supports: MP3, WAV, M4A, FLAC, OGG, and most audio formats.
  Limits: 25MB file size, 10-minute duration. Payment is charged on download; duration refusals are still charged.
  Note: transcription can take 30–120 seconds for longer files (CPU-based, requests queue serially).
  Without X402_PRIVATE_KEY, only the free test endpoint is available.
  
  Returns: transcript text, detected language, language confidence, duration, and segment or word timestamps.`,
    {
      url: z.string().url().describe("URL of the audio file to transcribe (public, http/https, max 25MB, max 10 min)"),
      language: z.string().optional()
        .describe("ISO 639-1 language hint (e.g. 'en', 'fr', 'es') — omit for auto-detection"),
      word_timestamps: z.boolean().default(false)
        .describe("Return word-level timestamps instead of segment-level (default: false)"),
    },
    async (params) => {
      const base = APIS.transcription.baseUrl;
      try {
        const usePaid = !!PRIVATE_KEY;
        if (usePaid) {
          const payload: Record<string, unknown> = {
            url: params.url,
            word_timestamps: params.word_timestamps,
          };
          if (params.language) payload.language = params.language;
          const data = await apiPost(base, "/transcribe", payload, true);
          return textResult({ mode: "paid", cost: "$0.05", ...data });
        } else {
          const data = await apiGet(base, "/transcribe/test");
          return textResult({
            mode: "free_test",
            note: "Free test — returns fixture data. Set X402_PRIVATE_KEY for real audio transcription.",
            ...data,
          });
        }
      } catch (err: any) {
        return errorResult(err.message);
      }
    }
  );