{
  "schema_version": "v1",
  "protocol": "mcp-discovery",
  "name_for_human": "AgentPay x402 Facilitator API",
  "name_for_model": "agentpay_x402_facilitator",
  "description_for_human": "AgentPay is a production x402 payment facilitator on Base L2. Verify EIP-712 grants, settle USDC micropayments, create escrows, and register as a provider \u2014 all over standard HTTP. Built for autonomous AI agents. No API keys, no accounts, just USDC on Base.",
  "description_for_model": "Tools below are generated only from the operations in https://x402-agent-pay.com/openapi.json. Do not call a tool that is not in this list. Store catalog tools live at https://agentpaystore.com/mcp and are intentionally not repeated here.",
  "auth": {
    "type": "none",
    "note": "Paid operations challenge with HTTP 402 / x402 v2."
  },
  "api": {
    "type": "openapi",
    "url": "https://x402-agent-pay.com/openapi.json"
  },
  "source": {
    "openapi": "3.0.3",
    "info_version": "2.1.1",
    "operation_count": 22,
    "tools_sha256": "2dacab3da1457fee616966cdccc5e301faa9ee17ef03d8c4b8497929fdd18d40",
    "generated_at": 1790797134
  },
  "cache": {
    "max_age_seconds": 300,
    "etag_source": "tools_sha256"
  },
  "rate_limit": {
    "receive_address": {
      "route": "GET /api/agent/{agent_id}/receive-address",
      "scope": "per client IP and agent_id",
      "limit": 30,
      "window_seconds": 60,
      "applies_to": "unpaid address rotation lookups only",
      "exempt": [
        "/x402/verify",
        "/x402/settle",
        "/pay",
        "/escrow",
        "/release",
        "/refund",
        "/status/{payment_id}"
      ],
      "exempt_note": "Requests that carry PAYMENT-SIGNATURE, X-Payment-Signature, or X-Payment are not delayed, even on this route. POST/PUT/PATCH of the sibling receive-addresses registration is not limited."
    },
    "backoff": {
      "algorithm": "full jitter exponential backoff",
      "formula": "sleep = random_uniform(0, min(cap_seconds, base_seconds * 2 ** attempt))",
      "base_seconds": 0.5,
      "cap_seconds": 30,
      "honor": "Retry-After",
      "on_429": "Stop immediately. Sleep for the Retry-After value (seconds) if present, otherwise one full jitter step. Do not pipeline more receive-address calls for the same agent_id from the same client.",
      "on_success": "Reset the attempt counter to 0.",
      "do_not_retry": "Do not apply this loop to /x402/verify, /x402/settle, /pay, /escrow, /release, /refund, or /status/{payment_id}. A 402 there is a payment challenge, not overload."
    }
  },
  "settlement_exempt_paths": [
    "/x402/verify",
    "/x402/settle",
    "/pay",
    "/escrow",
    "/release",
    "/refund",
    "/status/{payment_id}"
  ],
  "not_included": [
    "AgentPayStore shop tools (live separately at https://agentpaystore.com/mcp)",
    "agentworld.me MCP tools",
    "Any operation absent from the facilitator OpenAPI file"
  ],
  "tools": [
    {
      "name": "wellKnownMcpDiscovery",
      "description": "Static JSON pointing at the live Streamable HTTP MCP URL, tool names, treasury payees, and related OpenAPI/x402 documents. An AgentPay convention, not a universal official MCP standard. Fetching this file does not open an MCP session.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/.well-known/mcp.json",
        "url": "https://x402-agent-pay.com/.well-known/mcp.json",
        "summary": "AgentPay MCP discovery document (not a live MCP server)",
        "payment_required": false
      }
    },
    {
      "name": "x402Discovery",
      "description": "Machine-readable discovery document listing all x402-payable endpoints, accepted assets, and payment requirements. This is how agents find and configure payments automatically.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/.well-known/x402",
        "url": "https://x402-agent-pay.com/.well-known/x402",
        "summary": "x402 discovery document",
        "payment_required": false
      }
    },
    {
      "name": "getEcosystem",
      "description": "Returns all registered API providers in the AgentPay ecosystem \u2014 name, description, endpoints, and payout wallet. Free to call. Use this for agent-to-agent discovery.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/api/agentpay/ecosystem",
        "url": "https://x402-agent-pay.com/api/agentpay/ecosystem",
        "summary": "List all registered providers",
        "payment_required": false
      }
    },
    {
      "name": "registerAgent",
      "description": "Self-registration endpoint for AI agents and API providers. Returns an api_key and endpoint_id instantly. No email verification required. Payout goes directly to your wallet address.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Agent or provider name"
              },
              "wallet": {
                "type": "string",
                "description": "Base L2 wallet address for payouts"
              },
              "agent_type": {
                "type": "string",
                "enum": [
                  "ai_agent",
                  "api_provider",
                  "human"
                ],
                "default": "ai_agent"
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "wallet"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/api/agentpay/register",
        "url": "https://x402-agent-pay.com/api/agentpay/register",
        "summary": "Register as an agent or API provider",
        "payment_required": false
      }
    },
    {
      "name": "getAnalytics",
      "description": "Returns settlement volume, call counts, and revenue breakdown for your partner account.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "partner_id": {
            "type": "string",
            "in": "query"
          },
          "api_key": {
            "type": "string",
            "in": "query"
          }
        },
        "additionalProperties": false,
        "required": [
          "partner_id",
          "api_key"
        ]
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/api/partner/analytics",
        "url": "https://x402-agent-pay.com/api/partner/analytics",
        "summary": "Get partner analytics",
        "payment_required": false
      }
    },
    {
      "name": "getPartnerBalance",
      "description": "Returns current claimable balance, total earned, payout wallet, and verification status for a partner.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "partner_id": {
            "type": "string",
            "in": "query"
          },
          "api_key": {
            "type": "string",
            "in": "query"
          }
        },
        "additionalProperties": false,
        "required": [
          "partner_id",
          "api_key"
        ]
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/api/partner/balance",
        "url": "https://x402-agent-pay.com/api/partner/balance",
        "summary": "Get partner balance and earnings",
        "payment_required": false
      }
    },
    {
      "name": "claimEarnings",
      "description": "Trigger a payout of claimable earnings to your registered wallet address. Minimum claim: $1.00 USDC.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "partner_id": {
                "type": "string"
              },
              "api_key": {
                "type": "string"
              }
            },
            "required": [
              "partner_id",
              "api_key"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/api/partner/claim",
        "url": "https://x402-agent-pay.com/api/partner/claim",
        "summary": "Claim earned USDC",
        "payment_required": false
      }
    },
    {
      "name": "listEndpoints",
      "description": "Returns all API endpoints registered under your partner account.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "partner_id": {
            "type": "string",
            "in": "query"
          },
          "api_key": {
            "type": "string",
            "in": "query"
          }
        },
        "additionalProperties": false,
        "required": [
          "partner_id",
          "api_key"
        ]
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/api/partner/endpoints",
        "url": "https://x402-agent-pay.com/api/partner/endpoints",
        "summary": "List your registered endpoints",
        "payment_required": false
      }
    },
    {
      "name": "createEndpoint",
      "description": "Add an x402-payable API endpoint to your provider listing. Agents can discover and pay for your endpoint via AgentPay.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "partner_id": {
                "type": "string"
              },
              "api_key": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "description": "Your x402-payable endpoint URL"
              },
              "price_usdc": {
                "type": "number",
                "description": "Price per call in USDC"
              },
              "description": {
                "type": "string"
              },
              "method": {
                "type": "string",
                "enum": [
                  "GET",
                  "POST",
                  "PUT",
                  "DELETE"
                ],
                "default": "POST"
              }
            },
            "required": [
              "partner_id",
              "api_key",
              "url",
              "price_usdc"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/api/partner/endpoints",
        "url": "https://x402-agent-pay.com/api/partner/endpoints",
        "summary": "Register a new endpoint",
        "payment_required": false
      }
    },
    {
      "name": "registerPartner",
      "description": "Register as an API provider in the AgentPay revenue pool. Providers earn a share of settlement fees based on volume. Supply a partner_id to claim your namespace.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "partner_id": {
                "type": "string",
                "description": "Unique namespace for your provider account"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "wallet": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "website": {
                "type": "string"
              }
            },
            "required": [
              "partner_id",
              "name",
              "wallet"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/api/partner/register",
        "url": "https://x402-agent-pay.com/api/partner/register",
        "summary": "Register as a revenue-share provider",
        "payment_required": false
      }
    },
    {
      "name": "createEscrow",
      "description": "Lock USDC in escrow for milestone-based agent jobs. Funds are held by the facilitator until /release is called by the payer or dispute resolution is triggered. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "payer": {
                "type": "string",
                "description": "Payer wallet address"
              },
              "payee": {
                "type": "string",
                "description": "Payee wallet address (agent or human)"
              },
              "amount_usdc": {
                "type": "number",
                "description": "Amount in USDC to lock"
              },
              "description": {
                "type": "string",
                "description": "Job or service description"
              },
              "payment_header": {
                "type": "string",
                "description": "x402 payment header to fund the escrow"
              }
            },
            "required": [
              "payer",
              "payee",
              "amount_usdc"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/escrow",
        "url": "https://x402-agent-pay.com/escrow",
        "summary": "Create a USDC escrow",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "get_facilitator_handshake",
      "description": "Runs the buyer's side of an x402 handshake: reads the endpoint's terms, confirms they are signable, calls the facilitator it names to see whether it answers /supported and /verify, prices settlement against live Base gas and Chainlink ETH/USD, and checks the wallet balance against the price. A missing facilitator is a warning, not a blocker; gas applies only to self-broadcast. Free, and it never sends a payment.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Full URL of the public x402 endpoint to probe.",
            "in": "query"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "default": "GET",
            "description": "The verb the endpoint expects.",
            "in": "query"
          },
          "wallet": {
            "type": "string",
            "description": "Optional 0x address; checks funding and self-broadcast headroom.",
            "in": "query"
          }
        },
        "additionalProperties": false,
        "required": [
          "url"
        ]
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/facilitator/handshake",
        "url": "https://x402-agent-pay.com/facilitator/handshake",
        "summary": "Can this wallet pay this endpoint right now (free)",
        "payment_required": false
      }
    },
    {
      "name": "facilitatorMcp",
      "description": "Live MCP transport (FastMCP Streamable HTTP, JSON responses, stateless). Call MCP initialize, notifications/initialized, tools/list and tools/call here. Tools x402_facilitator_verify and x402_facilitator_settle forward to the existing localhost /verify and /settle implementation. This is not GET /mcp (OpenAPI discovery JSON) and not /.well-known/mcp.json (static discovery document).",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "description": "MCP JSON-RPC message"
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/facilitator/mcp",
        "url": "https://x402-agent-pay.com/facilitator/mcp",
        "summary": "Streamable HTTP MCP endpoint for facilitator verify/settle tools",
        "payment_required": false
      }
    },
    {
      "name": "healthCheck",
      "description": "Returns 200 if the facilitator is online and connected to Base L2.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/health",
        "url": "https://x402-agent-pay.com/health",
        "summary": "Health check",
        "payment_required": false
      }
    },
    {
      "name": "submitPayment",
      "description": "Alias for /x402/settle. Accepts a signed x402 payment header and settles USDC on Base L2. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "payment_header": {
                "type": "string"
              },
              "resource": {
                "type": "string"
              },
              "partner_id": {
                "type": "string"
              }
            },
            "required": [
              "payment_header"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/pay",
        "url": "https://x402-agent-pay.com/pay",
        "summary": "Submit x402 payment (alias)",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "refundEscrow",
      "description": "Return locked USDC to the payer. Can be called by the payer before release, or by dispute resolution. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "escrow_id": {
                "type": "string"
              },
              "payer": {
                "type": "string",
                "description": "Payer wallet address"
              }
            },
            "required": [
              "escrow_id",
              "payer"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/refund",
        "url": "https://x402-agent-pay.com/refund",
        "summary": "Refund an escrow",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "releaseEscrow",
      "description": "Release locked USDC to the payee upon job completion. Must be called by the original payer. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "escrow_id": {
                "type": "string"
              },
              "payer": {
                "type": "string",
                "description": "Payer wallet \u2014 must match original escrow creator"
              }
            },
            "required": [
              "escrow_id",
              "payer"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/release",
        "url": "https://x402-agent-pay.com/release",
        "summary": "Release escrowed USDC",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "getPaymentStatus",
      "description": "Look up the on-chain settlement status of any payment by ID. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "description": "Payment ID returned by /pay or /x402/settle",
            "in": "path"
          }
        },
        "additionalProperties": false,
        "required": [
          "payment_id"
        ]
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/status/{payment_id}",
        "url": "https://x402-agent-pay.com/status/{payment_id}",
        "summary": "Check payment status",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "getProtocolInfo",
      "description": "Returns the facilitator's supported payment schemes, accepted assets, and network info. Use this to auto-configure an x402 client.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/x402/info",
        "url": "https://x402-agent-pay.com/x402/info",
        "summary": "Protocol info and payment requirements",
        "payment_required": false
      }
    },
    {
      "name": "settlePayment",
      "description": "Submit and settle a USDC payment via EIP-3009 transferWithAuthorization on Base L2. This is the full settlement call \u2014 verifies the grant and executes on-chain in one step. Payment challenge uses x402 v2 (402 + PAYMENT-REQUIRED). This manifest does not settle and does not fabricate a payment tool.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "payment_header": {
                "type": "string",
                "description": "Base64-encoded EIP-712 signed grant"
              },
              "resource": {
                "type": "string"
              },
              "partner_id": {
                "type": "string",
                "description": "Optional \u2014 routes revenue share to a provider"
              }
            },
            "required": [
              "payment_header"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/x402/settle",
        "url": "https://x402-agent-pay.com/x402/settle",
        "summary": "Settle an x402 payment on-chain",
        "payment_required": true,
        "payment_headers": [
          "PAYMENT-SIGNATURE",
          "X-Payment-Signature",
          "X-Payment"
        ]
      }
    },
    {
      "name": "getStats",
      "description": "Returns total settlements, USDC volume, active escrows, and fees collected. Free to call.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "x-agentpay": {
        "method": "GET",
        "path": "/x402/stats",
        "url": "https://x402-agent-pay.com/x402/stats",
        "summary": "Live settlement statistics",
        "payment_required": false
      }
    },
    {
      "name": "verifyPayment",
      "description": "Verify an incoming EIP-712 signed x402 payment grant. Returns whether the payment is valid and sufficient for the requested resource. Free to call.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "body": {
            "type": "object",
            "properties": {
              "payment_header": {
                "type": "string",
                "description": "Base64-encoded x402 payment header (EIP-712 signed)"
              },
              "resource": {
                "type": "string",
                "description": "URL of the resource being paid for"
              },
              "required_amount": {
                "type": "string",
                "description": "Required amount in USDC atomic units (6 decimals)"
              }
            },
            "required": [
              "payment_header",
              "resource"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "body"
        ]
      },
      "x-agentpay": {
        "method": "POST",
        "path": "/x402/verify",
        "url": "https://x402-agent-pay.com/x402/verify",
        "summary": "Verify an x402 payment grant",
        "payment_required": false
      }
    }
  ]
}