{
  "openapi": "3.1.0",
  "info": {
    "title": "402oracle",
    "version": "1.4.0",
    "description": "402oracle: machine-payable verification layer. Signed attestations for AI agents, paid per call in USDC via x402.",
    "contact": {
      "name": "402oracle",
      "email": "support@402oracle.com",
      "url": "https://402oracle.com"
    }
  },
  "servers": [
    {
      "url": "https://402oracle.com"
    }
  ],
  "paths": {
    "/verify/business": {
      "post": {
        "operationId": "verify_business",
        "summary": "Verify a business or domain is real and established before your agent pays an invoice, onboards a vendor, or trusts it. A business-verification oracle for KYB, vendor screening, and fraud checks: RDAP registration age, DNS (A/MX/NS), email posture (SPF/DMARC), and HTTPS reachability. Returns a signed attestation with a 0-100 trust score and evidence URLs.",
        "description": "Paid endpoint: $0.05 USDC per call via the x402 protocol. A request without an X-PAYMENT header returns HTTP 402 with payment requirements in the 'accepts' array. Responses are ES256-signed attestations verifiable against https://402oracle.com/.well-known/jwks.json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Domain to verify, e.g. example.com"
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed attestation. Settlement receipt is in the PAYMENT-RESPONSE header (x402 v2) or X-PAYMENT-RESPONSE (v1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAttestation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (e.g. missing or malformed input field). Not charged — do not retry without fixing the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. x402 v2 terms are in the base64 PAYMENT-REQUIRED response header; v1 terms are mirrored in the JSON body's 'accepts' array. Also returned when payment verification or settlement fails — the reason is in 'error'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Verification failed — an upstream data source or adjudicator was unavailable. Not charged; retrying later is reasonable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Payment facilitator unreachable or returned an error. Not charged; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service not configured to accept payments (payTo address unset).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify/price": {
      "post": {
        "operationId": "verify_price",
        "summary": "Confirm a crypto asset's price before your agent trades, quotes, or settles on it. A signed price oracle: cross-checks Coinbase, Kraken, and OKX for a median and flags divergence when sources disagree. Returns a signed attestation your agent can cite.",
        "description": "Paid endpoint: $0.02 USDC per call via the x402 protocol. A request without an X-PAYMENT header returns HTTP 402 with payment requirements in the 'accepts' array. Responses are ES256-signed attestations verifiable against https://402oracle.com/.well-known/jwks.json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "symbol": {
                    "type": "string",
                    "description": "Ticker symbol, e.g. BTC, ETH, SOL"
                  }
                },
                "required": [
                  "symbol"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed attestation. Settlement receipt is in the PAYMENT-RESPONSE header (x402 v2) or X-PAYMENT-RESPONSE (v1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAttestation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (e.g. missing or malformed input field). Not charged — do not retry without fixing the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. x402 v2 terms are in the base64 PAYMENT-REQUIRED response header; v1 terms are mirrored in the JSON body's 'accepts' array. Also returned when payment verification or settlement fails — the reason is in 'error'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Verification failed — an upstream data source or adjudicator was unavailable. Not charged; retrying later is reasonable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Payment facilitator unreachable or returned an error. Not charged; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service not configured to accept payments (payTo address unset).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify/freshness": {
      "post": {
        "operationId": "verify_freshness",
        "summary": "Check that a URL is live and its data is fresh before your agent acts on its contents. A freshness oracle: returns HTTP status, Last-Modified/ETag, a content SHA-256, and whether the content changed versus a prior hash. Returns a signed attestation.",
        "description": "Paid endpoint: $0.02 USDC per call via the x402 protocol. A request without an X-PAYMENT header returns HTTP 402 with payment requirements in the 'accepts' array. Responses are ES256-signed attestations verifiable against https://402oracle.com/.well-known/jwks.json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Full URL including https://"
                  },
                  "prior_hash": {
                    "type": "string",
                    "description": "Optional prior SHA-256 hex to compare against"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed attestation. Settlement receipt is in the PAYMENT-RESPONSE header (x402 v2) or X-PAYMENT-RESPONSE (v1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAttestation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (e.g. missing or malformed input field). Not charged — do not retry without fixing the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. x402 v2 terms are in the base64 PAYMENT-REQUIRED response header; v1 terms are mirrored in the JSON body's 'accepts' array. Also returned when payment verification or settlement fails — the reason is in 'error'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Verification failed — an upstream data source or adjudicator was unavailable. Not charged; retrying later is reasonable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Payment facilitator unreachable or returned an error. Not charged; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service not configured to accept payments (payTo address unset).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify/claim": {
      "post": {
        "operationId": "verify_claim",
        "summary": "Fact-check a single factual claim against web evidence before your agent relies on it. A fact-checking oracle and hallucination guard: returns a verdict (supported / contradicted / insufficient), a confidence score, and citations, as a signed attestation.",
        "description": "Paid endpoint: $0.25 USDC per call via the x402 protocol. A request without an X-PAYMENT header returns HTTP 402 with payment requirements in the 'accepts' array. Responses are ES256-signed attestations verifiable against https://402oracle.com/.well-known/jwks.json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "claim": {
                    "type": "string",
                    "description": "A single factual claim, 8-600 characters"
                  }
                },
                "required": [
                  "claim"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed attestation. Settlement receipt is in the PAYMENT-RESPONSE header (x402 v2) or X-PAYMENT-RESPONSE (v1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAttestation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (e.g. missing or malformed input field). Not charged — do not retry without fixing the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. x402 v2 terms are in the base64 PAYMENT-REQUIRED response header; v1 terms are mirrored in the JSON body's 'accepts' array. Also returned when payment verification or settlement fails — the reason is in 'error'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Verification failed — an upstream data source or adjudicator was unavailable. Not charged; retrying later is reasonable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Payment facilitator unreachable or returned an error. Not charged; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service not configured to accept payments (payTo address unset).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify/business/batch": {
      "post": {
        "operationId": "verify_business_batch",
        "summary": "Verify up to 5 business domains in one signed attestation — vendor lists, invoice batches, marketplace supplier screening. Same checks as /verify/business per domain (RDAP registration age, DNS, SPF/DMARC, HTTPS) with a 0-100 trust score each, returned as one ES256-signed attestation. Flat $0.15 per batch: 40% below the per-domain price of single calls at a full batch.",
        "description": "Paid endpoint: $0.15 USDC per call via the x402 protocol. A request without an X-PAYMENT header returns HTTP 402 with payment requirements in the 'accepts' array. Responses are ES256-signed attestations verifiable against https://402oracle.com/.well-known/jwks.json.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Domain, e.g. example.com"
                    },
                    "minItems": 2,
                    "maxItems": 5,
                    "description": "2-5 domains to verify in one call. Duplicates are de-duplicated."
                  }
                },
                "required": [
                  "domains"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed attestation. Settlement receipt is in the PAYMENT-RESPONSE header (x402 v2) or X-PAYMENT-RESPONSE (v1).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedAttestation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body (e.g. missing or malformed input field). Not charged — do not retry without fixing the input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Payment required. x402 v2 terms are in the base64 PAYMENT-REQUIRED response header; v1 terms are mirrored in the JSON body's 'accepts' array. Also returned when payment verification or settlement fails — the reason is in 'error'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentRequired"
                }
              }
            }
          },
          "500": {
            "description": "Verification failed — an upstream data source or adjudicator was unavailable. Not charged; retrying later is reasonable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Payment facilitator unreachable or returned an error. Not charged; retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service not configured to accept payments (payTo address unset).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SignedAttestation": {
        "type": "object",
        "properties": {
          "attestation": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "subject": {
                "type": "object"
              },
              "result": {
                "type": "object"
              },
              "evidence": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "confidence": {
                "type": "number"
              },
              "issuer": {
                "type": "object"
              },
              "issued_at": {
                "type": "string"
              },
              "expires_at": {
                "type": "string"
              }
            }
          },
          "signature": {
            "type": "object",
            "properties": {
              "alg": {
                "type": "string"
              },
              "kid": {
                "type": "string"
              },
              "canonicalization": {
                "type": "string"
              },
              "value": {
                "type": "string"
              },
              "jwks": {
                "type": "string"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable code: invalid_request, verification_failed, settlement_failed, settlement_error, facilitator_unreachable, service_unconfigured."
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation."
          },
          "charged": {
            "type": "boolean",
            "description": "Whether the caller's payment was settled. False on every error response — failed calls are never billed."
          }
        },
        "required": [
          "error"
        ]
      },
      "PaymentRequired": {
        "type": "object",
        "description": "x402 v1 payment terms (v2 terms ride in the PAYMENT-REQUIRED header).",
        "properties": {
          "x402Version": {
            "type": "integer",
            "examples": [
              1
            ]
          },
          "error": {
            "type": "string"
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": {
                  "type": "string",
                  "examples": [
                    "exact"
                  ]
                },
                "network": {
                  "type": "string",
                  "examples": [
                    "base"
                  ]
                },
                "maxAmountRequired": {
                  "type": "string",
                  "description": "Atomic USDC units (6 decimals)."
                },
                "resource": {
                  "type": "string"
                },
                "payTo": {
                  "type": "string"
                },
                "asset": {
                  "type": "string"
                },
                "maxTimeoutSeconds": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}