# Send Agent Commerce Engine to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- 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.
## Suggested prompts
### New install

```text
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.
```
### Upgrade existing

```text
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.
```
## Machine-readable fields
```json
{
  "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": {
    "downloadUrl": "/downloads/agent-commerce-engine",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agent-commerce-engine",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "README.md",
      "SERVER_SPEC.md",
      "SKILL.md",
      "_meta.json",
      "scripts/commerce.py",
      "scripts/lib/__init__.py"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "agent-commerce-engine",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-29T05:55:10.703Z",
      "expiresAt": "2026-05-06T05:55:10.703Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agent-commerce-engine",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=agent-commerce-engine",
        "contentDisposition": "attachment; filename=\"agent-commerce-engine-1.7.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "agent-commerce-engine"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "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."
      ]
    }
  },
  "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"
  }
}
```
## Documentation

### Standard Agentic Commerce Engine

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.

GitHub Repository: https://github.com/NowLoadY/agent-commerce-engine

### Quick Start: Backend Integration

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.

### Reference Case: Lafeitu

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.

### 🔒 Security & Privacy

To ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:

### 1. Local Credential Persistence

Storage Location: ~/.openclaw/credentials/agent-commerce-engine/
Mechanism: Account and session Token information is stored locally in JSON format. The credential file is written with 0600 (user-only) permissions.
Security 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.
Scope: Credentials are stored on the local machine for reuse by the current user environment.
Lifecycle: Credentials can be purged at any time by running the logout command.

### 2. Secure Transmission

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.
HTTPS Enforcement: The client rejects non-HTTPS remote endpoints. localhost and 127.0.0.1 remain available for local development.
Encrypted Transport: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP.

### 3. Anonymous Tracking (Visitor ID)

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.

### 🛠 Tool Priority & Fallback Strategy

To provide the most accurate and efficient experience, follow this priority sequence:

API First (Primary): Always attempt to use the commerce.py script first. It provides structured, high-precision data. Target a store via --store <url> argument.
Stateless Headers: Rely on the engine's built-in header management (x-user-account, x-visitor-id) to maintain session integrity without cookies.
Self-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.

### 🧠 Agent Operational Logic

Follow these logical flows to ensure a high-quality user experience:

### 1. Product Discovery & Validation

Goal: Ensure the item exists and find the correct specifications before taking action.

Action: Always run search or list before adding to cart.
Logic: 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.
Refinement: 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.

### 2. Authentication & Profile Flow

Goal: Manage user privacy and session data.

Logic: The API is stateless. Actions requiring identity will return 401 Unauthorized if credentials aren't saved.
Commands:

View profile: python3 scripts/commerce.py get-profile
Update details: python3 scripts/commerce.py update-profile --name "Name" --address "..." --phone "..." --email "..."


Required Data: Respect the schema of the specific brand's backend.

### 3. Registration Flow

Goal: Handle new users.

Trigger: When the user needs a new account or the backend returns "User Not Found".
Instruction: 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.

### 4. Shopping Cart Management

Goal: Precise modification of the user's shopping session.

Logic: The engine supports incrementing quantities or setting absolute values.
Commands:

Add: python3 scripts/commerce.py add-cart <slug> --variant <V> --quantity <Q>
Update: python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>
Remove: python3 scripts/commerce.py remove-cart <slug> --variant <V>
Clear: python3 scripts/commerce.py clear-cart
Checkout / Create Order (Handoff): python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <ADDRESS>


Validation: Variant values must be strictly chosen from the product's available options list.
Payment 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.

### 5. Brand Information & Storytelling

Goal: Access brand identity and support data.

Logic: Use the brand-info interface to retrieve narrative content.
Tooling:

python3 scripts/commerce.py brand-story: Get the narrative/mission.
python3 scripts/commerce.py company-info: Get formal details.
python3 scripts/commerce.py contact-info: Get customer support channels.

### 🚀 Capabilities Summary

search / list: Product discovery and inventory scan. Use --page <N> and --limit <N> to safely paginate through large catalogs.
get: Deep dive into product specifications, variants, and pricing.
promotions: Current business rules, shipping thresholds, and active offers.
cart: Complete session summary including VIP discounts and tax/shipping estimates.
add-cart / update-cart / remove-cart / clear-cart: Atomic cart control.
create-order: Finalize cart into a pending order and secure payment URL for user handoff.
get-profile / update-profile: Personalization and fulfillment data.
brand-story / company-info / contact-info: Brand context and support.
orders: Real-time tracking and purchase history.

### 💻 CLI Configuration & Examples

# Target a store directly via --store (preferred)
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 search "item"
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart <slug> --variant <variant_id>

# Or use environment variable (deprecated, will be removed in a future version)
export COMMERCE_URL="https://api.yourbrand.com/v1"
python3 scripts/commerce.py list

Credentials are automatically stored per-domain under ~/.openclaw/credentials/agent-commerce-engine/<domain>/.

### 🤖 Troubleshooting & Debugging

AUTH_REQUIRED: Token missing or expired. Run login to obtain a new token.
AUTH_INVALID: Wrong credentials. Verify account and password.
PRODUCT_NOT_FOUND: Resource not found. Verify slug via search.
VARIANT_UNAVAILABLE: The requested variant is invalid or out of stock. Check the instruction field for available alternatives.
CART_EMPTY: Attempted checkout with no items. Add items first.
Connection Error: Verify the --store URL is correct and the endpoint is reachable.
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: NowLoadY
- Version: 1.7.1
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-29T05:55:10.703Z
- Expires at: 2026-05-06T05:55:10.703Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/agent-commerce-engine)
- [Send to Agent page](https://openagent3.xyz/skills/agent-commerce-engine/agent)
- [JSON manifest](https://openagent3.xyz/skills/agent-commerce-engine/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/agent-commerce-engine/agent.md)
- [Download page](https://openagent3.xyz/downloads/agent-commerce-engine)