Comparing APIs on Settlement Rail Before Ranking

Comparing APIs on settlement rail starts with a practical question: can the agent complete the payment path attached to this offer? A cheaper endpoint is not cheaper in operation when the buyer cannot authorize, verify, settle, or record the payment it requires.

That makes settlement an eligibility dimension before it becomes comparison context. Two providers may perform the same job and accept the same inputs. If one uses a path the buyer has approved and the other requires a direct path the buyer cannot operate, only one is a usable candidate.

A settlement rail changes the work around the call

An API comparison usually begins with the visible service dimensions: price, measured latency, measured success rate, and input compatibility. Settlement is easy to push into a footnote because it does not describe the result returned by the endpoint.

The rail still changes what the buyer must do. It determines where payment requirements come from, which party verifies the authorization, how settlement is submitted, and what evidence comes back with the paid response. In x402, the server presents one or more payment requirements and the client selects an accepted option. The scheme and network tell the client how to form the payment payload; the resource server or a facilitator then verifies and settles it according to that mechanism.

Those are execution conditions, not descriptive metadata. If the client does not support the required mechanism, it cannot turn the listing into a paid call. A row that hides the rail until after ranking can therefore name a winner that the agent is unable to buy from.

Filter for an executable path before ranking

Settlement belongs with the hard requirements that define the eligible candidate set. The buying system should establish that requirement before discovery and carry it unchanged through comparison and decision.

The minimum checks are concrete:

• The offer exposes payment requirements the client can parse.
• The client supports the scheme and network pair returned for the resource.
• The buyer's policy permits the required settlement path.
• The authorization can be formed without an unapproved manual step.
• The response provides enough settlement evidence for the buyer's records.
• The same settlement requirement reaches discovery, comparison, and decision.

This is the same discipline used by requirement contracts for agent API calls. In Apiosk, `settlement=apiosk|direct` is one of the shared requirement parameters. If the buyer requires one path, a candidate on the other path should be excluded. It should not receive a slightly lower score and remain eligible.

Only after that filter runs should the comparison order the survivors. Price cannot compensate for an unsupported payment path, just as low latency cannot compensate for missing required inputs.

Do not collapse settlement into price

Price and settlement answer different questions. Price states how much the unit of work costs. Settlement describes how the buyer's payment obligation is verified and completed.

Combining them into one opaque cost column destroys useful evidence. A provider can be cheaper but require a path outside the buyer's approved controls. Another can have the same stated price but fit the buyer's existing payment client and recordkeeping. The buyer needs both facts separately to explain why one offer was excluded and another was ranked.

This separation also keeps the API comparison matrix honest. The settlement column establishes whether the row can participate under the current requirement. The scoring columns then compare eligible candidates on the dimensions available for that request.

Do not copy a list of supported chains, assets, or prices into the buying policy and assume it remains current. Those terms change. Read the payment requirements the gateway returns, and treat `https://gateway.apiosk.com/.well-known/x402` as Apiosk's live source for its payment terms.

The rail affects failure handling and evidence

The payment path determines more than the happy path. It also shapes the failure an operator has to diagnose.

A buyer needs to distinguish a provider failure from a payment failure. An invalid authorization, expired requirement, unsupported mechanism, unsuccessful settlement, and endpoint error do not have the same remedy. The settlement response and its identifiers let the client decide whether to retry payment, choose another eligible provider, or stop before creating a duplicate charge.

That evidence matters after the call too. A decision record can explain that a candidate was removed because it failed the settlement requirement. The paid response can then support a separate record that the selected path completed. Keeping those facts distinct prevents a routing explanation from being mistaken for proof of payment.

The x402 specification is also expanding beyond one settlement behavior. Different schemes can move value immediately, authorize up to a maximum, or retain a commitment for later redemption. A buyer does not need to turn every mechanism into one generic label. It needs to know which mechanism the offer presents, whether its client supports it, and whether its operating policy permits it.

Compare the remaining candidates transparently

Once settlement has removed incompatible offers, Apiosk compares the reviewed candidates on price, measured latency, measured success rate, and input compatibility. Each candidate receives a relative 0–100 score for that comparison, with the active weights and per-dimension contributions returned beside it.

The score is not a permanent grade. It depends on the candidates in that one request. The evidence needed for recomputing an API score therefore travels with the result rather than living in a general methodology page.

Missing measurements remain visible. A dimension Apiosk has not measured for a candidate is dropped from its weighting and named, never scored zero. Result quality and provider terms are not measured anywhere. Settlement eligibility does not fill those gaps; it only establishes that the buyer can execute the payment path for the offer being compared.

External x402 hits stay outside this process. Discovery can return them in `external_candidates`, but they have no `candidate_id`, are unreviewed and unmeasured, and are not settleable through Apiosk. They cannot enter `/v1/compare` or `/v1/decide` merely because they advertise a recognizable rail.

Where Apiosk fits

Apiosk carries `settlement=apiosk|direct` through `GET /v1/discover`, `GET /v1/compare`, and `GET /v1/decide` with the buyer's other requirements. Discovery returns stable candidate IDs. Comparison shows the eligible candidates side by side. Decision returns one provider, the rule that selected it, each rejected candidate with the exact failed constraint, and the runners-up in order.

The role is narrow: Apiosk makes the settlement requirement explicit before ranking and keeps the resulting comparison checkable. It does not replace the gateway's live payment terms or claim to measure provider terms and result quality.

If you run a paid endpoint, publish payment requirements a client can act on and keep the live gateway document current. List your API for reviewed comparison so an agent can find the offer, test it against an approved settlement path, and compare it only with candidates it can actually buy from.