Nettrux 如何透過部署閘門告知 Agent 哪些 x402 功能未啟用
Agents should be able to read your feature flags: how the first 3PL on x402 tells buyers what is switched off
Nettrux 在其 Agent 指南以純文字列出部署閘門,明示 x402 發現、真實款項結算及訪客結帳均未啟用。
Agents should be able to read your feature flags
Here is a problem nobody had five years ago. A software agent lands on a seller's website, reads the docs, and has to decide on its own whether the thing described there actually works today. It can't hop on a call with sales. It can't read the tone of a "coming soon" banner. It can't tell the difference between a roadmap slide and a production route unless someone writes the difference down in plain text.
For most API products the cost of guessing wrong is a failed request and a retry. For freight, guessing wrong means a truck that never shows up, or an agent telling its human that a load is booked when it isn't.
Nettrux, a freight broker and forwarder in Fremont, California, is the first 3PL on x402. One small decision in how it documents that work is worth copying no matter what you sell: the agent guide opens with a section called "Deploy gates" that prints, in plain text, which capabilities are on and which are off.
What the gates say
Each gate is an environment variable read when the site is built. The guide shows the value that deployment baked in, and states the rule outright: only the exact string true turns a gate on. As of the instructions dated 2026-11-09, there are three:
-
EDGE_X402_DISCOVERY_PUBLISHED: false. The site serves its own/.well-known/x402file, but it's a pointer, not a catalog of payable resources. The resources array on that origin is empty and the file doesn't redirect anywhere. -
X402_REAL_MONEY_SETTLEMENT_LIVE: false. The guide describes the documented 402 handshake and explicitly does not claim that a payment has settled, or that settlement books the freight. -
GUEST_X402_CHECKOUT_ENABLED: false. Guest routes exist in the OpenAPI document, and the guide tells agents not to call them.
That's three "no" answers at the very top of a page whose whole purpose is to sell agent-booked freight. It reads like an odd marketing choice. It's actually the most useful thing on the page for a machine buyer.
Why an agent needs this more than a person does
A person reading a vendor site fills gaps with judgment. They notice the beta label, they email someone, they wait for a demo. An agent fills gaps with whatever the text implies. If the docs describe a pay-and-book route in confident present tense, a well-behaved agent will assume it can pay and book, and it'll pass that assumption up to its user.
So a seller selling to agents has a new obligation: say what's true about state, not just about shape. An OpenAPI document tells you the shape of a request. It doesn't tell you whether the money behind that request is real, or whether a route is wired to anything. Deploy gates fill that gap. They turn "is this live?" from a judgment call into a field an agent can read.
There's a second benefit. Gates make the docs self-correcting. When a value flips to true in a future deployment, the page changes with it. The agent doesn't have to diff marketing copy or trust a blog post to learn that something moved; it reads the same line it read last week and gets a different answer.
How an agent should use them
If you're building a shipping agent that might buy from Nettrux, or from any seller that publishes gates like this, here's a reasonable policy:
-
Read the gates before planning. Fetch the guide, or the
/.well-known/x402pointer it names, and treat each gate as a precondition for a branch of your plan. With discovery unpublished, the payable URLs live underx402Resourceson the freight API host, not on the marketing site. - Never report more than the gates allow. With real-money settlement off, your agent should never tell its user "paid and booked" based on the docs alone. Quote locks are fine to talk about. Settlement claims should come only from fields on a response the agent actually received.
-
Trust the response over the page. The guide is clear that a successful commit returns
data.booking.money_modeanddata.settlementwith a network and a transaction. Those fields, on the actual response, are what your agent reports. The page tells you what to expect; the response tells you what happened. - Treat "don't call" as binding. The guest routes are in the OpenAPI, and the guide says not to call them. A good agent respects the narrower instruction over the broader schema.
- Re-check on a schedule, not on every call. Gates change with deployments, not with requests. Caching them for a day and re-reading them before any booking is a sensible middle ground.
What is on today
The gates describe what's off. The rest of the guide describes what an authenticated agent can do now, and it's a clean flow:
-
Rate-shop with
POST /v1/rates/shopto get ranked options, cheapest first. Related rate calls cover LTL, air, spot and FTL. -
Price-lock with
POST /v1/quotes(required fieldsquoteNumber,validUntil,rateInput). You get a quote id, alockedTotal, and a status of active, converted, expired or withdrawn. The lock is idempotent on the quote number you send, so a retry won't create a second quote. -
Commit with
POST /v1/immediate-bookings/commit, a body of exactly{ "quote_id": ... }, and no other fields. The OpenAPI summary documents the first call as an x402 v1 HTTP 402 challenge. The paid retry carries anX-PAYMENTheader built from that challenge and is described as verify, then settle, then book. The published response schema lists 200, so the guide tells you to handle both. -
Read the receipt with
GET /v1/immediate-bookings/{booking_id}, which returns the booking plus a settlement projection, scoped to your tenant.
All of these use a bearer token. The site is upfront that it doesn't issue tokens and doesn't describe a self-serve signup for them. That's another honest "not yet" an agent can act on: if it doesn't already hold credentials, the right move is to hand off to a human, and the guide gives a dispatch number (1-888-617-3530) for exactly that.
On the payment side, the claim Nettrux makes publicly is narrow and specific: it has settled a real x402 USDC payment on Base in testing. That's an engineering milestone, not a production claim, and the gates say so in machine-readable form.
The broader lesson for x402 sellers
x402 makes paying over HTTP easy. That's the point of putting payment in a status code. But easy payment raises the stakes on accurate state. If an agent can pay in one retry, it needs to know, before that retry, whether the payment is real, whether the thing being bought will be delivered, and whether the route it found is one it should use at all.
Most sellers today answer those questions in prose spread across a pricing page, a changelog and a support article. Agents are bad at stitching that together. A short block of named flags with literal values is something any agent can parse.
If you run an x402 service, consider publishing your own gates:
-
Name them like variables, not like features.
REAL_MONEY_SETTLEMENT_LIVEis harder to misread than "Payments (beta)". - Print the literal value the deployment actually uses, not a summary of it.
- Say what each value means for the caller. "Don't call these routes" is more useful than "limited availability".
- Tie them to the build, so the page can't drift from production.
Freight is a good stress test for this idea because the cost of a wrong assumption is physical: a dock appointment, a driver's time, a customer's shipment. If a 3PL can be this explicit about what's off, a data API has no excuse.
FAQ
Is Nettrux's x402 endpoint public? No. The commit route is documented for authenticated agents with a bearer token, and the discovery gate is off. Nettrux is building the public agent rail.
Does Nettrux settle real money over x402 today? The real-money settlement gate is off. Nettrux has settled a real x402 USDC payment on Base in testing.
What modes can an agent rate? The guide lists LTL, air, spot and FTL on rate calls.
Where do I start? Read the agent guide, then the OpenAPI document it links. For anything that needs a person, call dispatch.
Alex Carney, Nettrux. nettrux.ai
來源:DEV Community · dev.to