API Reference

Returns which facilitator is currently primary, its fallback, and suggested client behavior.

curl https://x402labs.cloud/facilitator

{
  "primary": {
    "name": "x402labs",
    "type": "x402labs",
    "available": true
  },
  "fallback": {
    "name": "CodeNut Pay",
    "type": "codenut",
    "available": true
  },
  "configuration": {
    "type": "auto",
    "fallbackEnabled": true
  },
  "recommendation": "Using primary facilitator: x402labs"
}

Fetch the SOL/USD price feed (via Jupiter) and derived USD-to-lamports conversions used for rent-exempt enforcement.

curl https://x402labs.cloud/pricing/sol-usd

{
  "current": {
    "price": 156.38,
    "source": "Jupiter",
    "timestamp": "2025-11-11T19:05:28.439Z"
  },
  "cached": {
    "price": 156.12,
    "age": "42s"
  },
  "health": { "healthy": true },
  "providerCosts": [
    {
      "provider": "Helius",
      "usdCost": 0.00015,
      "lamports": 890880,
      "sol": "0.000890880"
    }
  ]
}

Discover prepaid bundle options for a given chain. Combine with x402-batch header to redeem.

Query Parameters

curl 'https://x402labs.cloud/batch-pricing?chain=solana'

{
  "chain": "solana",
  "batchOptions": [
    {
      "providerId": "helius-solana",
      "providerName": "Helius",
      "calls": 1000,
      "price": 0.12,
      "pricePerCall": 0.00012,
      "savings": "20.0%"
    }
  ],
  "note": "Batch payments allow you to pre-pay for multiple RPC calls at a discount"
}

Returns the RPC methods supported by the routed provider for a specific chain (or provider).

Query Parameters

curl 'https://x402labs.cloud/rpc-methods?chain=solana'

{
  "chain": "solana",
  "provider": "Helius",
  "methods": [
    "getSlot",
    "getBalance",
    "getLatestBlockhash",
    "getAccountInfo"
  ],
  "documentation": "https://docs.solana.com/api"
}

Execute an RPC call with intelligent provider routing and x402 payment.

Request Body

Response (200 Success)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 379462958,
  "x402": {
    "provider": "Helius",
    "paymentInfo": {
      "provider": "solana",
      "chain": "solana",
      "txHash": "5CTE...uRzh",
      "amount": 0.00015,
      "explorer": "https://orb.helius.dev/tx/5CTE...uRzh",
      "payer": "AyfXgR9SMs9GucxJReJqCHGCM2R6xgF29MwNAm7WR75k",
      "timestamp": "2025-10-28T19:12:40.582Z"
    },
    "cost": 0.00015,
    "status": "settled"
  }
}

Response (402 Payment Required)

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "asset": "USDC",
      "maxAmountRequired": "150",
      "payTo": "3HBV2F9C25k8169rKv6FDqQaFHj52NYH5JJjFYDoSnAZ",
      "resource": "https://x402labs.cloud/rpc",
      "description": "RPC access via Helius for solana",
      "extra": {
        "facilitator": {
          "primary": "x402labs",
          "type": "x402labs",
          "fallback": "CodeNut Pay"
        },
        "feePayer": "HsozMJWWHNADoZRmhDGKzua6XW6NNfNDdQ4CkE9i5wHt",
        "nonce": "1762898224761-0.11427330977237005"
    }
  }
  ]
}

Header: x402-payment
Value: JSON string

{
  "paymentPayload": {
    // Payment proof (varies by facilitator)
  },
  "paymentRequirements": {
    // Payment details
  }
}

