{
  "openapi": "3.1.0",
  "info": {
    "title": "free3d.io x402 API",
    "version": "2.0.0",
    "description": "Machine interface for AI agents: paywalled catalog access via x402 v2 (EIP-3009) and legacy on-chain settlement.",
    "contact": {
      "email": "free3dio@pm.me",
      "url": "https://free3d.io/x402/docs.html"
    },
    "x-guidance": "Model pages (/model/{slug}/{hash}) return HTTP 402 for AI agents. To pay: decode the PAYMENT-REQUIRED header, pick an accepts[] row (Base USDC EIP-3009 recommended, amount 100000 = $0.10), sign TransferWithAuthorization, retry with PAYMENT-SIGNATURE header. Free surfaces: /x402/teaser/{hash}, /x402/card/{hash}.json, listings under /x402/listing/. Docs: https://free3d.io/x402/docs.html. Pricing: https://free3d.io/x402/pricing.json."
  },
  "servers": [
    { "url": "https://free3d.io", "description": "Production" }
  ],
  "paths": {
    "/x402/verify": {
      "post": {
        "operationId": "exchangeTxForAccessToken",
        "summary": "Exchange an on-chain payment for a one-time access token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tx_hash", "network", "resource_id"],
                "properties": {
                  "tx_hash": { "type": "string", "description": "Blockchain transaction hash" },
                  "network": { "type": "string", "enum": ["ethereum", "base", "polygon", "arbitrum", "avalanche", "bnb", "solana", "tron"] },
                  "resource_id": { "type": "string", "description": "8-char model hash or request URI" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Access token issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "expires_in": { "type": "integer" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request" },
          "402": { "description": "Payment verification failed" }
        }
      }
    },
    "/x402/card/{hash}.json": {
      "get": {
        "operationId": "getModelPublicCard",
        "summary": "Public model metadata (no download URL)",
        "security": [],
        "parameters": [
          { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}$" } }
        ],
        "responses": {
          "200": { "description": "JSON card with citation, discovery links, related models" },
          "404": { "description": "Model not found" }
        }
      }
    },
    "/x402/teaser/{hash}": {
      "get": {
        "operationId": "getModelTeaserHtml",
        "summary": "Indexable HTML teaser for search bots",
        "security": [],
        "parameters": [
          { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}$" } }
        ],
        "responses": {
          "200": { "description": "HTML teaser (index,follow) with Schema.org 3DModel JSON-LD; canonical points to model page" },
          "404": { "description": "Model not found" }
        }
      }
    },
    "/x402/listing/category/{slug}/{id}": {
      "get": {
        "operationId": "getCategoryListingHtml",
        "summary": "Indexable HTML listing for a category (search bots)",
        "security": [],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "HTML listing (index,follow) with CollectionPage/ItemList JSON-LD" },
          "404": { "description": "Category not found or empty" }
        }
      }
    },
    "/x402/listing/tag/{tag}": {
      "get": {
        "operationId": "getTagListingHtml",
        "summary": "Indexable HTML listing for a tag (search bots)",
        "security": [],
        "parameters": [
          { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }
        ],
        "responses": {
          "200": { "description": "HTML listing (index,follow) with CollectionPage/ItemList JSON-LD" },
          "404": { "description": "Tag not found or empty" }
        }
      }
    },
    "/model/{slug}/{hash}": {
      "get": {
        "operationId": "getModelPage",
        "summary": "Model detail page (402 for unpaid AI agents)",
        "x-payment-info": {
          "protocols": [{ "x402": {} }],
          "price": { "fixed": { "mode": "fixed", "currency": "USD", "amount": "0.10" } },
          "description": "x402 v2 paywall. Decode PAYMENT-REQUIRED header for accepts[] (USDC/PYUSD/USDT on Base, Ethereum, Arbitrum, Solana, TRON); pay via PAYMENT-SIGNATURE (EIP-3009) or X-Payment. See https://free3d.io/x402/docs.html"
        },
        "security": [
          { "PaymentSignature": [] },
          { "XPayment": [] },
          { "ApiKey": [] },
          { "AccessToken": [] }
        ],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "Chair-3D-model-gsm3ds-for-interior-3d-visualization" },
          { "name": "hash", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{8}$" }, "example": "acedb0a3" }
        ],
        "responses": {
          "200": { "description": "HTML or markdown model page (paid / human)" },
          "401": {
            "description": "Payment required (legacy/CDN) — same as 402; decode PAYMENT-REQUIRED header",
            "headers": {
              "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded PaymentRequired JSON" },
              "X-X402-Status": { "schema": { "type": "string", "enum": ["payment_required"] } }
            }
          },
          "402": {
            "description": "Payment required — PAYMENT-REQUIRED header with x402 v2 JSON",
            "headers": {
              "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Base64-encoded PaymentRequired JSON" }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PaymentSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 v2 EIP-3009 PaymentPayload (base64 JSON)"
      },
      "XPayment": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Payment",
        "description": "Legacy: <tx_hash>:<network>"
      },
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Subscription API key (x402_...)"
      },
      "AccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Access-Token",
        "description": "One-time token from POST /x402/verify"
      }
    }
  },
  "externalDocs": {
    "url": "https://free3d.io/x402/docs.html",
    "description": "x402 integration guide for AI agents"
  },
  "x-discovery": {
    "ownershipProofs": [
      "0x51d1e2e73f41c4f15013d44Fbc5C48B86baD1638",
      "HjoWkMShHU14cjM2jzxXRaAbDdHXPD747HbwpS686YYu"
    ],
    "pricing": "https://free3d.io/x402/pricing.json",
    "wellKnownX402": "https://free3d.io/.well-known/x402"
  }
}