Github

x444 Facilitator

x444 Facilitator API Reference

Overview

The x444 Facilitator API implements the x402 protocol for blockchain payment verification and settlement. It enables developers, dApps, and AI agents to verify and settle payments across multiple networks in a gasless, standardized, and chain-agnostic way.

Base URL

https://facilitator.x444.io

Version: 1.0.0 License: MIT Contact: [email protected]

Authentication

Include your API key in the request header:

X-API-Key: your-api-key

1. Get Facilitator Information

GET /v1

Returns basic information about the facilitator service and available endpoints.

Response

{
  "service": "X402 Facilitator",
  "version": "1.0.0",
  "endpoints": {
    "/": "Facilitator information",
    "/supported": "List supported networks and schemes",
    "/resources": "Get available resources",
    "/verify": "Verify payment validity",
    "/settle": "Settle payments on blockchain",
    "/health": "Service health status"
  }
}

Use Case: Check facilitator connectivity and discover all available routes.

2. Check Service Health

GET /v1/health

Checks the health of the facilitator service and its blockchain connections.

Response

{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "networks": {
    "evm": "configured",
    "svm": "configured"
  }
}

Use Case: Useful for uptime monitoring and infrastructure diagnostics.

3. Get Supported Payment Types

GET /v1/supported

Lists all payment schemes and networks supported by the facilitator.

Response

{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "bsc",
      "extra": {
        "feePayer": "0x1234567890abcdef1234567890abcdef12345678"
      }
    }
  ]
}

Errors

  • 500 Internal Server Error: Network configuration or internal failure.

Use Case: Check which networks and schemes your app can interact with.

4. Get Available Resources

GET /v1/resources

Returns a list of supported resources and networks.

Response

{
  "resources": ["EVM Networks", "SVM Networks"],
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Use Case: Discover available infrastructure for EVM and SVM environments.

5. Verify Payment

POST /v1/verify

Verifies the validity of a payment payload before settlement. Checks digital signatures, nonces, timestamps, and payment data against requirements.

Request

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "bsc",
    "payload": {
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
        "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "value": "1000000",
        "validAfter": "1703123456",
        "validBefore": "1703127056",
        "nonce": "0x0000...001"
      },
      "signature": "0x..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "bsc",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
    "resource": "https://api.example.com/data",
    "description": "AI dataset query",
    "maxTimeoutSeconds": 300
  }
}

Response

{
  "isValid": true,
  "payer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
}

Errors

  • 400 Bad Request: Invalid payload or signature.

Use Case: Run a pre-flight check before settlement to ensure transaction validity.

6. Settle Payment

POST /v1/settle

Finalizes the payment by submitting it to the blockchain. This executes the actual token transfer through the x444 wrapper.

Request

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "bsc",
    "payload": {
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
        "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "value": "1000000",
        "validAfter": "1703123456",
        "validBefore": "1703127056",
        "nonce": "0x0000...001"
      },
      "signature": "0x..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "bsc",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
    "resource": "https://api.example.com/data",
    "description": "AI dataset query",
    "maxTimeoutSeconds": 300
  }
}

Response

{
  "success": true,
  "txHash": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7..."
}

Errors

  • 400 Bad Request: Invalid data or schema mismatch.

  • 500 Internal Server Error: Blockchain transaction failed.

Use Case: Execute verified transactions on-chain through the facilitator’s settlement flow.

Typical Flow

Client → /verify → Facilitator → Signature validation
       → /settle → Facilitator → On-chain transfer → Recipient

Verification ensures payload validity. Settlement executes the transaction.

Example Integration (Node.js)

import axios from "axios";

const API_URL = "https://facilitator.x444.io/v1";
const API_KEY = process.env.X444_API_KEY;

async function verifyPayment(payload) {
  const res = await axios.post(`${API_URL}/verify`, payload, {
    headers: { "X-API-Key": API_KEY },
  });
  console.log(res.data);
}

async function settlePayment(payload) {
  const res = await axios.post(`${API_URL}/settle`, payload, {
    headers: { "X-API-Key": API_KEY },
  });
  console.log(res.data);
}

Notes

  • All timestamps are Unix epoch seconds.

  • Nonces must be unique per payer to prevent replay attacks.

  • /verify and /settle are idempotent.

  • Supports both EVM and SVM networks.

Summary

The x444 Facilitator API turns standard HTTP requests into blockchain transactions. It provides a unified verification and settlement layer that powers instant, gasless payments for the AI economy.

Last updated