Facilitator API

These endpoints implement the x402 facilitator protocol. They are always free — providers and payment middleware call them automatically.

GET

/facilitator/supported

Returns the networks, assets, and settlement capabilities supported by KODA.

Request

curlbash

curl https://x402.kodaoracle.com/facilitator/supported

Response

200 OKjson

{
  "supported": true,
  "networks": ["base"],
  "assets": [
    {
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6
    }
  ],
  "facilitatorAddress": "...",
  "qualityGate": true,
  "settlementMode": "quality-validated"
}

POST

/facilitator/verify

Verifies that an x402 payment header is valid and covers the required amount.

Request Body

POSTjson

{
  "paymentHeader": "<base64-encoded x402 payment>",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "resource": "https://provider.com/api/v1/data",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x..."
  }
}

Response

200 OKjson

{
  "valid": true,
  "invalidReason": null,
  "payer": "0x...",
  "amount": "1000"
}

POST

/facilitator/settle

Settles an x402 payment. If responseBody is provided, KODA runs the quality gate before settling. Without it, standard settlement applies.

Standard Settlement (no quality gate)

POSTjson

{
  "paymentHeader": "<base64-encoded x402 payment>",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "resource": "https://provider.com/api/v1/data",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x..."
  }
}

Quality Gate Settlement

POSTjson

{
  "paymentHeader": "<base64-encoded x402 payment>",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "resource": "https://provider.com/api/v1/data",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x..."
  },
  "responseBody": "{\"data\":{\"price\":0.0142}}"
}

Response (settled)

200 OKjson

{
  "success": true,
  "settled": true,
  "transactionHash": "0x...",
  "qualityGate": {
    "passed": true,
    "checks": {
      "validJson": true,
      "hasData": true,
      "noErrors": true,
      "minSize": true
    },
    "score": 4
  }
}

Response (rejected)

400 Quality Gate Failedjson

{
  "success": false,
  "settled": false,
  "reason": "quality_gate_failed",
  "qualityGate": {
    "passed": false,
    "checks": {
      "validJson": true,
      "hasData": false,
      "noErrors": false,
      "minSize": false
    },
    "score": 1
  }
}

Quality Gate Rules

validJson — Response parses as valid JSON
hasData — Contains a data, result, or results field, or is an array
noErrors — No error/errors field present
minSize — Response body is greater than 10 bytes
Must pass 3 of 4 checks to settle.