truewire

Open source · Python on PyPI, TypeScript in the repo

Typed clients, true to the wire.

Truewire turns any API, documented or not, REST or WebSocket, into a typed, validated client you can trust. Record real wire examples. Declare what a schema can't say. Generate the client, the tests, the mock and the docs from the same source.

Get started Read the spec format

pip install truewire · Apache-2.0 toolchain, MIT runtime. No account.

recorded GET /pets/42 → 200
{
  "id": 42,
  "name": "Fido",
  "status": "sold",
  "created_at": "2025-12-24T08:30:00Z"
}
typed Pet, validated on every call
id          int
name        str
status      Literal['available', 'pending', 'sold']
created_at  datetime  # parsed, tz-aware
  • 14 production clients
  • 3,638 endpoints
  • 2,404 recorded HTTP pairs

Those 14 clients serve exchange and blockchain APIs in production, where the wire is the only reliable documentation.

  1. Built from the wire, not the document.

    Every endpoint is backed by a recorded request and response, captured against the live API. The schema has to match the recording. When the API changes, the check goes red before your users do.

  2. The things schemas can't say, declared and audited.

    Pagination, response envelopes, redacted fields, stream subscriptions: declared as data beside the endpoint, checked against the schema, generated into code. A pagination block becomes a _paged walker with guards against silent truncation.

  3. WebSocket is not an afterthought.

    Streams, RPC-over-WS and JSON-RPC are first-class in the spec, the generator and the mock server. The mock replays recorded subscribe, push and unsubscribe sequences over a real socket. Your tests never touch the network.

02

From docs URL to verified client

Six commands. One source of truth. Nothing you have to remember to keep in sync.

shell
$ pip install truewire
Successfully installed truewire-0.3.0 truewire-core-0.1.1

$ truewire init petstore
Created petstore

$ cd petstore && truewire import openapi ../petstore.yaml
operations      8
written         8
skipped         0
shared schemas  4 (Category, Order, OrderBase, Pet)
examples        5
warnings        1
  - GET /pets: dropped header parameter `X-Request-Id`

validation: 0 errors, 0 warnings

$ truewire check
Project: petstore
Endpoints: 8 (rpc=8, stream=0)

Example validation:
  endpoints  5/8
  files      5
  errors     0

Spec authoring:
  pagination  0
  violations 0
  warnings   0

Result: OK

$ truewire examples --require-verified
Project: petstore
Endpoints: 8 (rpc=8, stream=0)
Coverage (paired examples): 5/8 (62%)

Public     3/6    with examples
Authed     2/2    with examples

Unverified: 3 endpoint(s) declared `unverified` (see ADR 0001)

Example files:
  requests    5
  responses   5

Response codes:
  200         4
  201         1

$ truewire generate python
Initialized .truewire/python-files.json; preserved existing unowned files.
Generated petstore (python) into src/petstore

$ truewire mock
HTTP  http://127.0.0.1:8321
WS    (no websocket examples in this project)
Serving recorded examples; Ctrl-C to stop.
python
from petstore import Petstore

async with Petstore.new(base_url='http://127.0.0.1:8321') as client:
  pet = await client.pets.get_pet(pet_id=42)
  pet['name']        # 'Fido', typed str
  pet['status']      # 'sold', typed Literal['available', 'pending', 'sold']
  pet['created_at']  # datetime(2025, 12, 24, 8, 30, tzinfo=UTC), parsed from the wire
03

How it works

  1. 1 Record.

    Point the spec at the API's docs and call each endpoint once: truewire capture makes the call through your own generated client and keeps the pair. truewire import openapi seeds the spec if a document exists. An endpoint that can't be called declares why.

  2. 2 Declare.

    Add the blocks a schema can't hold: pagination, envelope, redacted, push. Give every price a decimal-string and every timestamp its real epoch unit. truewire check audits all of it.

  3. 3 Generate.

    truewire generate python writes an async client with typed responses, runtime validation on by default, _paged walkers, and docstrings pulled from the spec.

  4. 4 Gate.

    truewire examples --require-verified, truewire surface, truewire standards and truewire docs check run in CI. We call a client done when they are green, not before.

04

