{
  "openapi": "3.1.0",
  "info": {
    "title": "x402 Counterparty Score",
    "version": "1.0.0",
    "description": "Decision-grade counterparty scores for the x402 ecosystem, served to AI agents over MCP (Model Context Protocol) with per-call x402 payments (USDC). Input an x402 endpoint URL or pay-to address; output is a trust verdict (trusted/caution/avoid) with wash-trading ratio, real-buyer count, repeat-buyer rate, and provenance fields (source, updated_at, confidence). Scoring rules are deterministic and publicly documented at /methodology."
  },
  "servers": [
    {
      "url": "/",
      "description": "Same origin as this document. All paths are origin-relative; the deployed origin serving this file is the service origin."
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "MCP JSON-RPC 2.0 endpoint (Streamable HTTP)",
        "description": "Send MCP JSON-RPC 2.0 messages (initialize, tools/list, tools/call). The machine-readable tool contract is duplicated in x-mcp.tools of this document and verified byte-for-byte against the live shelf by an automated test. Calling the paid tool without payment returns an in-band quote in the tool result's _meta[\"x402/error\"]; see x-x402-payment-flow.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "A JSON-RPC 2.0 request, notification, response, or batch (MCP Streamable HTTP).",
                "type": ["object", "array"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC 2.0 response. Tool errors are in-band: error envelopes carry a machine-readable next step (recovery instructions, retry_after, free_alternative) and settle no payment."
          },
          "202": {
            "description": "Accepted (JSON-RPC notification; no response body)."
          }
        }
      },
      "get": {
        "operationId": "mcpNotificationStream",
        "summary": "Optional SSE notification stream — not offered",
        "description": "This server does not offer the optional MCP SSE notification stream. GET returns 405 with an Allow header (POST, DELETE) and machine-readable instructions to send JSON-RPC requests via POST instead.",
        "responses": {
          "405": {
            "description": "Method not allowed. Body: { \"error\": \"METHOD_NOT_ALLOWED\", \"instructions\": \"...use POST /mcp...\" }"
          }
        }
      },
      "delete": {
        "operationId": "mcpEndSession",
        "summary": "Terminate the MCP session",
        "description": "Ends the MCP session identified by the mcp-session-id header, per MCP Streamable HTTP.",
        "responses": {
          "default": {
            "description": "Session termination result per MCP Streamable HTTP."
          }
        }
      }
    }
  },
  "x-mcp": {
    "endpoint": "/mcp",
    "transport": "streamable-http",
    "tools": [
      {
        "name": "score_x402_counterparty",
        "description": "Returns trust verdict (trusted/caution/avoid) with wash-trading ratio, real-buyer count, and repeat-buyer rate for an x402 endpoint URL or pay-to address. $0.02/call. Updated daily from Base on-chain settlement data and the x402 Bazaar catalog.",
        "payment": {
          "required": true,
          "price_usd": 0.02,
          "note": "Paid per successful call via x402 (see x-x402-payment-flow). The in-band 402 quote is authoritative for price, asset, network, and pay-to address. Error envelopes settle no payment."
        },
        "inputSchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "type": "object",
          "properties": {
            "subject": {
              "description": "The counterparty to score: an x402 endpoint URL (e.g. \"https://api.seller.example/quote\") or a pay-to address (e.g. \"0x036C…\"), exactly as advertised in the x402 Bazaar catalog or the 402 handshake.",
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            }
          },
          "required": ["subject"]
        },
        "outputSchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "type": "object",
          "properties": {
            "subject": {
              "description": "The x402 endpoint URL or pay-to address this score is about.",
              "type": "string"
            },
            "verdict": {
              "description": "Decision-grade trust verdict on the counterparty.",
              "type": "string",
              "enum": ["trusted", "caution", "avoid"]
            },
            "wash_trading_ratio": {
              "description": "Share of nominal settlement volume attributed to wash trading (self-dealing or funding-loop patterns), 0 to 1.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "real_buyer_count": {
              "description": "Number of distinct real buyers after wash-trading filtering.",
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "repeat_buyer_rate": {
              "description": "Share of real buyers that purchased more than once, 0 to 1.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "source": {
              "description": "Origin of the underlying data, e.g. \"base-settlements\" or \"bazaar-directory\".",
              "type": "string"
            },
            "updated_at": {
              "description": "ISO 8601 UTC timestamp of when this score was computed.",
              "type": "string"
            },
            "confidence": {
              "description": "Objective confidence from rule coverage and data completeness, 0 to 1. Never self-reported by an LLM.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "required": [
            "subject",
            "verdict",
            "wash_trading_ratio",
            "real_buyer_count",
            "repeat_buyer_rate",
            "source",
            "updated_at",
            "confidence"
          ],
          "additionalProperties": false
        }
      },
      {
        "name": "get_sample_score",
        "description": "Returns a clearly-marked stale sample counterparty score in the exact response schema of score_x402_counterparty (verdict, wash_trading_ratio, real_buyer_count, repeat_buyer_rate, source, updated_at, confidence). Free, no payment required, no input required. Sample data is fixed and expired by design — use it to validate response parsing, then call score_x402_counterparty ($0.02/call) for fresh decision-grade scores.",
        "payment": {
          "required": false,
          "price_usd": 0,
          "note": "Free teaser: validate response parsing and schema at zero cost before paying for live scores."
        },
        "inputSchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "type": "object",
          "properties": {}
        },
        "outputSchema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "type": "object",
          "properties": {
            "subject": {
              "description": "The x402 endpoint URL or pay-to address this score is about.",
              "type": "string"
            },
            "verdict": {
              "description": "Decision-grade trust verdict on the counterparty.",
              "type": "string",
              "enum": ["trusted", "caution", "avoid"]
            },
            "wash_trading_ratio": {
              "description": "Share of nominal settlement volume attributed to wash trading (self-dealing or funding-loop patterns), 0 to 1.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "real_buyer_count": {
              "description": "Number of distinct real buyers after wash-trading filtering.",
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "repeat_buyer_rate": {
              "description": "Share of real buyers that purchased more than once, 0 to 1.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "source": {
              "description": "Origin of the underlying data, e.g. \"base-settlements\" or \"bazaar-directory\".",
              "type": "string"
            },
            "updated_at": {
              "description": "ISO 8601 UTC timestamp of when this score was computed.",
              "type": "string"
            },
            "confidence": {
              "description": "Objective confidence from rule coverage and data completeness, 0 to 1. Never self-reported by an LLM.",
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "sample": {
              "description": "Always true: this response is a sample, not a live score.",
              "type": "boolean",
              "const": true
            },
            "sample_notice": {
              "description": "Machine-readable warning that the data is stale sample data.",
              "type": "string"
            }
          },
          "required": [
            "subject",
            "verdict",
            "wash_trading_ratio",
            "real_buyer_count",
            "repeat_buyer_rate",
            "source",
            "updated_at",
            "confidence",
            "sample",
            "sample_notice"
          ],
          "additionalProperties": false
        }
      }
    ]
  },
  "x-x402-payment-flow": {
    "protocol": "x402",
    "currency": "USDC",
    "quote": "Calling the paid tool without payment returns the tool result with _meta[\"x402/error\"]: an envelope whose `accepts` array lists payment requirements (scheme, network, asset, pay-to address, amount) plus machine-readable retry instructions.",
    "pay": "Sign a payment authorization for one entry of `accepts`, base64-encode the x402 payment payload JSON, and call this tool again with it in request params._meta[\"x402/payment\"]. x402-aware MCP clients (e.g. agents/x402 withX402Client) do this automatically.",
    "settle": "The server verifies and settles the payment via an x402 facilitator before returning the answer. If the tool returns an error envelope (payment_settled: false), no payment is settled: you are never charged for an unavailable answer.",
    "authoritative_quote": "The in-band 402 quote is authoritative for price, asset, network, and pay-to address. The listed $0.02/call is the currently configured price."
  },
  "x-error-envelopes": {
    "ANSWER_UNAVAILABLE": "503 semantics: no fresh answer for this subject (missing, delisted, or older than 24h; stale answers are never sold). Envelope carries recovery.retry_after (next refresh), recovery.instructions, and free_alternative: get_sample_score. No payment settled.",
    "TOOL_DELISTED": "503 semantics: the tool is temporarily delisted by the operator; the check runs before any payment step, so no payment is settled.",
    "METHOD_NOT_ALLOWED": "HTTP 405 on GET /mcp: the optional SSE notification stream is not offered; send JSON-RPC via POST."
  },
  "x-documentation": {
    "landing": "/",
    "methodology": "/methodology",
    "llms_txt": "/llms.txt"
  }
}