{
  "type": "object",
  "required": ["paymentPayload", "paymentRequirements"],
  "properties": {
  "paymentPayload": {
      "type": "object",
      "description": "Facilitator-specific proof",
      "properties": {
    "signedIntent": {
          "type": "object",
          "properties": {
            "publicKey": { "type": "string" },
            "signature": { "type": "string" }
          }
    },
        "x402Version": { "type": "number" },
        "scheme": { "type": "string" },
        "network": { "type": "string" },
        "facilitator": { "type": "string" },
        "txBase64": { "type": "string" },
        "payload": {
          "type": "object",
          "properties": {
            "transaction": { "type": "string" }
          }
        }
      }
  },
  "paymentRequirements": {
      "type": "object",
      "properties": {
        "scheme": { "type": "string" },
        "network": { "type": "string" },
        "maxAmountRequired": { "type": ["string", "number"] },
        "amount": { "type": ["string", "number"] },
        "asset": { "type": ["string", "object"] },
        "payTo": { "type": "string" },
        "recipient": { "type": "string" },
        "resource": { "type": "string" },
        "description": { "type": "string" },
        "extra": { "type": "object" }
      }
    }
  }
}

🧠 Tip: Send monetary fields as strings (e.g., "150") to avoid JSON floating-point precision loss.

JavaScript example:

const payment = {
  paymentPayload: {
    signedIntent: { /* ... */ },
    txBase64: "...",  // x402labs only
    network: "solana"
  },
  paymentRequirements: {
    amount: 749,
    recipient: "26AvBMEXaJAfA2R7wtQiPNYeWUd8QSi6rvy5i5W78vNR",
    nonce: `${Date.now()}-${Math.random()}`
  }
};

const response = await fetch('https://x402labs.cloud/rpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x402-payment': JSON.stringify(payment)  // ← Stringified JSON
  },
  body: JSON.stringify({
    method: 'getSlot',
    params: [],
    chain: 'solana'
  })
});

The payment header is validated for:

• Valid JSON format
• Ed25519 signature verification (x402labs only)
• Recipient matches treasury wallet
• Nonce is unique (prevents replay attacks)
• x402labs: SOL transfer ≥ 890,880 lamports and txBase64 decodes to a valid transaction
• CodeNut: Base64 payload transaction includes compute budget instructions (positions 0 and 1) and matches quoted maxAmountRequired
• PayAI: Base64 payload transaction sets facilitator fee payer, instructions [limit, price, transfer], and passes SDK verification
• Optional batch metadata is stored server-side (x402-batch header) and decremented atomically

Check service health and provider status.

curl https://x402labs.cloud/health

Response

{
  "status": "ok",
  "timestamp": "2025-10-27T12:00:00.000Z",
  "version": "1.0.0",
  "chains": ["solana", "ethereum", "base"],
  "stats": {
    "totalProviders": 8,
    "activeProviders": 8,
    "healthyProviders": 7,
    "averageLatency": 312
  }
}

Get list of all RPC providers with real-time health status.

Query Parameters

curl 'https://x402labs.cloud/providers?chain=solana'

Response

{
  "providers": [
    {
      "id": "triton-solana",
      "name": "Triton One",
      "chains": ["solana"],
      "costPerCall": 0.0001,
      "batchCost": { "calls": 1000, "price": 0.08 },
      "status": "active",
      "priority": 100,
      "averageLatency": 245
    }
  ],
  "total": 1
}

Provider Details

Inspect telemetry, current latency, and cost for a specific provider.

GET /providers/triton-solana

{
  "id": "triton-solana",
  "name": "Triton One",
  "chains": ["solana"],
  "costPerCall": 0.00015,
  "batchCost": { "calls": 1000, "price": 0.12 },
  "status": "active",
  "priority": 90,
  "averageLatency": 241,
  "metadata": {
    "supportedMethods": ["getSlot", "getBalance", "..."],
    "dataCenters": ["us-east-1", "eu-central-1"]
  },
  "health": {
    "lastChecked": "2025-11-11T19:07:12.384Z",
    "lastStatus": "active",
    "consecutiveFailures": 0
  }
}

1. Lowest Cost (Default)

Selects the provider with the lowest cost per call.

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "lowest-cost"
  }
}

2. Lowest Latency

Selects the fastest provider based on real-time health checks.

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "lowest-latency",
    "maxLatencyMs": 2000
  }
}

3. Highest Priority

Uses premium providers first (e.g., Triton One for Solana).

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "highest-priority"
  }
}

4. Round Robin

Distributes load evenly across all providers.

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "round-robin"
  }
}

Availability is exposed via /facilitator. The 402 response mirrors this in accepts[].extra.facilitator.