How it compares

A cell reads ? where we have not verified the claim ourselves. We publish what we checked, not what we guessed. Tell us what we got wrong and we will fix it.

CapabilityTruewireOpenAPI GeneratorSpeakeasyFernhey-api
Open sourceYes (Apache-2.0, MIT runtime)Yes (Apache-2.0)No (closed generator)Partial (?)Yes (MIT)
Self-hostedYesYesCLI runs locally, generator is hosted (?)?Yes
Runtime validation of responsesYes, default on, per-call overrideVaries by generatorYes?Yes (via Zod/Valibot plugins)
WebSocket streamsYes (subscribe, push, RPC over WS)No?Partial (?)No
JSON-RPCYes (over HTTP and WS)No??No
Declared pagination with generated walkersYes, 5 strategiesNoYesYes?
Mock server from recorded examplesYes, HTTP and WSNoHTTP only (?)?No
Verified-coverage gateYesNoNoNoNo
Docs type-checkingYesNoNoNoNo
MCP serverYes (truewire mcp)NoYes (Gram)??
TypeScriptYes (generator in the repo, npm pending)YesYesYesYes
PythonYesYesYesYesExperimental

We build Truewire for API consumers first: people integrating an API they do not control. If you own your API and have a clean OpenAPI document, any tool above will serve you, and truewire import openapi reads your document too.

05

Pricing

Talk to us

Free. Self-hosted. Forever.

$0

The toolchain, the runtime, the mock server, the checks. Apache-2.0 and MIT. Everything one developer needs, with no account.

Get started

Spec service.

From $2,000 per API

Send us a docs URL. Get back a verified spec, a mock server, a generated client with tests, and checked docs, delivered as a repository you own. We price by surface size and by how much of it we can verify against a real account. For teams migrating off a hosted generator, or anyone integrating a WebSocket API they didn't write.

Request a quote

Cloud.

Coming soon

A hosted registry with private specs, managed regeneration and publishing (spec change, pull request, package release), and hosted mock endpoints for CI. Free for public specs.

Join the waitlist
06

FAQ

Is this OpenAPI?

No. The spec is JSON Schema 2020-12 per endpoint, one directory each, with recorded examples and declared blocks for pagination, envelopes, streams and redaction. OpenAPI has no place for most of that. The format holds what OpenAPI cannot and asks for less ceremony.

Can I import my OpenAPI document?

Yes. truewire import openapi spec.yaml reads 3.0 and 3.1, writes one endpoint directory per operation, and turns any examples in the document into recorded example pairs. Then truewire check tells you what the document left out.

Does it do WebSocket?

Yes, and it is the reason the tool exists. Streams (subscribe, push, unsubscribe), request/reply over WS, and JSON-RPC over either transport are first-class in the spec, the generator and the mock server. The mock replays recorded message sequences over a real socket.

Is there a TypeScript client?

Yes, in the repository. truewire generate typescript reads the same plan as the Python backend and writes an ESM package typed by the @truewire/core runtime; the GitHub example is generated in TypeScript and replays the same recordings through the mock, in CI. The npm package is pending, and WebSocket streams and composite cores are being finished now. Rust and Go are the candidates after that. We do not promise dates. We ship when the gate is green, and we publish the gate on the roadmap.

How is this different from Speakeasy?

Speakeasy generates SDKs from an OpenAPI document you own, on a closed generator, for a monthly fee per language. Truewire is open source and self-hosted, starts from recorded wire examples rather than a document, covers WebSocket and JSON-RPC, and gates every endpoint on a recorded example or a stated reason. If you own a clean OpenAPI document and want six languages this quarter, pick Speakeasy. If you are integrating an API you don't control, pick Truewire.

Who's behind it?

Truewire is a spinoff of the internal tooling behind Tribulnation's typed exchange clients, founded by Marcel Claramunt (@marcelclaramunt), who spent years hand-maintaining clients for 14 exchange and blockchain APIs and is the project's public face. An AI operator runs the day-to-day engineering, the docs and the roadmap. Marcel decides on anything public, financial or legal. We hold the code to one bar whoever wrote it: every claim in the docs is checked against the code, and every endpoint against the wire.