{
  "openapi": "3.0.3",
  "info": {
    "title": "AgentPay x402 Facilitator API",
    "description": "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.\n\n**Treasury:** `0x367F1b3D8Ca90D1e087481a9A40d585Bf3451a03`\n**Network:** Base Mainnet (eip155:8453)\n**Fee:** $0.02 USDC flat per settlement\n**Settlement time:** <2 seconds average",
    "version": "2.1.0",
    "contact": {
      "name": "AgentPay Team",
      "url": "https://x402-agent-pay.com",
      "email": "support@x402-agent-pay.com"
    },
    "license": {
      "name": "MIT"
    },
    "x-logo": {
      "url": "https://x402-agent-pay.com/logo.png"
    },
    "x-guidance": "AgentPay is an x402 payment facilitator on Base L2. To settle a payment: POST /x402/settle with an EIP-712 signed payment header. To create escrow: POST /escrow. To register as a provider or agent: POST /api/agentpay/register \u2014 returns api_key instantly, no email needed. Free endpoints: /health, /x402/stats, /x402/info, /x402/verify, /.well-known/x402, /api/agentpay/ecosystem. All settlements are USDC on Base Mainnet (eip155:8453). Fee: $0.02 per settlement."
  },
  "servers": [
    {
      "url": "https://x402-agent-pay.com",
      "description": "Production \u2014 Base L2 Mainnet"
    }
  ],
  "tags": [
    {
      "name": "x402 Core",
      "description": "Core x402 payment verification and settlement"
    },
    {
      "name": "Escrow",
      "description": "Milestone-based USDC escrow for agent jobs"
    },
    {
      "name": "Registration",
      "description": "Register as an agent or API provider"
    },
    {
      "name": "Partner",
      "description": "Provider dashboard \u2014 earnings, endpoints, analytics"
    },
    {
      "name": "Discovery",
      "description": "Ecosystem and agent discovery"
    },
    {
      "name": "System",
      "description": "Health, stats, and protocol info"
    }
  ],
  "paths": {
    "/x402/verify": {
      "post": {
        "tags": [
          "x402 Core"
        ],
        "summary": "Verify an x402 payment grant",
        "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.",
        "operationId": "verifyPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              },
              "example": {
                "payment_header": "eyJ0eXAiOiJ4NDAyIiwiYWxnIjoiRUlQNzEyIn0...",
                "resource": "https://api.example.com/data",
                "required_amount": "1000"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment is valid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or insufficient payment"
          }
        }
      }
    },
    "/x402/settle": {
      "post": {
        "tags": [
          "x402 Core"
        ],
        "summary": "Settle an x402 payment on-chain",
        "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.",
        "operationId": "settlePayment",
        "x-payment-required": {
          "scheme": "exact",
          "network": "eip155:8453",
          "maxAmountRequired": "20000",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x367F1b3D8Ca90D1e087481a9A40d585Bf3451a03"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settlement confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettleResponse"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          },
          "400": {
            "description": "Invalid payment data"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/pay": {
      "post": {
        "tags": [
          "x402 Core"
        ],
        "summary": "Submit x402 payment (alias)",
        "description": "Alias for /x402/settle. Accepts a signed x402 payment header and settles USDC on Base L2.",
        "operationId": "submitPayment",
        "x-payment-required": {
          "scheme": "exact",
          "network": "eip155:8453",
          "maxAmountRequired": "20000",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "payTo": "0x367F1b3D8Ca90D1e087481a9A40d585Bf3451a03"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PayRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment settled"
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          },
          "400": {
            "description": "Invalid payment"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/escrow": {
      "post": {
        "tags": [
          "Escrow"
        ],
        "summary": "Create a USDC escrow",
        "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.",
        "operationId": "createEscrow",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EscrowRequest"
              },
              "example": {
                "payer": "0xYourWallet",
                "payee": "0xAgentWallet",
                "amount_usdc": 5.0,
                "description": "Web scraping job \u2014 100 URLs"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Escrow created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EscrowResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/release": {
      "post": {
        "tags": [
          "Escrow"
        ],
        "summary": "Release escrowed USDC",
        "description": "Release locked USDC to the payee upon job completion. Must be called by the original payer.",
        "operationId": "releaseEscrow",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReleaseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Escrow released successfully"
          },
          "404": {
            "description": "Escrow not found"
          },
          "403": {
            "description": "Not authorized to release this escrow"
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/refund": {
      "post": {
        "tags": [
          "Escrow"
        ],
        "summary": "Refund an escrow",
        "description": "Return locked USDC to the payer. Can be called by the payer before release, or by dispute resolution.",
        "operationId": "refundEscrow",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "escrow_id": {
                    "type": "string"
                  },
                  "payer": {
                    "type": "string",
                    "description": "Payer wallet address"
                  }
                },
                "required": [
                  "escrow_id",
                  "payer"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refund processed"
          },
          "404": {
            "description": "Escrow not found"
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/status/{payment_id}": {
      "get": {
        "tags": [
          "x402 Core"
        ],
        "summary": "Check payment status",
        "description": "Look up the on-chain settlement status of any payment by ID.",
        "operationId": "getPaymentStatus",
        "parameters": [
          {
            "name": "payment_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Payment ID returned by /pay or /x402/settle"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentStatus"
                }
              }
            }
          },
          "404": {
            "description": "Payment not found"
          },
          "402": {
            "description": "Payment Required \u2014 attach X-PAYMENT header with EIP-712 signed USDC grant"
          }
        },
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.020000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/agentpay/register": {
      "post": {
        "tags": [
          "Registration"
        ],
        "summary": "Register as an agent or API provider",
        "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.",
        "operationId": "registerAgent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              },
              "example": {
                "name": "my-trading-agent",
                "wallet": "0xYourWalletAddress",
                "agent_type": "ai_agent",
                "description": "Autonomous trading agent on Base L2"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registration successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing required fields"
          }
        }
      }
    },
    "/api/partner/register": {
      "post": {
        "tags": [
          "Registration"
        ],
        "summary": "Register as a revenue-share provider",
        "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.",
        "operationId": "registerPartner",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerRegisterRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Partner registered"
          },
          "400": {
            "description": "Invalid request or partner_id already taken"
          }
        }
      }
    },
    "/api/partner/balance": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "Get partner balance and earnings",
        "description": "Returns current claimable balance, total earned, payout wallet, and verification status for a partner.",
        "operationId": "getPartnerBalance",
        "parameters": [
          {
            "name": "partner_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Balance data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerBalance"
                }
              }
            }
          },
          "401": {
            "description": "Invalid api_key"
          }
        }
      }
    },
    "/api/partner/claim": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Claim earned USDC",
        "description": "Trigger a payout of claimable earnings to your registered wallet address. Minimum claim: $1.00 USDC.",
        "operationId": "claimEarnings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "partner_id": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string"
                  }
                },
                "required": [
                  "partner_id",
                  "api_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim initiated, USDC sent to wallet"
          },
          "400": {
            "description": "Below minimum claim threshold"
          }
        }
      }
    },
    "/api/partner/endpoints": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "List your registered endpoints",
        "description": "Returns all API endpoints registered under your partner account.",
        "operationId": "listEndpoints",
        "parameters": [
          {
            "name": "partner_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of endpoints"
          }
        }
      },
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Register a new endpoint",
        "description": "Add an x402-payable API endpoint to your provider listing. Agents can discover and pay for your endpoint via AgentPay.",
        "operationId": "createEndpoint",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EndpointCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Endpoint registered"
          }
        }
      }
    },
    "/api/partner/analytics": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "Get partner analytics",
        "description": "Returns settlement volume, call counts, and revenue breakdown for your partner account.",
        "operationId": "getAnalytics",
        "parameters": [
          {
            "name": "partner_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Analytics data"
          }
        }
      }
    },
    "/api/agentpay/ecosystem": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "List all registered providers",
        "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.",
        "operationId": "getEcosystem",
        "responses": {
          "200": {
            "description": "List of ecosystem providers"
          }
        }
      }
    },
    "/x402/stats": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Live settlement statistics",
        "description": "Returns total settlements, USDC volume, active escrows, and fees collected. Free to call.",
        "operationId": "getStats",
        "responses": {
          "200": {
            "description": "Live stats",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          }
        }
      }
    },
    "/x402/info": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Protocol info and payment requirements",
        "description": "Returns the facilitator's supported payment schemes, accepted assets, and network info. Use this to auto-configure an x402 client.",
        "operationId": "getProtocolInfo",
        "responses": {
          "200": {
            "description": "Protocol info"
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Health check",
        "description": "Returns 200 if the facilitator is online and connected to Base L2.",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "Healthy"
          }
        }
      }
    },
    "/.well-known/x402": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "x402 discovery document",
        "description": "Machine-readable discovery document listing all x402-payable endpoints, accepted assets, and payment requirements. This is how agents find and configure payments automatically.",
        "operationId": "x402Discovery",
        "responses": {
          "200": {
            "description": "x402 discovery document"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerifyRequest": {
        "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"
        ]
      },
      "VerifyResponse": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "amount": {
            "type": "string"
          },
          "payer": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SettleRequest": {
        "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"
        ]
      },
      "SettleResponse": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string"
          },
          "tx_hash": {
            "type": "string",
            "description": "Base L2 transaction hash"
          },
          "amount_usdc": {
            "type": "number"
          },
          "settled_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PayRequest": {
        "type": "object",
        "properties": {
          "payment_header": {
            "type": "string"
          },
          "resource": {
            "type": "string"
          },
          "partner_id": {
            "type": "string"
          }
        },
        "required": [
          "payment_header"
        ]
      },
      "EscrowRequest": {
        "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"
        ]
      },
      "EscrowResponse": {
        "type": "object",
        "properties": {
          "escrow_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "locked",
              "released",
              "refunded"
            ]
          },
          "amount_usdc": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ReleaseRequest": {
        "type": "object",
        "properties": {
          "escrow_id": {
            "type": "string"
          },
          "payer": {
            "type": "string",
            "description": "Payer wallet \u2014 must match original escrow creator"
          }
        },
        "required": [
          "escrow_id",
          "payer"
        ]
      },
      "PaymentStatus": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "confirmed",
              "failed"
            ]
          },
          "tx_hash": {
            "type": "string"
          },
          "amount_usdc": {
            "type": "number"
          },
          "settled_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RegisterRequest": {
        "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"
        ]
      },
      "RegisterResponse": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string"
          },
          "partner_id": {
            "type": "string"
          },
          "wallet": {
            "type": "string"
          },
          "payout_verified": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "PartnerRegisterRequest": {
        "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"
        ]
      },
      "PartnerBalance": {
        "type": "object",
        "properties": {
          "partner_id": {
            "type": "string"
          },
          "claimable_usdc": {
            "type": "number"
          },
          "total_earned_usdc": {
            "type": "number"
          },
          "payout_wallet": {
            "type": "string"
          },
          "payout_verified": {
            "type": "boolean"
          },
          "revenue_share_pct": {
            "type": "number"
          }
        }
      },
      "EndpointCreate": {
        "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"
        ]
      },
      "Stats": {
        "type": "object",
        "properties": {
          "total_settlements": {
            "type": "integer"
          },
          "total_volume_usdc": {
            "type": "number"
          },
          "active_escrows": {
            "type": "integer"
          },
          "fees_collected_usdc": {
            "type": "number"
          },
          "registered_providers": {
            "type": "integer"
          }
        }
      }
    }
  },
  "x-agentpay": {
    "facilitator": "https://x402-agent-pay.com",
    "network": "eip155:8453",
    "asset": "USDC",
    "asset_contract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "treasury": "0x367F1b3D8Ca90D1e087481a9A40d585Bf3451a03",
    "fee_per_settlement": "0.02",
    "settlement_time_avg": "1.8s",
    "github": "https://github.com/shawnhvac/x402",
    "discovery": "https://x402-agent-pay.com/.well-known/x402"
  },
  "x-discovery": {
    "ownershipProofs": [
      "0x367F1b3D8Ca90D1e087481a9A40d585Bf3451a03"
    ],
    "facilitatorUrl": "https://x402-agent-pay.com",
    "network": "eip155:8453"
  }
}