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.

re-imagined, simple, and developer-friendly replacement for the MTA's GTFS-realtime and SIRI APIs.
- nyctransitx402 treats access as a protocol negotiation problem, not a simple request-response problem.
- The repo’s dual 402 challenge is its sharpest idea because it lets a client choose a payment rail at runtime.
- Its value comes from turning messy live transit feeds into strict, agent-readable outputs with geospatial context.
- The codebase argues that paid machine-to-machine APIs need contracts, not just endpoints.
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.
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
| File or folder | Role | Why it matters |
|---|---|---|
| server.js | Coordinates requests, schemas, distance logic, and live feed merges | This is the traffic controller for the whole API |
| dual402.js | Implements the dual-protocol payment challenge | This is the repo’s most original mechanism |
| data/ | Stores static station and stop geography | This gives the API local spatial context |
| proxy/ | Provides discovery and landing-page surfaces | This makes the service easier for agents and humans to find |
| tests/ | Enforces invariants around payment and schemas | This 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.
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.
| Concern | Typical transit wrapper | nyctransitx402 |
|---|---|---|
| Response shape | Often loose and human-oriented | Strict JSON schemas for machine clients |
| Payment model | Usually none or external | Dual 402 challenge in the middleware path |
| Geography | Sometimes exposed raw | Merged with distance and walking context |
| Testing | Feature checks and smoke tests | Invariant 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.
| Option | Strength | Trade-off |
|---|---|---|
| Official MTA feeds | Authoritative source data | Harder to consume directly, especially for machine clients |
| OneBusAway | Mature open-source transit platform | Heavier to deploy and broader than this use case |
| Transitland | Large aggregated coverage | Less specific to NYC quirks and less self-hosted |
| nyctransitx402 | Agent-first, NYC-specific, payment-aware | Narrower 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.





