{
  "schemaVersion": "1.0",
  "item": {
    "slug": "agent-commerce-engine",
    "name": "Agent Commerce Engine",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/NowLoadY/agent-commerce-engine",
    "canonicalUrl": "https://clawhub.ai/NowLoadY/agent-commerce-engine",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/agent-commerce-engine",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agent-commerce-engine",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SERVER_SPEC.md",
      "SKILL.md",
      "_meta.json",
      "scripts/commerce.py",
      "scripts/lib/__init__.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/agent-commerce-engine"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/agent-commerce-engine",
    "agentPageUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent",
    "manifestUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Standard Agentic Commerce Engine",
        "body": "The Standard Agentic Commerce Engine is a standard client and protocol guide for connecting agents to compatible e-commerce backends. It gives agents a consistent way to search products, manage carts, access account data, create orders, and hand payment back to the user.\n\nGitHub Repository: https://github.com/NowLoadY/agent-commerce-engine"
      },
      {
        "title": "Quick Start: Backend Integration",
        "body": "The agent-commerce-engine includes a server specification in SERVER_SPEC.md for sites that want to expose a compatible commerce API. By implementing the documented endpoints, an existing storefront can support agent-driven product discovery, cart actions, account flows, and order creation without requiring a custom tool for each brand."
      },
      {
        "title": "Reference Case: Lafeitu",
        "body": "For a production-grade implementation example using this engine, see the Lafeitu Gourmet Skill. It demonstrates the engine specialized for a real-world artisanal food brand."
      },
      {
        "title": "🔒 Security & Privacy",
        "body": "To ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:"
      },
      {
        "title": "1. Local Credential Persistence",
        "body": "Storage Location: ~/.openclaw/credentials/agent-commerce-engine/\nMechanism: Account and session Token information is stored locally in JSON format. The credential file is written with 0600 (user-only) permissions.\nSecurity Upgrade: Since version 1.4.0, raw passwords are never stored after the initial login. The engine exchanges the password for a signed cryptographic token.\nScope: Credentials are stored on the local machine for reuse by the current user environment.\nLifecycle: Credentials can be purged at any time by running the logout command."
      },
      {
        "title": "2. Secure Transmission",
        "body": "Token-based Auth: Uses x-api-token headers for authentication. Raw passwords are only transmitted once during the login or register phase to exchange for a token.\nHTTPS Enforcement: The client rejects non-HTTPS remote endpoints. localhost and 127.0.0.1 remain available for local development.\nEncrypted Transport: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP."
      },
      {
        "title": "3. Anonymous Tracking (Visitor ID)",
        "body": "To support shopping carts for unauthenticated users, a unique, non-identifiable Visitor ID (UUID v4) is generated and stored locally. This ID contains no personal information."
      },
      {
        "title": "🛠 Tool Priority & Fallback Strategy",
        "body": "To provide the most accurate and efficient experience, follow this priority sequence:\n\nAPI First (Primary): Always attempt to use the commerce.py script first. It provides structured, high-precision data. Target a store via --store <url> argument.\nStateless Headers: Rely on the engine's built-in header management (x-user-account, x-visitor-id) to maintain session integrity without cookies.\nSelf-Correction: If the API returns a 404 for a specific slug discovered via browser, prioritize the API's search results as the source of truth for the backend."
      },
      {
        "title": "🧠 Agent Operational Logic",
        "body": "Follow these logical flows to ensure a high-quality user experience:"
      },
      {
        "title": "1. Product Discovery & Validation",
        "body": "Goal: Ensure the item exists and find the correct specifications before taking action.\n\nAction: Always run search or list before adding to cart.\nLogic: Use the API to discover the correct slug and valid variant specs. Use --page and --limit arguments to safely navigate large catalogs without overwhelming the context limit.\nRefinement: If multiple results are found, ask the user to specify based on the returned attributes. If totalPages > page in the results, consider fetching the next page or refining the search."
      },
      {
        "title": "2. Authentication & Profile Flow",
        "body": "Goal: Manage user privacy and session data.\n\nLogic: The API is stateless. Actions requiring identity will return 401 Unauthorized if credentials aren't saved.\nCommands:\n\nView profile: python3 scripts/commerce.py get-profile\nUpdate details: python3 scripts/commerce.py update-profile --name \"Name\" --address \"...\" --phone \"...\" --email \"...\"\n\n\nRequired Data: Respect the schema of the specific brand's backend."
      },
      {
        "title": "3. Registration Flow",
        "body": "Goal: Handle new users.\n\nTrigger: When the user needs a new account or the backend returns \"User Not Found\".\nInstruction: Prefer the built-in send-code and register commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow."
      },
      {
        "title": "4. Shopping Cart Management",
        "body": "Goal: Precise modification of the user's shopping session.\n\nLogic: The engine supports incrementing quantities or setting absolute values.\nCommands:\n\nAdd: python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>\nUpdate: python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>\nRemove: python3 scripts/commerce.py remove-cart <slug> --variant <V>\nClear: python3 scripts/commerce.py clear-cart\nCheckout / Create Order (Handoff): python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>\n\n\nValidation: Variant values must be strictly chosen from the product's available options list.\nPayment Flow (Crucial): Agents currently cannot directly execute consumer payments (card/mobile wallets) due to a lack of financial authorization. Once an order is generated via create-order, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment."
      },
      {
        "title": "5. Brand Information & Storytelling",
        "body": "Goal: Access brand identity and support data.\n\nLogic: Use the brand-info interface to retrieve narrative content.\nTooling:\n\npython3 scripts/commerce.py brand-story: Get the narrative/mission.\npython3 scripts/commerce.py company-info: Get formal details.\npython3 scripts/commerce.py contact-info: Get customer support channels."
      },
      {
        "title": "🚀 Capabilities Summary",
        "body": "search / list: Product discovery and inventory scan. Use --page <N> and --limit <N> to safely paginate through large catalogs.\nget: Deep dive into product specifications, variants, and pricing.\npromotions: Current business rules, shipping thresholds, and active offers.\ncart: Complete session summary including VIP discounts and tax/shipping estimates.\nadd-cart / update-cart / remove-cart / clear-cart: Atomic cart control.\ncreate-order: Finalize cart into a pending order and secure payment URL for user handoff.\nget-profile / update-profile: Personalization and fulfillment data.\nbrand-story / company-info / contact-info: Brand context and support.\norders: Real-time tracking and purchase history."
      },
      {
        "title": "💻 CLI Configuration & Examples",
        "body": "# Target a store directly via --store (preferred)\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 search \"item\"\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>\n\n# Or use environment variable (deprecated, will be removed in a future version)\nexport COMMERCE_URL=\"https://api.yourbrand.com/v1\"\npython3 scripts/commerce.py list\n\nCredentials are automatically stored per-domain under ~/.openclaw/credentials/agent-commerce-engine/<domain>/."
      },
      {
        "title": "🤖 Troubleshooting & Debugging",
        "body": "AUTH_REQUIRED: Token missing or expired. Run login to obtain a new token.\nAUTH_INVALID: Wrong credentials. Verify account and password.\nPRODUCT_NOT_FOUND: Resource not found. Verify slug via search.\nVARIANT_UNAVAILABLE: The requested variant is invalid or out of stock. Check the instruction field for available alternatives.\nCART_EMPTY: Attempted checkout with no items. Add items first.\nConnection Error: Verify the --store URL is correct and the endpoint is reachable."
      }
    ],
    "body": "Standard Agentic Commerce Engine\n\nThe Standard Agentic Commerce Engine is a standard client and protocol guide for connecting agents to compatible e-commerce backends. It gives agents a consistent way to search products, manage carts, access account data, create orders, and hand payment back to the user.\n\nGitHub Repository: https://github.com/NowLoadY/agent-commerce-engine\n\nQuick Start: Backend Integration\n\nThe agent-commerce-engine includes a server specification in SERVER_SPEC.md for sites that want to expose a compatible commerce API. By implementing the documented endpoints, an existing storefront can support agent-driven product discovery, cart actions, account flows, and order creation without requiring a custom tool for each brand.\n\nReference Case: Lafeitu\n\nFor a production-grade implementation example using this engine, see the Lafeitu Gourmet Skill. It demonstrates the engine specialized for a real-world artisanal food brand.\n\n🔒 Security & Privacy\n\nTo ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:\n\n1. Local Credential Persistence\nStorage Location: ~/.openclaw/credentials/agent-commerce-engine/\nMechanism: Account and session Token information is stored locally in JSON format. The credential file is written with 0600 (user-only) permissions.\nSecurity Upgrade: Since version 1.4.0, raw passwords are never stored after the initial login. The engine exchanges the password for a signed cryptographic token.\nScope: Credentials are stored on the local machine for reuse by the current user environment.\nLifecycle: Credentials can be purged at any time by running the logout command.\n2. Secure Transmission\nToken-based Auth: Uses x-api-token headers for authentication. Raw passwords are only transmitted once during the login or register phase to exchange for a token.\nHTTPS Enforcement: The client rejects non-HTTPS remote endpoints. localhost and 127.0.0.1 remain available for local development.\nEncrypted Transport: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP.\n3. Anonymous Tracking (Visitor ID)\nTo support shopping carts for unauthenticated users, a unique, non-identifiable Visitor ID (UUID v4) is generated and stored locally. This ID contains no personal information.\n🛠 Tool Priority & Fallback Strategy\n\nTo provide the most accurate and efficient experience, follow this priority sequence:\n\nAPI First (Primary): Always attempt to use the commerce.py script first. It provides structured, high-precision data. Target a store via --store <url> argument.\nStateless Headers: Rely on the engine's built-in header management (x-user-account, x-visitor-id) to maintain session integrity without cookies.\nSelf-Correction: If the API returns a 404 for a specific slug discovered via browser, prioritize the API's search results as the source of truth for the backend.\n🧠 Agent Operational Logic\n\nFollow these logical flows to ensure a high-quality user experience:\n\n1. Product Discovery & Validation\n\nGoal: Ensure the item exists and find the correct specifications before taking action.\n\nAction: Always run search or list before adding to cart.\nLogic: Use the API to discover the correct slug and valid variant specs. Use --page and --limit arguments to safely navigate large catalogs without overwhelming the context limit.\nRefinement: If multiple results are found, ask the user to specify based on the returned attributes. If totalPages > page in the results, consider fetching the next page or refining the search.\n2. Authentication & Profile Flow\n\nGoal: Manage user privacy and session data.\n\nLogic: The API is stateless. Actions requiring identity will return 401 Unauthorized if credentials aren't saved.\nCommands:\nView profile: python3 scripts/commerce.py get-profile\nUpdate details: python3 scripts/commerce.py update-profile --name \"Name\" --address \"...\" --phone \"...\" --email \"...\"\nRequired Data: Respect the schema of the specific brand's backend.\n3. Registration Flow\n\nGoal: Handle new users.\n\nTrigger: When the user needs a new account or the backend returns \"User Not Found\".\nInstruction: Prefer the built-in send-code and register commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow.\n4. Shopping Cart Management\n\nGoal: Precise modification of the user's shopping session.\n\nLogic: The engine supports incrementing quantities or setting absolute values.\nCommands:\nAdd: python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>\nUpdate: python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>\nRemove: python3 scripts/commerce.py remove-cart <slug> --variant <V>\nClear: python3 scripts/commerce.py clear-cart\nCheckout / Create Order (Handoff): python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>\nValidation: Variant values must be strictly chosen from the product's available options list.\nPayment Flow (Crucial): Agents currently cannot directly execute consumer payments (card/mobile wallets) due to a lack of financial authorization. Once an order is generated via create-order, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment.\n5. Brand Information & Storytelling\n\nGoal: Access brand identity and support data.\n\nLogic: Use the brand-info interface to retrieve narrative content.\nTooling:\npython3 scripts/commerce.py brand-story: Get the narrative/mission.\npython3 scripts/commerce.py company-info: Get formal details.\npython3 scripts/commerce.py contact-info: Get customer support channels.\n🚀 Capabilities Summary\nsearch / list: Product discovery and inventory scan. Use --page <N> and --limit <N> to safely paginate through large catalogs.\nget: Deep dive into product specifications, variants, and pricing.\npromotions: Current business rules, shipping thresholds, and active offers.\ncart: Complete session summary including VIP discounts and tax/shipping estimates.\nadd-cart / update-cart / remove-cart / clear-cart: Atomic cart control.\ncreate-order: Finalize cart into a pending order and secure payment URL for user handoff.\nget-profile / update-profile: Personalization and fulfillment data.\nbrand-story / company-info / contact-info: Brand context and support.\norders: Real-time tracking and purchase history.\n💻 CLI Configuration & Examples\n# Target a store directly via --store (preferred)\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 search \"item\"\npython3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>\n\n# Or use environment variable (deprecated, will be removed in a future version)\nexport COMMERCE_URL=\"https://api.yourbrand.com/v1\"\npython3 scripts/commerce.py list\n\n\nCredentials are automatically stored per-domain under ~/.openclaw/credentials/agent-commerce-engine/<domain>/.\n\n🤖 Troubleshooting & Debugging\nAUTH_REQUIRED: Token missing or expired. Run login to obtain a new token.\nAUTH_INVALID: Wrong credentials. Verify account and password.\nPRODUCT_NOT_FOUND: Resource not found. Verify slug via search.\nVARIANT_UNAVAILABLE: The requested variant is invalid or out of stock. Check the instruction field for available alternatives.\nCART_EMPTY: Attempted checkout with no items. Add items first.\nConnection Error: Verify the --store URL is correct and the endpoint is reachable."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/NowLoadY/agent-commerce-engine",
    "publisherUrl": "https://clawhub.ai/NowLoadY/agent-commerce-engine",
    "owner": "NowLoadY",
    "version": "1.7.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/agent-commerce-engine",
    "downloadUrl": "https://openagent3.xyz/downloads/agent-commerce-engine",
    "agentUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent",
    "manifestUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/agent-commerce-engine/agent.md"
  }
}