DEV Community

Nettrux
Nettrux

Posted on

A freight quote isn't an API call: quote locks, expiry and the x402 challenge

Most x402 examples sell something with a fixed price. A weather lookup costs a fraction of a cent. An image generation costs a few cents. The server knows the price before the request arrives, so the HTTP 402 challenge is easy: here's the amount, pay it, get the thing.

Freight doesn't work like that. The price of moving one pallet from Fremont to Reno depends on the day, the carrier, the weight class and whether a liftgate is needed at the receiver. A price that's good at 9 AM can be gone by noon. If you're building the first 3PL on x402, as Nettrux is, that's the problem you have to solve before the payment protocol matters at all.

This article walks through how Nettrux's published agent flow handles a price that moves, and why the design choices look the way they do. Everything here comes from the public agent guide and the OpenAPI it links.

The problem: paying for a moving target

Imagine an agent working for a shipper. It asks for rates and gets back five options. It thinks for a moment, maybe checks with a human, then tries to pay for the second option. Three things can have gone wrong in that gap:

  1. The rate has changed, so the amount in the payment no longer matches the price.
  2. The agent retries after a timeout and pays twice for one shipment.
  3. The agent pays for an option that was never actually reserved, so there's nothing to book.

A fixed-price API never has to think about any of these. A freight seller has to handle all three, or agents will create a reconciliation mess that a person ends up cleaning up by hand. That defeats the reason to let an agent book in the first place.

Step one: shopping is not buying

Nettrux separates looking from committing. The rate-shop route, POST /v1/rates/shop, returns ranked options, cheapest first. Related rate calls cover LTL, air, spot and FTL.

The important detail is what rate-shop does not do. Per the agent guide, it doesn't create the quote ID that the booking route requires. An agent can shop as often as it likes without leaving half-reserved shipments lying around. Shopping is cheap and stateless. Buying is a separate, deliberate act.

That split matters for agents more than for people. A human shopping for freight naturally stops after a few tabs. An agent might fire dozens of rate requests while it compares lanes or tests pickup dates. If every one of those created a reservation, the broker's board would fill with ghosts.

Step two: lock the price

When the agent has picked an option, it calls POST /v1/quotes. The required top-level fields are quoteNumber, validUntil and rateInput. The response carries three things the agent cares about:

  • data.quote.id: the quote ID the booking step needs.
  • data.quote.lockedTotal: the locked price.
  • data.quote.status: one of active, converted, expired or withdrawn.

This is the step that turns a moving price into a fixed one. Once a quote is locked, the number the agent pays against is the locked total, not whatever the market says a minute later. The validUntil field makes the time window explicit, so both sides know how long the lock holds.

The guide also notes that the lock is idempotent on the quote number the agent sends. In plain terms: if the agent's network drops and it sends the same lock request again with the same quote number, it gets the same quote back rather than a second one. That closes off one of the most common agent failure modes, the nervous retry.

Step three: the four quote states

The status field is small, but it tells an agent nearly everything it needs to decide what to do next:

  • active: the lock is live. The agent can try to commit.
  • converted: the quote has already become a booking. Don't pay again. Go read the booking instead.
  • expired: the window passed. Shop and lock again rather than forcing the old price through.
  • withdrawn: the quote was pulled. Same answer: start over.

A well-behaved agent checks this before it ever tries to pay. That's how the double-payment problem gets solved at the design level instead of after the fact. An agent that sees converted knows the shipment is already booked.

Step four: commit with one field

Here's where x402 comes in. The booking route is POST /v1/immediate-bookings/commit, and the body is exactly { "quote_id": "..." } with no other fields.

That restraint is deliberate. The agent doesn't send a price, a lane, a weight or an amount. All of that was fixed when the quote was locked. The commit just points at the lock. There's no room for the agent to send a stale number or a mistyped total, because it doesn't send a number at all.

The first commit call goes out without an X-PAYMENT header. The OpenAPI summary documents that call as an x402 v1 HTTP 402 challenge, and the challenge carries the payment terms. Notably, the agent guide doesn't name a token, chain or payee address. Those live in the challenge itself, so the agent reads them from the response it actually gets. The guide also points out that the published response schema on that operation is HTTP 200, so a careful client handles both a 402 and a 200.

