Facilitator API

The x402-FHE Facilitator provides payment verification services for confidential token transfers.

Production Endpoints

Environment	URL	Status
Production	https://zama-facilitator.ultravioletadao.xyz	Live
Local Development	http://localhost:4020	For testing

Production Ready

The production facilitator is hosted by Ultravioleta DAO and is ready for use. No setup required for testnet integration.

Base URL

Production:

https://zama-facilitator.ultravioletadao.xyz

Local Development:

http://localhost:4020

Endpoints

GET /

Returns service information.

Response

{
  "name": "X402 FHE Facilitator",
  "description": "Payment verification service for X402 FHE payments",
  "version": "1.0.0",
  "endpoints": {
    "health": "GET /health - Health check",
    "verify": "POST /verify - Verify FHE payment"
  }
}

---

GET /health

Health check endpoint.

Response

{
  "status": "ok",
  "service": "x402-facilitator",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "networks": ["fhevm-local", "sepolia"]
}

---

POST /verify

Verify an FHE payment.

Request Body

{
  "x402Version": 1,
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "fhe-transfer",
    "network": "sepolia",
    "chainId": 11155111,
    "payload": {
      "txHash": "0x...",
      "decryptionSignature": {
        "signature": "0x...",
        "publicKey": "0x...",
        "privateKey": "0x...",
        "userAddress": "0x...",
        "contractAddresses": ["0x..."],
        "startTimestamp": 1705312200,
        "durationDays": 365
      }
    }
  },
  "paymentRequirements": {
    "scheme": "fhe-transfer",
    "network": "sepolia",
    "chainId": 11155111,
    "payTo": "0x...",
    "maxAmountRequired": "1000000",
    "asset": "0x...",
    "resource": "https://example.com/api/premium",
    "description": "Premium content access",
    "mimeType": "application/json",
    "maxTimeoutSeconds": 300
  }
}

Success Response (200)

{
  "isValid": true,
  "txHash": "0x...",
  "amount": "1000000"
}

Error Response (400)

{
  "isValid": false,
  "invalidReason": "Insufficient payment. Required: 1000000, Got: 500000"
}

Error Codes

Status	Meaning
200	Payment verified
400	Invalid payment
500	Server error

Invalid Reasons

Common invalidReason values:

Reason	Description
Transaction not found	TX hash not on chain
No ConfidentialTransfer event	Event not in logs
Recipient mismatch	Wrong payTo address
Sender mismatch	Transfer not from user
Contract not authorized	Token not in signature
Insufficient payment	Amount below required
Decryption failed	Cannot decrypt handle