x402 vs API keys and subscriptions: when pay-per-request makes sense

The question of x402 vs API keys and subscriptions is not about which model is newer. Each one makes different assumptions about who your caller is and how often they come back, and for a lot of APIs the honest answer is "both". This guide compares them fairly, says plainly where keys and plans are still the better choice, and shows how to run them side by side on one Laravel API.

What each model asks of the caller#

API keys with a subscription or prepaid plan. A person signs up, agrees to terms, adds a card, picks a plan and copies a key. From then on every request carries the key, you look up the account, check its quota, and bill monthly or draw down credit. The caller is known before the first request.

x402. The caller asks for the resource. The server answers 402 Payment Required with a machine-readable price. The caller signs a USDC payment for exactly that amount and retries with a PAYMENT-SIGNATURE header. The server verifies it, serves the response and settles the transfer through a facilitator. The caller is unknown until it pays, and after it pays you know a wallet address, nothing more. The x402 overview walks through the headers.

The difference is when trust is established. Keys establish it up front, once, through a human process. x402 establishes it per request, through a signature.

Side by side#

Neither column wins outright. The table is mostly a list of trade-offs between knowing your customer and not needing to.

Where x402 is the better fit#

Callers you have never met. An agent working through a task finds your endpoint, needs one answer, and will never come back. Nobody is going to fill in a signup form for that, and you do not want an account per one-off caller. x402 turns that request into revenue instead of a bounce.

Spiky or long-tail usage. A subscription only makes sense to the buyer if they will use it enough. Callers who need ten requests this month and none next month are poorly served by plans, and often just do not buy one. Per-request pricing lets them pay for exactly what they used.

Endpoints with very different costs. With keys, an expensive endpoint and a cheap one usually draw down the same quota at some exchange rate. With x402 each route carries its own price, and the Laravel package can compute one per request with X402::priceUsing(). The pricing guide covers how to set those numbers.

No credentials to manage. There is no key to store, rotate or leak on the agent side, only a wallet. Agents are advised to use a dedicated low-balance wallet, which caps what a compromised agent can spend. On your side there is no private key either: the server needs a receiving address, not a key.

Where API keys or subscriptions are better#

Being honest about this is what makes the rest of the comparison useful.

Steady, high-volume customers. A business making a large, predictable number of requests every day wants a contract, a negotiated rate and one invoice. Per-request settlement adds work for both sides with no benefit.

You need to know the customer. Support, SLAs, per-customer rate limits, usage reports and account management all assume an identity. A wallet address is not one. If your API requires terms of service to be accepted or usage to be tied to an organisation, keys fit better.

Predictable revenue matters more than reach. Recurring plans give you a number you can plan around. Pay-per-request revenue moves with usage.

People, not agents, are the buyers. A developer evaluating your API in a browser expects a dashboard, a card form and a key. x402 is designed for software that pays for itself. For humans, use normal checkout.

Refunds and credit are part of the product. If you routinely refund failed jobs or extend credit, a billing system does that naturally. x402 payments are irreversible once settled.

Latency-critical tight loops. In the Laravel package's default before_response mode the request waits for verification and settlement before responding. after_response mode responds before settling, at the cost of a window where a served response can fail to settle. A key lookup is cheaper than either. Most endpoints will not notice; a few will.

Running both on one Laravel API#

You do not have to choose per API. With requestway/laravel-x402, a route can charge unknown agents with x402 and serve your existing customers through the keys or sessions they already use. Requests matching a bypass rule are served free, and the response carries an X-X402-Bypass header naming the rule that matched, so "why wasn't this charged?" always has an answer.

Customers with API keys#

Existing customers who pay you another way keep sending their key. Configure the header and the accepted keys:

X402_API_KEY_HEADER=X-API-Key
X402_API_KEYS=key_for_customer_a,key_for_customer_b

X-API-Key is the default header. Keys are compared with hash_equals. A request with a valid key skips payment; a request without one gets the 402 like any other caller.

Signed-in users#

If your web app's users call the same endpoints, let them through per route:

Route::get('/report', ReportController::class)->middleware('x402:0.25,free-for-auth');

Or exempt signed-in users everywhere with X402_FREE_FOR_AUTH=true, and use paid-for-auth on the specific routes that should charge them anyway.

Your own infrastructure#

Monitoring, health checks and internal services should never pay. Allowlist their IPs or CIDR ranges:

X402_BYPASS_IPS=203.0.113.4,10.0.0.0/8

Anything else: a closure#

When the rule depends on your own data, such as a prepaid credit balance or an active subscription, use a closure:

use Requestway\X402\Facades\X402;

X402::bypassUsing(fn (Request $request, RoutePayment $route): bool
    => $request->user()?->hasCredits() === true);

Here hasCredits() stands for whatever your own user model uses to decide that someone has already paid. Subscribers are served from their plan; everyone else sees the x402 price.

Run php artisan x402:routes to see every paid route with its price and bypass rules, and test the bypass the same way you test payments:

it('does not charge our own monitoring', function () {
    X402::fake();
    config()->set('x402.bypass.ips', ['127.0.0.1']);

    $this->getJson('/report')->assertOk();

    X402::assertNotCharged();
});

On Node, the official @x402/express, @x402/next and @x402/hono middleware protects the routes you list in its route map, so one way to get the same split is to serve key holders on a route your key middleware guards and leave it out of that map. The Node guide shows the payment side.

Decide with data#

If you are not sure whether agents will pay for an endpoint your subscribers already use, do not guess. Set X402_MODE=observe and nothing is charged: every request that would have been charged is recorded with status = observed, and the response carries an X-X402-Would-Charge header. After a week or two you know how much traffic the route gets and what it would have earned at your price.

Requestway shows that as would-be revenue per route, next to settled earnings once you switch to enforce, so you can see whether x402 is adding revenue or only shifting it. The observe mode guide explains the method, the install guide covers setup, and you can create a free account to track it.

FAQ#

Can I accept both API keys and x402 payments on the same endpoint?#

Yes. With the Laravel package, configure X402_API_KEYS and requests carrying a valid key in the X-API-Key header are served free, while everyone else gets the 402. The response includes an X-X402-Bypass header naming the rule that matched.

Do AI agents need an account to pay with x402?#

No. The agent needs a wallet holding USDC on a network the API accepts. It reads the price from the 402, signs a payment and retries; no signup, key or card is involved.

Do x402 payments support refunds?#

Settled payments are irreversible on chain. If you want to give money back, that is a separate transfer you send yourself. If refunds are a normal part of your product, a billing system with keys is the better fit for those customers.

Is pay-per-request cheaper than a subscription for the caller?#

It depends on usage. As an example, at $0.01 per request a caller making 500 requests a month pays $5; one making 50,000 pays $500, and would probably prefer a plan. That is why running both models side by side often makes sense.