The agent then retries the same request with an X-PAYMENT header built by an x402 v1 client from that challenge. The summary describes the retry as verify, then settle, then book. Afterward, GET /v1/immediate-bookings/{booking_id} returns a receipt scoped to the tenant: the booking plus the settlement projection.

Why this shape suits agents

Put the steps together and you get a pattern that's easy for software to get right:

  • Shopping is free and leaves no trace, so agents can explore.
  • Locking turns a market price into a fixed one with an explicit expiry.
  • Locks are idempotent, so retries don't multiply reservations.
  • Status says whether to pay, read or start over, so agents don't double-pay.
  • The commit carries only a pointer, so no stale amount can slip in.
  • The 402 challenge carries the payment terms, so the agent never guesses where money goes.

None of these ideas is exotic. Good booking systems have used price holds and idempotency keys for years. What's new is putting them in front of an HTTP payment handshake that software agents can complete without a checkout page.

Where things stand

Being clear about status is part of the design too.

  • Nettrux is the first 3PL on x402, and Nettrux has settled a real x402 USDC payment on Base in testing.
  • The agent guide shows its deploy gates in plain view. Discovery publishing, real-money x402 settlement and guest x402 checkout are all switched off on the public site today, and the page says so.
  • Rating and booking calls use a bearer token, and the public site doesn't issue tokens. Developers who want to try the flow should contact dispatch.
  • Humans approve everything that moves money or leaves the building. An agent can shop, lock and stage. A person releases.

If you need freight moved this week, the Nettrux portal works the normal way: enter a lane, see live LTL, FTL and air options, and book.

FAQ

Why not just let the agent pay the rate-shop price?
Because that price isn't reserved. Locking first means the amount paid and the amount booked are the same number.

What happens if a lock expires mid-conversation?
The status reads expired. The agent shops and locks again rather than pushing an old price through.

Does the agent ever send a dollar amount?
Not to the commit route. The body is only the quote ID. Payment terms come from the 402 challenge.

Who do I talk to about access?
Dispatch answers at 1-888-617-3530 or dispatch@nettrux.net.


Alex Carney, Nettrux. Nettrux LLC is a California freight broker and forwarder in Fremont, and the first 3PL on x402. Learn more at nettrux.ai and read the agent guide.

Top comments (3)

Collapse
 
aiapikey profile image
HAOHAOnovai •

The TTL decides all three of those failure modes, and it should come from your agent's own timing rather than a round number. Measure the gap between "rates returned" and "payment sent": if the median is 75 seconds, a 60-second lock expires on more than half of quotes, and every re-quote is a fresh price.

That makes expected slippage a product of two measurable numbers, re-quote rate x drift per re-quote. At 60% and 2% you pay about 1.2% above the price you showed the human - often more than the payment fee you were optimizing.

For double-pay the key has to be the quote id, not the request id: a retry against a consumed quote then fails cleanly instead of booking twice.

Collapse
 
api_lord profile image
Api Lord •

Keeping rate-shop from minting the quote ID is the tidy bit. Agents get to window shop without leaving ghosts on the board.

One thing I'd check on the idempotent lock is the same quoteNumber resent with a different rateInput. Quietly returning the original quote would hide a real agent bug, so a conflict error is kinder there.

What happens when payment settles a few seconds after validUntil?

Collapse
 
aiapikey profile image
HAOHAOnovai •

Agreed on the conflict: same quoteNumber with a different rateInput must be a 409, never a quiet return. A quiet return is worse than an error because the agent believes it booked at the price it just asked for.

On settling after validUntil, the cleanest framing is that the quote is a price, not a reservation. Then there are only two honest policies, and both must appear in the 402 response so the agent can choose before it pays: hard reject with an explicit refund path, or accept only if the settled amount equals the quoted amount and the delay is inside a grace window you published.

What you must not do is accept late payments silently, because that makes validUntil advisory and the re-quote economics come back.