{
  "schema_version": "1",
  "portal_version": "1.0.0-foundation",
  "updated_at": "2026-07-20",
  "source": "marco.public_portal",
  "provenance": "canonical_registry",
  "data": {
    "sdk_version": "2.10.2",
    "bundle_url": "https://marco.melega.ai/widgets/marco-connect.v2.10.js",
    "loader_url": "https://marco.melega.ai/widgets/marco.js",
    "element_global": "MarcoConnect",
    "installation_modes": [
      {
        "id": "loader",
        "note": "One script tag with a public site key. Configuration is remote.",
        "recommended": true
      },
      {
        "id": "sdk",
        "note": "Direct bundle + MarcoConnect.mount() for full control."
      },
      {
        "id": "plugin",
        "note": "WordPress plugin or Shopify app embed installs the loader for you."
      }
    ],
    "themes": [
      "dark",
      "light",
      "silver",
      "blue",
      "orange",
      "forest",
      "purple",
      "gold"
    ],
    "sizes": [
      "compact",
      "standard",
      "full",
      "navbar",
      "floating",
      "icon"
    ],
    "placements": [
      "top-right",
      "bottom-right",
      "bottom-left"
    ],
    "default_placement": "top-right",
    "config_fields": [
      {
        "name": "application",
        "note": "Host application name."
      },
      {
        "name": "theme",
        "note": "dark · light · silver · blue · orange · forest · purple · gold"
      },
      {
        "name": "size",
        "note": "compact · standard · full · navbar · floating"
      },
      {
        "name": "signature",
        "note": "Community signature visibility."
      },
      {
        "name": "language",
        "note": "BCP-47 tag. 2.0.0 ships en."
      },
      {
        "name": "origin",
        "note": "Portal origin used for links and the handshake."
      }
    ],
    "required_fields": [
      "application"
    ],
    "optional_fields": [
      "theme",
      "size",
      "signature",
      "language",
      "origin"
    ],
    "methods": [
      {
        "name": "connect()",
        "note": "Runs the wallet + Passport ceremony."
      },
      {
        "name": "disconnect()",
        "note": "Ends the session and clears state."
      },
      {
        "name": "open()",
        "note": "Expands the connected panel."
      },
      {
        "name": "close()",
        "note": "Collapses the connected panel."
      },
      {
        "name": "refresh()",
        "note": "Re-reads Passport and M-Credits."
      },
      {
        "name": "getState()",
        "note": "Readonly snapshot of the current state."
      },
      {
        "name": "on(event, fn)",
        "note": "Subscribe. Returns an unsubscribe function."
      },
      {
        "name": "destroy()",
        "note": "Unmounts the widget and drops listeners."
      }
    ],
    "events": [
      {
        "name": "ready",
        "note": "The SDK mounted and read its first state."
      },
      {
        "name": "connect",
        "note": "A wallet session was established."
      },
      {
        "name": "disconnect",
        "note": "The session ended."
      },
      {
        "name": "passportResolved",
        "note": "An existing Passport was found."
      },
      {
        "name": "passportCreated",
        "note": "A Passport was issued automatically."
      },
      {
        "name": "error",
        "note": "Any failure, with a stable code."
      },
      {
        "name": "change",
        "note": "Any state transition."
      }
    ],
    "state_fields": [
      {
        "name": "status",
        "note": "idle · loading · connecting · connected · disconnected · error"
      },
      {
        "name": "connected",
        "note": "Session present."
      },
      {
        "name": "loading",
        "note": "First read in flight."
      },
      {
        "name": "syncing",
        "note": "Background refresh in flight."
      },
      {
        "name": "wallet",
        "note": "{ address, chainId } or null."
      },
      {
        "name": "passport",
        "note": "{ passportNumber, publicPassportId, lifecycleStatus } or null."
      },
      {
        "name": "mCredits",
        "note": "{ available, currency, known }. Unknown stays unknown."
      },
      {
        "name": "application",
        "note": "The configured host application name."
      },
      {
        "name": "version",
        "note": "SDK semantic version."
      }
    ],
    "site_key": {
      "attribute": "data-marco-site",
      "prefix": "dsk_",
      "public": true,
      "secret": false,
      "client_safe": true,
      "authority": "MARCO deployment registry"
    },
    "security_boundaries": [
      "The widget never receives or requests a private key.",
      "The widget never asserts a balance; it renders what MARCO returns.",
      "No secret may be placed in any Connect configuration field.",
      "The site key identifies a deployment; it grants no authority."
    ],
    "schema": "/schemas/marco-connect-config.v1.json",
    "test_procedure": [
      "Install the snippet on a staging page served over HTTPS.",
      "Load the page and confirm the widget mounts with no console error.",
      "Run “Check installation” in the Partner Console; expect INSTALLED.",
      "Connect a test Passport and confirm passportResolved fires."
    ],
    "examples": [
      {
        "id": "html",
        "label": "HTML",
        "template": "<div id=\"marco-connect\"></div>\n<script src=\"https://marco.melega.ai/widgets/marco-connect.v2.10.js\" defer></script>\n<script>\n  window.addEventListener(\"load\", function () {\n    window.MarcoConnect.mount(\"#marco-connect\", { application: \"Your App\", theme: \"dark\", size: \"standard\" });\n  });\n</script>"
      },
      {
        "id": "react",
        "label": "React",
        "template": "import { useEffect, useRef } from \"react\";\n\nexport function MarcoConnect() {\n  const ref = useRef<HTMLDivElement>(null);\n  useEffect(() => {\n    const s = document.createElement(\"script\");\n    s.src = \"https://marco.melega.ai/widgets/marco-connect.v2.10.js\";\n    s.defer = true;\n    s.onload = () => window.MarcoConnect.mount(ref.current, { application: \"Your App\" });\n    document.body.appendChild(s);\n    return () => { s.remove(); };\n  }, []);\n  return <div ref={ref} />;\n}"
      },
      {
        "id": "nextjs",
        "label": "Next.js",
        "template": "\"use client\";\nimport Script from \"next/script\";\n\nexport function MarcoConnect() {\n  return (\n    <>\n      <div id=\"marco-connect\" />\n      <Script src=\"https://marco.melega.ai/widgets/marco-connect.v2.10.js\" strategy=\"afterInteractive\"\n        onLoad={() => window.MarcoConnect.mount(\"#marco-connect\", { application: \"Your App\" })} />\n    </>\n  );\n}"
      },
      {
        "id": "wordpress",
        "label": "WordPress",
        "template": "Install the official MARCO plugin (/downloads/marco-for-wordpress.zip) and pair it. No code required."
      },
      {
        "id": "woocommerce",
        "label": "WooCommerce",
        "template": "The MARCO plugin detects WooCommerce automatically. Enable MARCO Pay in the plugin settings."
      },
      {
        "id": "shopify",
        "label": "Shopify",
        "template": "Install MARCO for Shopify, enable the app embed block, then place the Pay with MARCO block on the product template."
      },
      {
        "id": "custom_website",
        "label": "Custom website (loader)",
        "template": "<script src=\"https://marco.melega.ai/widgets/marco.js\" data-marco-site=\"dsk_examplesitekey01\" defer></script>"
      }
    ],
    "recipes": "/api/public/machine/recipes"
  },
  "canonical_url": "/api/public/machine/connect",
  "machine_interface_version": "1",
  "machine_interface_release": "MP103_MACHINE_INTERFACE_V1",
  "machine_interface_updated_at": "2026-08-12"
}