Skip to main content
Glama

Check an x402 payment before paying

check_payment
Read-onlyIdempotent

Decide whether a specific x402 payment should go through: returns allow true/false with reasons. Checks the endpoint's trust verdict, that the amount is within your cap and not above the monitored price, and that the payTo wallet matches the one we've observed (catches swapped or hijacked wallets). Optionally (minOrganicShare) it also requires that enough of the seller's volume comes from independent buyers. Intended for right before a payment, with the amount, payTo, and network from the endpoint's 402 quote; allow is true only when every rule passes. Use check_endpoint instead if you only want an endpoint's grade without a quote in hand. Read-only and free; it doesn't make or block the payment itself. When allow is false, the reasons list explains why. API docs: https://github.com/Book0fEli/lumiere-paycheck/blob/main/docs/api.md

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesFull URL of the x402 endpoint you are about to pay, including path
payToNoWallet address from the endpoint's 402 quote
amountNoAmount about to be paid, atomic units (USDC has 6 decimals: 10000 = $0.01)
networkNoNetwork from the quote, e.g. eip155:8453
hasAccessNotrue if you have your own account, API key or sign-in with this seller. For endpoints that need the seller's sign-in on top of x402, allowCaution/requireVerified then don't block (we couldn't confirm delivery only because we can't sign in).
maxAmountNoYour hard cap for this payment in atomic units (USDC: 1000000 = $1). Payments above it are denied.
allowCautionNofalse = deny endpoints with a caution verdict too, not just avoid (default true)
priceToleranceNoOptional, 0-0.5 (default 0.02 = 2%): how far above the endpoint's recent prices still counts as the same price, for sellers whose price drifts (pegged to BTC, gas or FX). Bigger jumps are denied as overcharges.
minOrganicShareNoOptional, 0-1: deny sellers where less than this share of 30-day volume comes from independent buyers (e.g. 0.5). Not applied to sellers whose buyers haven't been reviewed yet.
requireVerifiedNotrue = only allow endpoints that delivered on a real test payment (default false)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNo
allowYesPay only when true
gradeNo
notesNo
scoreNo
buyersNoWho is really behind the seller's buyers. Never changes the grade.
valuesNoAutomatic value checks on the latest paid response
listingNoPresent only when the latest paid response differs from the listing's example or schema. The data is delivered.
reasonsYesWhy it was allowed or denied
verdictNoproceed | caution | avoid | free | insufficient_data
deliveryNo
forTeamsNoShort note about team plans (per-agent keys, spend limits, audit trail)
observedNoThe latest payment quote our monitor saw
monitoredYesWhether the endpoint is in the monitored catalog
payToModeNo
reviewableNoDenied only for reasons a person may approve
afterPayingNoHow to report the outcome after paying (free, verified on-chain)
authRequiredNotrue: the seller needs its own sign-in on top of x402; send hasAccess: true if you have it
buyerReportsNoWhat real buyers reported after paying. Never changes the grade; confirmations move the endpoint up our paid-test queue.
gradeReasonsNoEvery factor behind the endpoint's grade (same as check_endpoint's reasons)
declaredPayToNoPayout wallets the seller declared itself
gradeHeadlineNoWhy the endpoint has its grade, in one sentence
walletUnconfirmedNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / priceTolerance
      Added value: +{
      +  "description": "Optional, 0-0.5 (default 0.02 = 2%): how far above the endpoint's recent prices still counts as the same price, for sellers whose price drifts (pegged to BTC, gas or FX). Bigger jumps are denied as overcharges.",
      +  "maximum": 0.5,
      +  "minimum": 0,
      +  "type": "number"
      +}
  2. Changed2 schema fields changed
    • addedOutput schema / properties / gradeHeadline
      Added value: +{
      +  "description": "Why the endpoint has its grade, in one sentence",
      +  "type": "string"
      +}
    • addedOutput schema / properties / gradeReasons
      Added value: +{
      +  "description": "Every factor behind the endpoint's grade (same as check_endpoint's reasons)",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "at": {
      +        "description": "Date of the event it's based on (YYYY-MM-DD)",
      +        "type": "string"
      +      },
      +      "effect": {
      +        "description": "positive, neutral or negative",
      +        "type": "string"
      +      },
      +      "factor": {
      +        "description": "data, delivery, uptime, speed, wallet, price, listing, values, access or withdrawn",
      +        "type": "string"
      +      },
      +      "limit": {
      +        "description": "The ceiling this factor puts on the grade, e.g. \"F (max 39)\"",
      +        "type": "string"
      +      },
      +      "text": {
      +        "description": "What we found, in plain words (paid-test results include the date and what came back)",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "factor",
      +      "effect",
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  3. Changed2 schema fields changed
    • addedInput schema / properties / hasAccess
      Added value: +{
      +  "description": "true if you have your own account, API key or sign-in with this seller. For endpoints that need the seller's sign-in on top of x402, allowCaution/requireVerified then don't block (we couldn't confirm delivery only because we can't sign in).",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / authRequired
      Added value: +{
      +  "description": "true: the seller needs its own sign-in on top of x402; send hasAccess: true if you have it",
      +  "type": "boolean"
      +}
  4. Changed3 schema fields changed
    • addedOutput schema / properties / afterPaying
      Added value: +{
      +  "description": "How to report the outcome after paying (free, verified on-chain)",
      +  "type": "string"
      +}
    • addedOutput schema / properties / buyerReports
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "What real buyers reported after paying. Never changes the grade; confirmations move the endpoint up our paid-test queue.",
      +  "properties": {
      +    "confirmed": {
      +      "description": "Buyers (customers or wallets) who reported a usable response in 7 days",
      +      "type": "number"
      +    },
      +    "note": {
      +      "type": "string"
      +    },
      +    "ourTestQueued": {
      +      "description": "Our own paid test is queued for this endpoint",
      +      "type": "boolean"
      +    },
      +    "problems": {
      +      "description": "Buyers who reported a problem in 7 days",
      +      "type": "number"
      +    },
      +    "windowDays": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "confirmed",
      +    "problems",
      +    "ourTestQueued",
      +    "windowDays",
      +    "note"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / values
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Automatic value checks on the latest paid response",
      +  "properties": {
      +    "checked": {
      +      "type": "boolean"
      +    },
      +    "warning": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "checked"
      +  ],
      +  "type": "object"
      +}
  5. Changed3 schema fields changed
    • changedOutput schema / properties / listing / description
      Previous value: -"Present only when the latest paid response doesn't match the listing's example. The data is delivered; the grade is capped at B until the listing matches."New value: +"Present only when the latest paid response differs from the listing's example or schema. The data is delivered."
    • addedOutput schema / properties / listing / properties / capped
      Added value: +{
      +  "description": "true: the data is reshaped vs the listing (nested, list vs item), grade capped at B; false: a minor gap, warning only",
      +  "type": "boolean"
      +}
    • changedOutput schema / properties / listing / properties / sellerFix / description
      Previous value: -"What the seller changes to lift the B cap"New value: +"What the seller can change"
  6. Changed1 schema field changed
    • addedOutput schema / properties / listing
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Present only when the latest paid response doesn't match the listing's example. The data is delivered; the grade is capped at B until the listing matches.",
      +  "properties": {
      +    "matchesExample": {
      +      "description": "false: the paid response differs from the seller's own example",
      +      "type": "boolean"
      +    },
      +    "sellerFix": {
      +      "description": "What the seller changes to lift the B cap",
      +      "type": "string"
      +    },
      +    "warning": {
      +      "description": "How the real response differs, and where to read the fields",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "matchesExample",
      +    "warning",
      +    "sellerFix"
      +  ],
      +  "type": "object"
      +}
  7. Changed2 schema fields changed
    • addedInput schema / properties / minOrganicShare
      Added value: +{
      +  "description": "Optional, 0-1: deny sellers where less than this share of 30-day volume comes from independent buyers (e.g. 0.5). Not applied to sellers whose buyers haven't been reviewed yet.",
      +  "maximum": 1,
      +  "minimum": 0,
      +  "type": "number"
      +}
    • addedOutput schema / properties / buyers
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Who is really behind the seller's buyers. Never changes the grade.",
      +  "properties": {
      +    "buyerWallets30d": {
      +      "description": "Buyer wallets that paid the seller in 30 days",
      +      "type": "number"
      +    },
      +    "estimated": {
      +      "description": "true when counted from a sample of buyers",
      +      "type": "boolean"
      +    },
      +    "flags": {
      +      "description": "coordinated_wallets, self_funded, concentrated_buyers, shared_operator, estimated, partial_lookup",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "independentBuyers30d": {
      +      "description": "Independent buyers behind the seller's buyer wallets in 30 days (wallets funded from one source count as one)",
      +      "type": "number"
      +    },
      +    "organicShare": {
      +      "description": "0-1: share of 30-day volume from independent buyers",
      +      "type": "number"
      +    },
      +    "reviewed": {
      +      "description": "false until the seller's buyers have been reviewed (the biggest sellers are reviewed daily)",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "reviewed"
      +  ],
      +  "type": "object"
      +}
  8. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior the annotations cannot: it is free, it does not make or block the payment itself, allow is true only when every rule passes, and the reasons list explains a false result. It also discloses the rule set being evaluated (trust verdict, cap, monitored price, payTo match, optional organic-share).

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?

Front-loaded with the core decision and the rule list, and every sentence carries new information (rules, optional rule, usage timing, alternative, safety profile, false-case behavior, docs link). It is dense and slightly long for a single paragraph, but there is no filler to cut.

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 an output schema present, return values need not be re-explained, yet the description still summarizes allow/reasons. For a 10-parameter decision tool it covers the decision logic, the preconditions, the alternative sibling, and a docs link — nothing an agent needs to invoke it correctly is missing.

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; the description earns above that by framing three parameters in context (amount/payTo/network come from the 402 quote) and by naming minOrganicShare with its intent. It still leaves maxAmount, allowCaution, and requireVerified entirely to the schema, so it does not fully substitute for per-parameter reading.

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 precise verb+resource ('Decide whether a specific x402 payment should go through') and immediately describes the return shape (allow true/false with reasons). It explicitly distinguishes itself from the sibling check_endpoint, so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

Gives the exact moment to use it ('right before a payment, with the amount, payTo, and network from the endpoint's 402 quote') and names the alternative with the condition that selects it ('Use check_endpoint instead if you only want an endpoint's grade without a quote in hand'). Both when-to-use and when-to-use-something-else are explicit.

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.