Skip to main content
Glama

Surface Contract: platform API behavior and x402 pre-payment checks

prepay_check

Check an x402 route BEFORE you pay it. GET /v1/prepay?url= makes ONE unpaid GET with no payment header and no credential, and returns one row: the measured HTTP status, the parsed x402 v2 challenge (scheme / network / asset / amount / payTo), whether that challenge is schema-valid exact-on-Base, and whether its payTo and price agree with the seller's own card (pass card to read that card with one more unpaid GET). No payment is made, no credential is sent, no redirect is followed, and a transport failure on our side is reported as unknown rather than as a fact about the seller. Use it to gate a payment decision on measured terms instead of on a seller's prose.

Input Schema

NameRequiredDescriptionDefault
urlYesabsolute https URL of the route you are about to pay
cardNooptional: absolute https URL of the seller's own card/listing page, read with one more unpaid GET to compare the wallet and the price it advertises (agreement is true|false|unknown, and unknown is null, never false)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden and does so richly: exactly ONE unpaid GET, no payment header, no credential, no redirect followed, and transport failure on the server side is reported as 'unknown' rather than as a fact about the seller. It also enumerates what the returned row contains, which is the behavioral detail an agent needs to trust the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first short sentence and nothing is filler, but the second sentence is an unusually long chain of clauses that packs return shape, safety guarantees, and failure semantics into one breath. Dense but still parseable, so slightly below ideal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description must define both the safety profile and the return payload, and it does: it lists the measured status, the parsed x402 v2 challenge fields, schema-validity, and card agreement semantics. An agent has everything needed to interpret a result and to decide whether to pay.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the schema already documents both `url` and `card`. The description adds decision-level meaning by framing `card` as reading the seller's advertised wallet/price with one more unpaid GET so the agent understands why it would supply the optional parameter, a modest increment over the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Check an x402 route') plus its timing constraint ('BEFORE you pay it') and the exact operation behind it (GET /v1/prepay?url=...). This is clearly distinct from the sibling tools about surface contracts and MCP preflight, so an agent can route to it without opening any other schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit use case: 'Use it to gate a payment decision on measured terms instead of on a seller's prose,' which tells the agent this is a pre-payment verification step. It does not name a concrete alternative tool or a when-not-to-use condition, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources