Skip to main content

​
Base URL

The Corbits production facilitator is available at:
https://facilitator.corbits.dev

​
API Endpoints

The facilitator exposes four HTTP endpoints for payment processing in the x402 protocol:

POST /accepts

Enrich payment requirements with blockchain-specific parameters

POST /verify

Validate payment proofs without executing blockchain transactions

POST /settle

Validate payment proofs and execute blockchain transactions

GET /supported

Query supported payment schemes and networks

​
Request Format

All endpoints accept and return JSON payloads with Content-Type: application/json.

​
Standard Headers

Content-Type: application/json
Accept: application/json
No authentication is required for facilitator endpoints. Access control is handled through cryptographic validation of payment proofs.

​
Response Format

All endpoints return JSON responses with appropriate HTTP status codes:
  • 200 OK: Request processed successfully
  • 400 Bad Request: Invalid request format or missing fields
  • 500 Internal Server Error: Facilitator encountered an error

​
Response by Endpoint

/accepts and /supported return: 
{
  "x402Version": 1,
  "accepts": [...]  // or "kinds": [...] for /supported
}
/verify returns: 
{
  "isValid": true,
  "invalidReason": null
}
/settle returns: 
{
  "success": true,
  "error": null,
  "txHash": "...",
  "networkId": "..."
}

​
Error Responses

/verify error: 
{
  "isValid": false,
  "invalidReason": "Error message"
}
/settle error: 
{
  "success": false,
  "error": "Error message",
  "txHash": null,
  "networkId": null
}

​
Protocol Version

All requests and responses include an x402Version field indicating the protocol version. Currently, only version 1 is supported.

​
Timeout Handling

All facilitator operations have a configurable timeout (default: 30 seconds) to prevent:
  • Slow blockchain RPC endpoints from blocking requests
  • Handler bugs from hanging the facilitator
  • Resource exhaustion attacks
If a handler operation exceeds the timeout, the request will fail with a 500 error.

​
Next Steps

Accept Endpoint

Learn how to enrich payment requirements

Verify Endpoint

Learn how to validate payments

Settle Endpoint

Learn how to settle payments

Errors

Understanding error responses