# Switch from dTelecom file transcription to MoneyTools Transcripts

Same `/v1/transcriptions/jobs` API shape, same $0.005/min list price, but **no prepaid credits and no wallet-auth headers**: each file is paid by a standard x402 402 → PAYMENT-SIGNATURE retry (USDC on Base). Typical change: base URL + swap the dTelecom SDK for an x402 fetch/requests wrapper.

## The diff
```diff
- BASE = "https://x402.dtelecom.org"
+ BASE = "https://speech.moneytools.dev"

- await gw.buyCredits({ amountUsd: 0.10 })            // prepaid credits: gone
- headers: Authorization/X-Wallet-Address/X-Wallet-Chain/X-Timestamp   // wallet-auth headers: gone
+ payFetch = wrapFetchWithPayment(fetch, x402Client)  // pays the exact 402 for each file

  POST  /v1/transcriptions/jobs   multipart: file, language, diarize   + Idempotency-Key   (unchanged)
  GET   /v1/transcriptions/jobs/{id}                                                        (unchanged path)
  poll auth: wallet signature headers from the paying wallet   (still accepted, EVM)
+ or: Authorization: Bearer <job_token>   (returned once in the 202)
  DELETE /v1/transcriptions/jobs/{id}                                                       (unchanged)
```

### TypeScript (from @dtelecom/x402-client)
```diff
- import { DtelecomGateway } from "@dtelecom/x402-client";
- const gw = new DtelecomGateway({ account });
- await gw.buyCredits({ amountUsd: 0.10 });
- const job = await gw.createFileTranscription({ file, idempotencyKey, language: "en" });
- const done = await gw.getFileTranscription(job.id);
+ import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+ import { ExactEvmScheme } from "@x402/evm";
+ const payFetch = wrapFetchWithPayment(fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
+ const form = new FormData(); form.append("file", file, "meeting.mp3"); form.append("language", "en");
+ const job = await (await payFetch("https://speech.moneytools.dev/v1/transcriptions/jobs",
+   { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: form })).json();   // 202 {id, job_token, status_url}
+ const done = await (await fetch(job.status_url, { headers: { Authorization: `Bearer ${job.job_token}` } })).json();
```

