{
  "openapi": "3.1.0",
  "info": {
    "title": "NERO 402 Facilitator API",
    "version": "1.0.0",
    "summary": "x402 V2 facilitator for the aa-native and exact settlement schemes on NERO Chain.",
    "description": "The NERO 402 facilitator verifies and settles x402 V2 payments. It speaks two schemes: `aa-native` (ERC-4337 smart-contract wallets sign a UserOperation that calls the on-chain SettlementContract, with paymaster-sponsored gas) and `exact` (EIP-3009 authorizations from EOAs, wire-compatible with upstream x402). Merchant servers call `/verify` and `/settle`; agents never call the facilitator directly. See https://docs.x402.nerochain.io/docs/core-concepts/facilitator for the conceptual model.",
    "contact": {
      "name": "NERO Chain",
      "email": "help-support@nerochain.io",
      "url": "https://docs.x402.nerochain.io"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/nerochain/nero-x402/blob/main/LICENSE"
    }
  },
  "externalDocs": {
    "description": "NERO 402 documentation",
    "url": "https://docs.x402.nerochain.io/docs"
  },
  "servers": [
    {
      "url": "https://facilitator.x402.nerochain.io",
      "description": "Reference facilitator (tracks main; mainnet + testnet config)"
    }
  ],
  "tags": [
    {
      "name": "discovery",
      "description": "Capability discovery for agents and merchants."
    },
    {
      "name": "payments",
      "description": "x402 payment verification and settlement."
    },
    {
      "name": "ops",
      "description": "Operational health."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "ops"
        ],
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns service status and the configured network. No authentication.",
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                },
                "example": {
                  "status": "ok",
                  "network": "eip155:1689"
                }
              }
            }
          }
        }
      }
    },
    "/supported": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getSupported",
        "summary": "List supported schemes, networks, and assets",
        "description": "Advertises the payment schemes the facilitator accepts and, per scheme, the networks and allowlisted asset addresses. Agents use this to decide how to pay. No authentication.",
        "responses": {
          "200": {
            "description": "Supported scheme matrix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupportedResponse"
                },
                "example": {
                  "x402Version": 2,
                  "schemes": [
                    {
                      "scheme": "aa-native",
                      "networks": [
                        "eip155:1689"
                      ],
                      "assets": [
                        "0xff13a7a12fd485bc9687ff88d8ae1a6b655ab469"
                      ]
                    },
                    {
                      "scheme": "exact",
                      "networks": [
                        "eip155:1689"
                      ],
                      "assets": [
                        "0x97eec1c29f745dc7c267f90292aa663d997a601d"
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/verify": {
      "post": {
        "tags": [
          "payments"
        ],
        "operationId": "verifyPayment",
        "summary": "Verify a signed payment payload",
        "description": "Validates a payment payload against its requirements without settling on chain: signature/UserOperation validity, scheme/network/asset match, amount, and off-chain replay status. Called by merchant middleware after an agent retries with a PAYMENT-SIGNATURE header.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result. `isValid` indicates acceptance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                },
                "examples": {
                  "valid": {
                    "value": {
                      "isValid": true,
                      "payer": "0xPAYER_SCW"
                    }
                  },
                  "invalid": {
                    "value": {
                      "isValid": false,
                      "invalidReason": "replay"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                },
                "example": {
                  "isValid": false,
                  "invalidReason": "malformed_request"
                }
              }
            }
          }
        }
      }
    },
    "/settle": {
      "post": {
        "tags": [
          "payments"
        ],
        "operationId": "settlePayment",
        "summary": "Settle a verified payment on chain",
        "description": "Verifies, then submits the payment on chain. For aa-native, submits the UserOperation through the NERO bundler with paymaster-sponsored gas; for exact, submits the EIP-3009 authorization. Idempotent per replay key: a duplicate settle returns the original receipt. Returns the on-chain transaction hash on success.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settlement result. `success` indicates on-chain settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettleResponse"
                },
                "examples": {
                  "settled": {
                    "value": {
                      "success": true,
                      "x402Version": 2,
                      "scheme": "aa-native",
                      "network": "eip155:1689",
                      "transactionHash": "0xTX",
                      "payer": "0xPAYER_SCW",
                      "amount": "1000",
                      "asset": "0xff13a7a12fd485bc9687ff88d8ae1a6b655ab469"
                    }
                  },
                  "failed": {
                    "value": {
                      "success": false,
                      "x402Version": 2,
                      "errorCode": "user_op_failed",
                      "message": "user_op_failed"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettleResponse"
                }
              }
            }
          },
          "503": {
            "description": "Transient settlement failure (e.g. bundler_unreachable, receipt_timeout). Honor the Retry-After header.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettleResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PaymasterApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Paymaster-Api-Key",
        "description": "Only relevant when self-hosting a facilitator: the NERO Paymaster API key (from the NERO AA Platform dashboard) the facilitator uses server-side to sponsor gas. The hosted facilitator and the public /verify, /supported endpoints require no caller credential."
      }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": [
          "status",
          "network"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "network": {
            "type": "string",
            "description": "CAIP-2 network id.",
            "example": "eip155:1689"
          }
        }
      },
      "SupportedResponse": {
        "type": "object",
        "required": [
          "x402Version",
          "schemes"
        ],
        "properties": {
          "x402Version": {
            "type": "integer",
            "const": 2
          },
          "schemes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "scheme",
                "networks",
                "assets"
              ],
              "properties": {
                "scheme": {
                  "type": "string",
                  "enum": [
                    "exact",
                    "aa-native"
                  ]
                },
                "networks": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "minItems": 1
                },
                "assets": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "pattern": "^0x[a-fA-F0-9]{40}$"
                  },
                  "minItems": 1
                }
              }
            }
          }
        }
      },
      "PaymentRequirements": {
        "type": "object",
        "required": [
          "scheme",
          "network",
          "amount",
          "asset",
          "payTo"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "enum": [
              "exact",
              "aa-native"
            ]
          },
          "network": {
            "type": "string",
            "description": "CAIP-2 network id.",
            "example": "eip155:1689"
          },
          "amount": {
            "type": "string",
            "description": "Atomic units of the asset (no decimal point).",
            "example": "1000"
          },
          "asset": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "ERC-20 token address."
          },
          "payTo": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Merchant recipient address."
          },
          "maxTimeoutSeconds": {
            "type": "integer",
            "example": 60
          }
        }
      },
      "PaymentPayload": {
        "type": "object",
        "required": [
          "x402Version",
          "accepted",
          "payload"
        ],
        "properties": {
          "x402Version": {
            "type": "integer",
            "const": 2
          },
          "accepted": {
            "$ref": "#/components/schemas/PaymentRequirements"
          },
          "payload": {
            "type": "object",
            "description": "Scheme-specific inner payload. For aa-native: a signed ERC-4337 UserOperation plus settlementCallSpec. For exact: an EIP-3009 authorization.",
            "additionalProperties": true
          },
          "extensions": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": [
          "paymentPayload",
          "paymentRequirements"
        ],
        "properties": {
          "paymentPayload": {
            "$ref": "#/components/schemas/PaymentPayload"
          },
          "paymentRequirements": {
            "$ref": "#/components/schemas/PaymentRequirements"
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "required": [
          "isValid"
        ],
        "properties": {
          "isValid": {
            "type": "boolean"
          },
          "payer": {
            "type": "string",
            "description": "Payer address when known and valid."
          },
          "invalidReason": {
            "type": "string",
            "description": "Set when isValid is false.",
            "enum": [
              "malformed_request",
              "replay",
              "invalid_inner_payload",
              "scheme_mismatch",
              "network_mismatch",
              "asset_not_allowed",
              "amount_mismatch",
              "signature_invalid"
            ]
          }
        }
      },
      "SettleRequest": {
        "type": "object",
        "required": [
          "paymentPayload",
          "paymentRequirements"
        ],
        "properties": {
          "paymentPayload": {
            "$ref": "#/components/schemas/PaymentPayload"
          },
          "paymentRequirements": {
            "$ref": "#/components/schemas/PaymentRequirements"
          }
        }
      },
      "SettleResponse": {
        "type": "object",
        "required": [
          "success",
          "x402Version"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "x402Version": {
            "type": "integer",
            "const": 2
          },
          "scheme": {
            "type": "string",
            "enum": [
              "exact",
              "aa-native"
            ]
          },
          "network": {
            "type": "string"
          },
          "transactionHash": {
            "type": "string"
          },
          "userOpHash": {
            "type": "string"
          },
          "requestHash": {
            "type": "string"
          },
          "payer": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "asset": {
            "type": "string"
          },
          "errorCode": {
            "type": "string",
            "description": "Set when success is false.",
            "enum": [
              "verify_failed",
              "in_flight",
              "user_op_failed",
              "bundler_unreachable",
              "receipt_timeout",
              "internal_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable detail for the error code."
          }
        }
      }
    }
  }
}