nyctransitx402: The Transit API That Teaches Agents How to Pay

A deep dive into a New York City transit service built for machine clients, with dual 402 payment challenges, strict schemas, and a radically agent-first interface.

8 to 10 min read • View on GitHub • More from mmurrs

A wide editorial scene showing a machine client approaching a guarded transit gateway with two different payment tokens in hand. The gateway opens only after a dual-key lock is satisfied, and a transit map sits beyond it as the destination. The image explains that access is negotiated by protocol and payment choice before any transit data is returned.
The repo’s core idea is that a transit API can behave like a negotiated gateway, not a public vending machine.

re-imagined, simple, and developer-friendly replacement for the MTA's GTFS-realtime and SIRI APIs.

Mateo Murrs, Project Creator · nyctransitx402 GitHub README
Key Takeaways

The API doesn’t just answer. It negotiates.

That is the memorable move in nyctransitx402. Instead of treating payment as a separate billing page or a fixed subscription wall, the repo turns access itself into a machine-readable exchange. A client can arrive, get challenged, and then choose a payment path without a human stepping in.

That makes this project feel less like a transit wrapper and more like a prototype for the agentic web. The transit data is concrete, but the real subject is the interface between software agents and paid services.

A WSJ-style hedcut portrait of Mateo Murrs based on his verified GitHub avatar. The portrait gives the article a human anchor while the surrounding story focuses on the API design and payment architecture.

Why transit is a good stress test for the agentic web

Transit is brutal in all the right ways. It is time-sensitive, location-sensitive, and full of small decisions that matter: which stop is closest, which line is delayed, whether a bike or a bus is the faster move. A human can glance at a map and improvise. An agent needs structured answers it can trust.

That is why the repo’s shape matters. It does not ask an AI to parse a pretty interface. It gives it a compact, queryable service that can resolve distance, walking time, vehicle status, and nearby options into something operational.

The system is small, but the contract is strict

The repo is lean on files, but strict about how requests move through payment, validation, and live data aggregation.

File or folderRoleWhy it matters
server.jsCoordinates requests, schemas, distance logic, and live feed mergesThis is the traffic controller for the whole API
dual402.jsImplements the dual-protocol payment challengeThis is the repo’s most original mechanism
data/Stores static station and stop geographyThis gives the API local spatial context
proxy/Provides discovery and landing-page surfacesThis makes the service easier for agents and humans to find
tests/Enforces invariants around payment and schemasThis treats economic behavior as correctness, not decoration

The interesting part is not size. It is discipline. The repository keeps the stack compact, but the behavior is tightly specified, which is exactly what machine clients need if they are going to trust the output enough to act on it.

How server.js fuses live feeds with local geography

The server side starts with validation, not optimism. Requests are checked against strict schemas, then the API resolves geography from local station data and computes distance and walking time before it returns a result. Only after that does it merge in live data from the transit feeds.

That sequencing is the point. A raw feed can tell you where a train is. This server tells you whether that train is the right thing to chase, given where the requester actually is.

A close-up editorial illustration of two data streams joining into one channel. One stream is a live transit feed rendered as linked nodes, and the other is a static street grid with station markers. They converge into a single decision corridor that ends in a compact JSON-like packet. The image explains how the API turns raw transit signals plus local geography into a decision-ready response.
Live feeds become more useful after they are merged with static geography and walking context.

dual402.js is the real invention

This is where the repo stops looking like a transit project and starts looking like a protocol paper. The middleware intercepts the response flow and can issue a payment-required challenge that speaks to two payment standards at once. The client is not forced into one wallet path upfront. It can choose at runtime.

That choice matters because it keeps the API interoperable. The implementation also stays lean, using native crypto for JWT work instead of dragging in a heavier dependency stack. The result is an unusually sharp piece of middleware: small surface area, high protocol ambition.

Invariant-driven testing turns payments into a safety property

The tests are not just checking whether routes respond. They are checking that paid routes do not accidentally become free routes, and that schemas stay fixed enough for agents to rely on them. That is a different quality bar.

For a machine-facing API, payment integrity is part of correctness. If a client cannot predict whether a request will succeed, or whether a paid response can be bypassed, the service is not trustworthy enough for automation.

ConcernTypical transit wrappernyctransitx402
Response shapeOften loose and human-orientedStrict JSON schemas for machine clients
Payment modelUsually none or externalDual 402 challenge in the middleware path
GeographySometimes exposed rawMerged with distance and walking context
TestingFeature checks and smoke testsInvariant checks for economic and schema behavior

What this beats, and where it doesn’t

Compared with the MTA’s official feeds, this repo is easier to consume. Compared with OneBusAway, it is far lighter. Compared with Transitland, it is narrower and more self-hostable. That is not a defect. It is the design.

The project wins when the job is specific: NYC transit, agent-first access, strict output, and programmable payment. It does not try to be the universal transit platform. It tries to be the most legible paid middleware for one city and one class of client.

OptionStrengthTrade-off
Official MTA feedsAuthoritative source dataHarder to consume directly, especially for machine clients
OneBusAwayMature open-source transit platformHeavier to deploy and broader than this use case
TransitlandLarge aggregated coverageLess specific to NYC quirks and less self-hosted
nyctransitx402Agent-first, NYC-specific, payment-awareNarrower scope by design

A small repo with a larger argument

The deeper argument here is that paid machine-to-machine services need more than a billing page. They need a negotiated contract, strict schemas, and a way to prove that the thing being paid for is the thing being executed. In that sense, transit is the example, not the message.

nyctransitx402 reads like an early sketch of the economic layer beneath the agentic web. If that future arrives, APIs will not just answer. They will authenticate, negotiate, verify, and then serve.