API Reference

Network Constants

Constant	Testnet Value	Mainnet Value
Network String	cronos-testnet	cronos
Chain ID	338	25
RPC URL	https://evm-t3.cronos.org	https://evm.cronos.org
USDX Contract	0x149a72BCdFF5513F2866e9b6394edba2884dbA07	Coming soon
Facilitator URL	https://facilitator.cronoslabs.org/v2/x402	Same (single endpoint)

Note: Use these contract addresses in the asset field of your payment requirements. Always verify contract addresses match your target network.

Note: The facilitator uses one base URL for all networks. Switch between mainnet and testnet by setting the network field in your payment requirements ("cronos-testnet" or "cronos"). See API Endpoints below.

API Endpoints

Endpoint	Method	URL
Health Check	GET	https://facilitator.cronoslabs.org/healthcheck
Supported	GET	https://facilitator.cronoslabs.org/v2/x402/supported
Verify	POST	https://facilitator.cronoslabs.org/v2/x402/verify
Settle	POST	https://facilitator.cronoslabs.org/v2/x402/settle

Health Check Endpoint

GET /healthcheck

Returns the health status of the facilitator service, including uptime, response time, and timestamp. No authentication required.

Response:

{
    "status": "success",
    "results": {
        "uptime": 167592.074548689,
        "responseTime": [
            13401697,
            473212559
        ],
        "message": "OK",
        "timestamp": 1762490327834
    }
}

Supported Endpoint

GET /v2/x402/supported

Retrieves the supported payment kinds from the facilitator service, including available networks, schemes, and X402 protocol versions. No authentication required.

{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "cronos-testnet"
    }
  ]
}

Verify Endpoint

POST /v2/x402/verify

Validates a payment header and requirements without executing an on-chain transaction. Use this to verify payment validity before committing to settlement.

Headers:

Content-Type: application/json
X402-Version: 1

Request Body:

{
  "x402Version": 1,
  "paymentHeader": "eyJ4NDAyVmVyc2lvbiI6MS4uLn0=",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "cronos-testnet",
    "payTo": "0xSeller...",
    "asset": "0xUSDX...",
    "maxAmountRequired": "1000000",
    "maxTimeoutSeconds": 300
  }
}

Payment Header (Base64 decoded structure):

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "cronos-testnet",
  "payload": {
    "from": "0xFrom...",
    "to": "0xPayTo...",
    "value": "1000000",
    "validAfter": 0,
    "validBefore": 1735689551,
    "nonce": "0xNonce...",
    "signature": "0xSignature...",
    "asset": "0xUSDX..."
  }
}

Success Response:

{
  "isValid": true,
  "invalidReason": null
}

Failure Response:

{
  "isValid": false,
  "invalidReason": "Unsupported network: ethereum-mainnet"
}

What This Endpoint Does:

• Decodes Base64-encoded payment headers

• Verifies scheme matches supported types (exact)

• Confirms network is supported (cronos-testnet)

• Validates asset/token contracts and amounts

• Verifies EIP-3009 signatures using EIP-712 typed data

• Checks validBefore and validAfter timestamp windows

• Rate limited to 10 requests per minute per IP

Common Invalid Reasons:

• Unsupported scheme: [scheme]

• Unsupported network: [network]

• Unsupported asset: [asset]

• Recipient does not match payTo address

• Invalid amount: [amount]

• Invalid EIP-3009 signature

• Invalid Base64 paymentHeader

Settle Endpoint

POST /v2/x402/settle

Executes a verified payment on-chain by submitting an EIP-3009 transferWithAuthorization transaction.

Headers:

Content-Type: application/json
X402-Version: 1

Request Body:

Same format as the Verify Endpoint.

Success Response:

{
  "x402Version": 1,
  "event": "payment.settled",
  "txHash": "0xTxHash...",
  "from": "0xFrom...",
  "to": "0xPayTo...",
  "value": "1000000",
  "blockNumber": 17352,
  "network": "cronos-testnet",
  "timestamp": "2025-11-04T20:19:11.000Z"
}

Failure Response:

{
  "x402Version": 1,
  "event": "payment.failed",
  "network": "cronos-testnet",
  "timestamp": "2025-11-04T20:19:11.000Z",
  "error": "Authorization already used"
}

What This Endpoint Does:

• Calls transferWithAuthorization on USDX Token

• Waits for transaction confirmation on-chain (facilitator blocks until settled)

• Uses unique nonces to prevent duplicate transactions

• Returns transaction hash, block number, and timestamp

• Rate limited to 5 requests per minute per IP

Common Errors:

• Authorization already used (duplicate nonce - transaction already executed)

• Authorization expired (validBefore timestamp passed)

• Authorization not yet valid (validAfter not reached)

• ERC20: transfer amount exceeds balance (insufficient balance)

• Invalid signature (signature verification failed off-chain or on-chain)

• Transaction failed on-chain (generic failure)