API

1. Facilitator API Overview

The xPlug Facilitator API is publicly accessible.

No special authentication is required. You do not need to set up a client key or secret key. Simply set the xPlug Facilitator URL, and you are good to go.

Base URL : https://facilitator.xplug.io

Endpoints :

• /verify : Used to validate whether the input conforms to the x402 standard.

• /settle : Used to charge x402 transactions.

• /support : Provides information on available networks.

2. x402 Payment Flow

The xPlug Facilitator adheres to the standard HTTP request-response cycle for x402 protocols.

• Initial Request (No Payment): The client sends an HTTP request to the server without the required payment header (X-PAYMENT-HEADER).

• Payment Requirement Response: The server responds with HTTP Status Code 402 (Payment Required), including the payment requirement information in the response body.

• Authorization and Signature: The client signs the payment authorization and resends the request, including the base64-encoded signature to the server.

• Validation and Settlement: The server validates the signature, performs the payment settlement on the blockchain, and then returns the requested premium content.

3. Reference

3.1 Payment Requirements Response

{  
  "x402Version": 1,  
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "1000000", // 1 USDC
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
      "payTo": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
      "resource": "https://api.example.com/weather",
      "description": "Access weather API",
      "mimeType": "application/json",
      "outputSchema": null,
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9"
      }
    }
  ]  
}

Field Descriptions

Field Name	Data Type	Description
x402Version	number	Protocol version identifier
error	string	Error message explaining why payment is required
accepts	array of Payment Requirements Object	Array of payment requirements object

Payment Requirements Object Descriptions

Field Name	Type	Required	Default	Description
scheme	string		exact	Payment scheme identifier
network	string			Blockchain network identifier (supported : "solana" , "solana-devnet")
maxAmountRequired	string			Required payment amount in decimal units
asset	string		86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY	Token contract address
payTo	string			Recipient wallet address
resource	string			URL of the protected API
description	string			Human readable description of API endpoint
mimeType	string		application/json	MIME type of response
outputSchema	object			JSON schema of the response
maxTimeoutSeconds	number			Maximum time allowed for payment settlement
extra	object			Scheme-specific additional information

3.2. POST /verify

Endpoint

https://facilitator.xplug.io/verifyfacilitator.xplug.io

HTTP Request Body

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana",
    "payload": {
      "transaction": "base64-encoded signed versioned transaction",
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/weather",
    "description": "Access weather API",
    "payTo": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    "maxTimeoutSeconds": 60,
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9"
    }
}

HTTP Response 200 (Success)

{
    "isValid": true,
    "payer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9"
}

HTTP Response 400 (Bad Request)

{
    "isValid": false,
    "error": "The maxAmountRequirement is not equivalent to the signed transaction"
}

3.3. POST /settle

Endpoint

https://facilitator.xplug.io/settlefacilitator.xplug.io

HTTP Request Body

{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "solana",
    "payload": {
      "transaction": "base64-encoded signed versioned transaction",
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana",
    "maxAmountRequired": "1000000",
    "resource": "https://api.example.com/weather",
    "description": "Access weather API",
    "payTo": "86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY",
    "maxTimeoutSeconds": 60,
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "extra": {
      "feePayer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9"
    }
}

HTTP Response 200

{
    "success": true,
    "error": "",
    "transaction": "3YZ4wBZ9EmU8VbNJABfVzjiiNHjUZfaz7uL5q93x122DCdJUhpbStZfZ12APJK1tijcmBzcf1V6TdZ3UiJ1HTYyd"
    "payer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9",
    "network": "solana"
}

HTTP Response 400

{
    "success": false,
    "error": "Signature verification failure",
    "transaction": ""
    "payer": "5XkN4Hx8tChhGR56iKAEuc9rHRpY2m8diu51rETxgLb9",
    "network": "solana"
}