## Differences you should know
| | dTelecom | MoneyTools Transcripts |
|---|---|---|
| Price | $0.005 per decoded audio minute (seconds rounded up), from prepaid credits | $0.005 per started audio minute, paid per file — no credits, no minimum |
| Payment | buy credits first (min $0.10), then wallet-signed requests | x402 v2 per request (USDC on Base, CDP facilitator); any x402 client |
| Auth headers | Authorization + X-Wallet-Address + X-Wallet-Chain + X-Timestamp | none to submit; poll with Bearer job_token or the same EVM wallet-auth headers from the paying wallet |
| Endpoint / body | POST /v1/transcriptions/jobs, multipart file, language, diarize, Idempotency-Key | same, plus JSON {"url"} import, optional webhook and summary |
| Max file | 256 MiB / 2 h | 100 MB / 3 h (MP3/WAV segmented; other containers up to 10 min) |
| Language | default en, auto not supported | auto-detect by default, or pass a Whisper code |
| Speaker diarization | included | NOT available (speaker:null, speaker_segments:[]) — stay on dTelecom if you need speakers |
| Outputs | text, segments, media | same shape + SRT, VTT, TXT (?format=), optional summary |
| Bad files | hold released | first ~5 min segment is transcribed before settlement: unreadable files are never charged |
| Retention | 24 h | 24 h |
| Capacity | admission-bounded (429) | shared daily audio-minute budget (live in https://speech.moneytools.dev/health → usage); paid jobs over the budget wait and resume after 00:00 UTC |

Rounding: we bill per **started** minute (61 s = 2 min = 0.004 USDC). Free price check: `GET https://speech.moneytools.dev/v1/speech/quote?minutes=60`; the unpaid POST also returns the exact price for your file before you pay.

## curl
```bash
# 1) unpaid upload -> HTTP 402 + PAYMENT-REQUIRED (exact price for THIS file) + {id, quote}
curl -i -X POST https://speech.moneytools.dev/v1/transcriptions/jobs \
  -H 'Idempotency-Key: meeting-42' -F file=@meeting.mp3 -F language=en

# 2) sign the PAYMENT-REQUIRED header locally (nothing is sent; refuses above MAX_USD)
curl -sO https://speech.moneytools.dev/examples/x402_sign.py && pip install "x402[evm]" eth-account
SIG=$(X402_PRIVATE_KEY=0x... python3 x402_sign.py "<PAYMENT-REQUIRED header value>")

# 3) same request, same Idempotency-Key (stored upload reused) + PAYMENT-SIGNATURE -> 202 {id, job_token, status_url}
curl -X POST https://speech.moneytools.dev/v1/transcriptions/jobs -H 'Idempotency-Key: meeting-42' \
  -H "PAYMENT-SIGNATURE: $SIG" -F file=@meeting.mp3 -F language=en

# 4) poll (every ~15 s) and fetch subtitles
curl -H "Authorization: Bearer $JOB_TOKEN" https://speech.moneytools.dev/v1/transcriptions/jobs/$ID
curl -H "Authorization: Bearer $JOB_TOKEN" "https://speech.moneytools.dev/v1/transcriptions/jobs/$ID?format=srt"

# whole flow as one script:  curl -sO https://speech.moneytools.dev/examples/transcribe.sh && bash transcribe.sh meeting.mp3 srt
```

## Python (x402 client library)
```python
# pip install "x402[requests,evm]" eth-account
import uuid, time, requests
from eth_account import Account
from x402 import x402ClientSync, max_amount
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmScheme

client = x402ClientSync()
client.register("eip155:8453", ExactEvmScheme(signer=EthAccountSigner(Account.from_key(PRIVATE_KEY))))
client.register_policy(max_amount(500_000))        # never pay more than 0.50 USDC per file
s = x402_requests(client)                          # pays the 402 and resends the same request

r = s.post("https://speech.moneytools.dev/v1/transcriptions/jobs",
           headers={"Idempotency-Key": f"py-{uuid.uuid4().hex}"},
           files={"file": ("meeting.mp3", open("meeting.mp3", "rb").read())}, data={"language": "en"})
job = r.json()                                     # 202 {id, status:"running", job_token, status_url, payment}
auth = {"Authorization": f"Bearer {job['job_token']}"}
while (st := requests.get(job["status_url"], headers=auth).json())["status"] not in ("completed", "failed"):
    time.sleep(15)
print(st["result"]["text"])                        # also: result.segments, result.srt, result.vtt
# full script: https://speech.moneytools.dev/examples/transcribe.py
```

## TypeScript (@x402/fetch)
```ts
// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
import { readFile } from "node:fs/promises";

const client = new x402Client()
  .register("eip155:8453", new ExactEvmScheme(privateKeyToAccount(process.env.X402_PRIVATE_KEY as `0x${string}`)))
  .registerPolicy((_v, reqs) => reqs.filter((r) => BigInt(r.amount) <= 500_000n)); // cap 0.50 USDC per file
const payFetch = wrapFetchWithPayment(fetch, client);

const form = new FormData();
form.append("file", new Blob([await readFile("meeting.mp3")]), "meeting.mp3");
form.append("language", "en");
const res = await payFetch("https://speech.moneytools.dev/v1/transcriptions/jobs", {
  method: "POST", headers: { "Idempotency-Key": `ts-${crypto.randomUUID()}` }, body: form,
});
const job = await res.json(); // 202 {id, job_token, status_url, payment:{amountUsd, transaction}}
const auth = { Authorization: `Bearer ${job.job_token}` };
let st;
do { await new Promise((r) => setTimeout(r, 15000)); st = await (await fetch(job.status_url, { headers: auth })).json(); }
while (st.status !== "completed" && st.status !== "failed");
console.log(st.result.text); // also st.result.segments / srt / vtt
// full script: https://speech.moneytools.dev/examples/transcribe.ts
```

## Keep the official @dtelecom/x402-client (base URL + one line)
```ts
import { DtelecomGateway } from "@dtelecom/x402-client";        // unchanged
import { installTranscriptsFetch, TRANSCRIPTS_URL } from "@moneytools-dev/transcripts";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
installTranscriptsFetch(account, { maxUsdPerRequest: 0.5 });     // + 1 line: pays the 402 of each file (only for https://speech.moneytools.dev)
const gw = new DtelecomGateway({ account, gatewayUrl: TRANSCRIPTS_URL }); // + base URL
// no gw.buyCredits(...)
const job = await gw.createFileTranscription({ file, filename: "meeting.mp3", idempotencyKey: "meeting-42", language: "en" });
const done = await gw.getFileTranscription(job.id);            // the client's own wallet-auth headers work for polling
console.log(done.status, done.result?.text);
```
Tested against @dtelecom/x402-client 0.6.2: create → poll (its own EVM wallet-auth headers are accepted from the wallet that paid) → delete. Solana wallet auth is not supported.

## Mini SDKs (same method names)
TypeScript:
```ts
import { TranscriptsGateway } from "@moneytools-dev/transcripts";   // same method names as DtelecomGateway
const tc = new TranscriptsGateway({ account, maxUsdPerRequest: 0.5 });
const job = await tc.createFileTranscription({ file, idempotencyKey: "meeting-42", language: "en" });
const done = await tc.waitForFileTranscription(job.id);
const srt = await tc.getFileTranscriptionText(job.id, "srt");
```
Python:
```python
from eth_account import Account
from moneytools_transcripts import TranscriptsClient   # pip install moneytools-transcripts (not published yet; see below)

tc = TranscriptsClient(Account.from_key(PRIVATE_KEY), max_usd_per_request=0.5)
job = tc.create_file_transcription(open("meeting.mp3", "rb"), idempotency_key="meeting-42", language="en")
done = tc.wait_for_file_transcription(job["id"])     # Bearer job_token, or wallet auth from the paying wallet
print(done["result"]["text"])
```
TypeScript: npm i @moneytools-dev/transcripts. The PyPI package moneytools-transcripts is built and tested but not published yet; until then use the copy-paste Python snippet above or the raw x402 examples below. Any x402 client works.

## Benchmark (2026-11-10, honest numbers)
| Sample (public domain) | Length | Segments | Ref. words | WER | Processing | × real time |
|---|---|---|---|---|---|---|
| Ozymandias (Shelley), LibriVox | 1.5 min | 1 | 111 | 0.9% | 2.8 s | 0.032 |
| Gettysburg Address, LibriVox | 2.7 min | 1 | 268 | 1.9% | 6.2 s | 0.039 |
| The Raven (Poe), LibriVox | 9.5 min | 2 | 1090 | 5.4% | 31.3 s | 0.055 |

Word error rate after lower-casing and stripping punctuation, aligned so the LibriVox intro/outro (not in the reference text) is not counted. Reference texts: Project Gutenberg #4 and #1065, standard 1818 Ozymandias text. Readers may follow a slightly different edition, and archaic spellings count as errors (e.g. 'visiter' → 'visitor', 'Pallas' → 'palace'), so these are sanity numbers, not a leaderboard.

Processing time = paid submit → last segment done, measured with our engine code on our build box calling Workers AI remotely (adds network hops; in production the worker calls the model from inside Cloudflare). Segments of one job run one after another, so long files take roughly (minutes ÷ 5) × 8–16 s.

3 clean single-speaker English recordings only. No diarization. Noisy, multi-speaker or non-English audio will score worse. We have not benchmarked dTelecom and make no claims about its quality or speed.

## Downloadable examples (no repo needed)
- https://speech.moneytools.dev/examples/transcribe.py
- https://speech.moneytools.dev/examples/transcribe.sh
- https://speech.moneytools.dev/examples/transcribe.ts
- https://speech.moneytools.dev/examples/x402_sign.py

## Response shapes
- 402: `{x402Version:2, accepts:[{scheme:"exact", network:"eip155:8453", amount, payTo, asset:USDC}], id, status:"payment_required", duration_seconds, quote:{startedMinutes, amountUsd}}` + `PAYMENT-REQUIRED` header.
- 202: `{id, status:"running", duration_seconds, job_token, status_url, results:{json,srt,vtt,txt}, poll_every_seconds:15, payment:{charged, amountUsd, transaction}}` + `PAYMENT-RESPONSE` header.
- GET: `{id, status: queued|running|completed|failed, duration_seconds, result:{text, language, segments:[{start,end,speaker,text}], media, timing_type, srt, vtt}}`.
- Same Idempotency-Key after payment → 409 `already_paid` (use a new key for a new file).

Links: llms.txt https://speech.moneytools.dev/llms.txt · OpenAPI https://speech.moneytools.dev/openapi.json · x402 https://speech.moneytools.dev/.well-known/x402 · MCP https://speech.moneytools.dev/mcp · health/capacity https://speech.moneytools.dev/health
