{
  "openapi": "3.1.0",
  "info": {
    "title": "Fresh SEM Agent Backlink Checkout API",
    "version": "1.0.0",
    "description": "Create order-bound backlink quotes and verify direct USDC payments on Base, Polygon, or Solana."
  },
  "servers": [{"url": "https://freshsem.com"}],
  "paths": {
    "/scripts/agent_backlinks.php": {
      "get": {
        "summary": "Read service metadata",
        "responses": {"200": {"description": "Service metadata"}}
      },
      "post": {
        "summary": "Create a quote, read order status, or verify payment",
        "parameters": [
          {"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "minLength": 16, "maxLength": 128}, "description": "Required for quote creation."},
          {"name": "Order-Access-Token", "in": "header", "required": false, "schema": {"type": "string", "minLength": 32, "maxLength": 128}, "description": "Caller-generated secret required for quote creation and retained by the caller."},
          {"name": "Authorization", "in": "header", "required": false, "schema": {"type": "string"}, "description": "Bearer Order-Access-Token, required for status and verify actions."}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {"schema": {"oneOf": [
              {"$ref": "#/components/schemas/QuoteRequest"},
              {"$ref": "#/components/schemas/StatusRequest"},
              {"$ref": "#/components/schemas/VerifyRequest"}
            ]}},
            "application/json": {"schema": {"oneOf": [
              {"$ref": "#/components/schemas/QuoteRequest"},
              {"$ref": "#/components/schemas/StatusRequest"},
              {"$ref": "#/components/schemas/VerifyRequest"}
            ]}}
          }
        },
        "responses": {
          "200": {"description": "Status read or verified order", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}},
          "201": {"description": "Quote created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}},
          "400": {"description": "Invalid request"},
          "404": {"description": "Order or payment not found"},
          "409": {"description": "Conflict, insufficient finality, or payment mismatch"},
          "429": {"description": "Rate limited"}
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QuoteRequest": {
        "type": "object",
        "required": ["action", "email", "password", "target_url", "anchor_text", "quantity", "network", "payer_address"],
        "properties": {
          "action": {"const": "quote"},
          "email": {"type": "string", "format": "email"},
          "password": {"type": "string", "minLength": 8, "maxLength": 72},
          "target_url": {"type": "string", "format": "uri", "pattern": "^https?://"},
          "anchor_text": {"type": "string", "minLength": 1, "maxLength": 255},
          "quantity": {"type": "integer", "minimum": 1, "maximum": 20},
          "target_notes": {"type": "string", "maxLength": 2000},
          "network": {"type": "string", "enum": ["base", "polygon", "solana"]},
          "payer_address": {"type": "string", "description": "Wallet address that will send the quoted USDC."}
        }
      },
      "StatusRequest": {
        "type": "object",
        "required": ["action", "order_id"],
        "properties": {"action": {"const": "status"}, "order_id": {"type": "string", "format": "uuid"}}
      },
      "VerifyRequest": {
        "type": "object",
        "required": ["action", "order_id", "transaction_hash"],
        "properties": {
          "action": {"const": "verify"},
          "order_id": {"type": "string", "format": "uuid"},
          "transaction_hash": {"type": "string", "description": "EVM transaction hash or Solana signature."}
        }
      },
      "Order": {
        "type": "object",
        "required": ["ok", "order_id", "status", "network", "asset", "amount_atomic", "pay_to"],
        "properties": {
          "ok": {"type": "boolean"},
          "order_id": {"type": "string", "format": "uuid"},
          "status": {"type": "string", "enum": ["pending", "verifying", "payment_verified", "paid_conflict", "fulfilled"]},
          "network": {"type": "string", "enum": ["base", "polygon", "solana"]},
          "network_label": {"type": "string"},
          "asset": {"type": "string"},
          "asset_symbol": {"const": "USDC"},
          "amount_atomic": {"type": "string", "description": "Exact USDC amount in six-decimal atomic units."},
          "amount_usdc": {"type": "string", "pattern": "^[0-9]+\\.[0-9]{6}$", "description": "Exact USDC amount to transfer."},
          "amount_usd": {"type": "integer"},
          "pay_to": {"type": "string", "description": "Order-specific Base/Polygon deposit address or the Fresh SEM Solana recipient."},
          "payer_address": {"type": "string"},
          "memo": {"type": ["string", "null"]},
          "freshsem_order_id": {"type": "integer"},
          "order_url": {"type": "string", "format": "uri"}
        }
      }
    }
  }
}