What I Learned Building a 402-Powered API for Agent Workflows

Max Holloway — Wed, 20 May 2026 19:35:37 +0000

Disclosure: I used AI as an editing/drafting assistant for this post, but the architecture, examples, and technical claims here are mine and were reviewed before publishing.

Most paid APIs still assume a familiar model:

issue an API key
put the user on a plan
count usage in the background
send an invoice later

That works fine for many developer products, but I kept running into a mismatch when thinking about agent workflows.

While building MintAPI, I kept coming back to the same question: are API keys and subscriptions really the right default for software that makes bursty, task-driven requests on behalf of an agent?

That led me to experiment with a paid API flow built around 402 Payment Required / x402.

The idea

The request flow looks like this:

the client makes a normal HTTP request
the server responds with a payment challenge
the client signs the payment using its own signer infrastructure
the client retries the request with payment attached
the server verifies payment and serves the response

In my case, this became a paid API surface for agent workflows, with a buyer-side SDK and a seller-side gateway.

The interesting part was not just "can I charge for an API call?" The interesting part was whether the payment step could feel like a normal transport concern instead of a separate billing workflow glued on top.

Why I didn't want API keys to be the whole story

I am not against API keys. They are simple, familiar, and easy to document.

But for this project, they felt like the wrong abstraction for a few reasons:

1. API keys identify access, not payment intent

An API key says "this caller is allowed to use the API." It doesn't naturally express "this specific request should carry a payment."

That usually pushes billing into metering systems, account plans, quotas, and reconciliation logic outside the request itself.

2. Agent traffic is uneven

Human-oriented products often map well to seats, monthly plans, or generous quotas.

Agent workloads often don't. You can have very low average usage with sharp spikes. In that world, a request-by-request payment model felt more honest.

3. I wanted the buyer to own signing

One thing I wanted to avoid was hiding too much payment logic inside the API provider.

The provider should verify payment. But the actual signing should happen in the buyer runtime, or in wallet infrastructure the buyer controls.

That boundary ended up shaping the whole SDK.

The two sides of the system

I ended up with two separate pieces.

Seller side: the gateway

The seller-side gateway does a few things:

validates the request
decides whether the route requires payment
returns a payment challenge when needed
verifies and settles payment
calls the upstream provider
returns a normalized response

One detail I cared about a lot: validation happens before payment.

That means malformed requests should fail fast with a normal error instead of charging the caller for a bad request. If someone sends an invalid query, the system should return a 400, not trigger a paid flow first.

That sounds obvious, but it is exactly the kind of edge case that makes paid APIs annoying if you get it wrong.

Buyer side: the SDK

On the client side, I wanted the integration to feel close to ordinary HTTP.

The SDK flow is roughly:

make request
detect 402
inspect supported payment routes
resolve a signer
sign
retry with a payment header

I also wanted the signer logic to stay out of endpoint code.

Instead of every endpoint handler deciding how to sign, the SDK uses a signer resolution layer. In practice that means the client can route signing based on network or signer family rather than scattering that logic across all API calls.

That made the buyer SDK much easier to reason about. If you want to see the public client surface, the MintAPI gateway SDK shows the buyer-side flow more directly.

Why signer resolution mattered more than I expected

This was probably the most important design choice in the client.

At first glance, "just pass a signer" sounds enough. In practice, it gets messy quickly.

Different buyers may want:

one default signer
different signers per network
different signers per signer family
managed wallet infrastructure
HSM/KMS-backed signing
different preferences depending on environment

If that logic leaks into every API call, the client becomes brittle very quickly.

So I treated signer resolution as its own concern. Endpoint code asks for a signer indirectly. A resolver decides how that happens.

That separation made the client easier to extend and reduced a lot of hidden complexity.

Error handling is part of the product

One thing I did not want was a payment-aware client that collapses every failure into "request failed."

That makes it hard for agent runtimes to react correctly.

There is a real difference between:

the server issued a payment challenge
the client could not find a supported payment network
the signer was unavailable
payment header creation failed
the upstream API failed after payment succeeded

Those are operationally different failures. So the client surface exposes typed errors instead of one generic failure mode.

That sounds like a small SDK detail, but for automation it matters a lot. An agent can retry one class of error, escalate another, and treat a third as a real product failure.

Route discovery turned out to be useful

I also added a machine-readable route discovery endpoint.

Originally this was mostly for internal convenience. I wanted one registry for routes, pricing, and validation metadata.

But it became useful for other reasons too:

docs generation
SDK helpers
machine-readable discovery for tools and agents
consistency between the gateway and the docs surface

If you are building APIs for software instead of humans alone, discoverability becomes much more important.

What still feels unresolved

I like this model more than I expected, but I do not think it answers everything.

A few open questions still feel real:

Is `402` intuitive enough?

I think it is elegant at the protocol level. I am less certain that it is immediately intuitive for most developers the first time they see it.

Is pay-per-request always the right fit?

Probably not. Some teams will still prefer API keys, quotas, and predictable monthly spend. That tradeoff does not disappear.

How much payment logic should the client know about?

I still think buyer-side signing is the right boundary, but there is a balancing act between giving the client enough control and making adoption too complex.

My current takeaway

The main thing I learned is that payment can be modeled as part of the request lifecycle, not just as an account-level concern.

That does not make subscriptions or API keys obsolete. But for agent-oriented workloads, I think there is real value in a model where:

each request can carry payment intent
the buyer controls signing
the gateway verifies before serving
the client can treat payment as a first-class transport step

That ended up feeling more natural for software-to-software usage than I expected.

If you want to see the product that came out of this experiment, MintAPI is the live implementation I used as the test bed for these ideas.

If you've worked on paid APIs, agent infrastructure, or protocol-level billing, I would be interested in your take: would you rather integrate a 402 flow like this, or stick with the usual API key + usage-plan model?

DEV Community: Max Holloway