Requirements JSON Schema

The Requirements Schema defines the structure of the JSON object returned by a server in an HTTP 402 Payment Required response when using the R402 profile.

This schema ensures all clients, SDKs, and facilitators can interpret rental offers consistently.

🧩 Root Structure


{
  "type": "object",
  "required": ["standard", "profile", "usage", "pay_to"],
  "properties": {
    "standard": { "type": "string", "const": "x402" },
    "profile": { "type": "string", "const": "r402/v1" },
    "resource": { "type": "string" },
    "usage": {
      "type": "object",
      "required": ["tiers"],
      "properties": {
        "modes": {
          "type": "array",
          "items": { "type": "string", "enum": ["view", "remix", "commercial-lite"] }
        },
        "tiers": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "duration_seconds", "price"],
            "properties": {
              "id": { "type": "string" },
              "label": { "type": "string" },
              "duration_seconds": { "type": "integer", "minimum": 60 },
              "price": {
                "type": "object",
                "required": ["amount", "currency"],
                "properties": {
                  "amount": { "type": "string" },
                  "currency": { "type": "string" },
                  "chain": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "pay_to": {
      "type": "object",
      "required": ["address"],
      "properties": {
        "address": { "type": "string" },
        "chain": { "type": "string" }
      }
    },
    "facilitator": { "type": "string", "format": "uri" },
    "nonce": { "type": "string" },
    "expires_at": { "type": "string", "format": "date-time" }
  }
}

🧠 Explanation

Field	Description
`standard`	Must be `"x402"` — ensures base protocol alignment.
`profile`	Identifies the R402 profile version (`r402/v1`).
`resource`	The unique identifier of the asset being rented or licensed.
`usage`	Core object defining how the resource can be used.
`usage.tiers`	Array of pricing tiers with durations and costs.
`usage.modes`	Optional array describing allowed usage actions.
`pay_to`	Wallet or on-chain account receiving payment.
`facilitator`	Optional verification endpoint for signed receipts.
`nonce`	Random value preventing replay attacks.
`expires_at`	Expiry timestamp for this pricing offer.

🧾 Example Response


{
  "standard": "x402",
  "profile": "r402/v1",
  "resource": "file:poster001.svg",
  "usage": {
    "modes": ["view", "remix"],
    "tiers": [
      { "id": "1d", "duration_seconds": 86400, "price": { "amount": "0.25", "currency": "USDC", "chain": "solana" } },
      { "id": "7d", "duration_seconds": 604800, "price": { "amount": "1.00", "currency": "USDC", "chain": "solana" } }
    ]
  },
  "pay_to": { "address": "SoLWallet111...", "chain": "solana" },
  "facilitator": "https://facilitator.fx402.xyz/settle",
  "nonce": "fa93...aa9",
  "expires_at": "2025-10-30T00:00:00Z"
}

🧩 Validation Notes

Clients should validate the presence of tiers before displaying pricing.
Servers may include additional fields — unknown properties must be ignored by clients for forward compatibility.
All numeric values (like duration_seconds) are integer seconds, not milliseconds.

✅ Highlights:

Fully formatted MDX (renders perfectly in Nextra)
JSON schema blocks with syntax highlighting
Table explanations of every field
Cross-links to the next relevant pages

Would you like me to continue with the next two (receipt-schema.mdx and metadata-extension.mdx) next?

Requirements JSON Schema

🧩 Root Structure

🧠 Explanation

🧾 Example Response

🧩 Validation Notes

📚 Related Documents