{
  "schemaVersion": "1.0",
  "item": {
    "slug": "moltpho",
    "name": "Moltpho",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/unifiedh/moltpho",
    "canonicalUrl": "https://clawhub.ai/unifiedh/moltpho",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/moltpho",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=moltpho",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "requirements.txt",
      "references/API.md",
      "references/POLICIES.md",
      "SKILL.md",
      "lib/proactive.py",
      "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. 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. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "slug": "moltpho",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-05T20:32:51.878Z",
      "expiresAt": "2026-05-12T20:32:51.878Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=moltpho",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=moltpho",
        "contentDisposition": "attachment; filename=\"moltpho-0.1.5.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "moltpho"
      },
      "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/moltpho"
    },
    "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/moltpho",
    "agentPageUrl": "https://openagent3.xyz/skills/moltpho/agent",
    "manifestUrl": "https://openagent3.xyz/skills/moltpho/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/moltpho/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. 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. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Moltpho Shopping Skill",
        "body": "Shop for items on Amazon autonomously using credit-backed mUSD tokens on Base mainnet."
      },
      {
        "title": "Overview",
        "body": "Moltpho is a headless shopping mall that enables AI agents to discover and purchase Amazon products using a credit system backed by mUSD (an ERC-20 token on Base mainnet). This skill handles:\n\nAgent registration and credential management\nProduct search and discovery\nAutonomous and proactive purchasing\nCredit balance monitoring\nx402 payment protocol integration"
      },
      {
        "title": "Bootstrap Flow",
        "body": "On first invocation, the skill MUST check for existing credentials and register if needed."
      },
      {
        "title": "Credentials Location",
        "body": "PlatformPathLinux/macOS~/.config/moltpho/credentials.jsonWindows%APPDATA%\\moltpho\\credentials.jsonOverrideMOLTPHO_CREDENTIALS_PATH environment variable"
      },
      {
        "title": "Registration Process",
        "body": "Check credentials file at the appropriate path\nIf missing, call POST /v1/agents/register with:\n\nopenclaw_instance_id (if available)\nagent_display_name\nagent_description\nNo shipping profile required at registration\n\n\nSave credentials with chmod 600 permissions\nAuto-open browser with notice: \"Opening portal in your browser to complete setup...\"\nRegistration proceeds WITHOUT shipping profile - orders will fail until owner adds one via portal"
      },
      {
        "title": "Credentials File Format",
        "body": "{\n  \"agent_id\": \"uuid\",\n  \"api_key_id\": \"moltpho_key_...\",\n  \"api_key_secret\": \"moltpho_secret_...\",\n  \"api_base_url\": \"https://api.moltpho.com\",\n  \"wallet_address\": \"0xabc123...\"\n}"
      },
      {
        "title": "bootstrap()",
        "body": "Initialize agent credentials and open portal for owner setup.\n\n1. Check if credentials file exists at platform-specific path\n2. If exists and valid: load credentials, verify with GET /v1/agents/me\n3. If missing or invalid:\n   a. Call POST /v1/agents/register (no auth required)\n   b. Receive: agent_id, api_key_id, api_key_secret, claim_url, wallet_address\n   c. Write credentials file with chmod 600\n   d. Display: \"Opening portal in your browser to complete setup...\"\n   e. Open browser to claim_url (valid for 24 hours)\n4. Return agent status (UNCLAIMED, CLAIMED, DEGRADED, SUSPENDED)"
      },
      {
        "title": "collect_shipping_profile()",
        "body": "Optionally collect shipping information from the owner.\n\nNote: This is OPTIONAL. Owners can configure shipping via the portal instead.\n      Orders will fail with INVALID_SHIPPING_PROFILE until a profile exists.\n\nIf collecting in conversation:\n1. Request full name\n2. Request address (street, city, state, ZIP)\n3. Request email\n4. Request phone\n5. Validate: US addresses only (international not supported in v1)\n6. Call POST /v1/shipping_profiles (upsert_shipping_profile)\n7. Confirm profile saved\n\nThe POST endpoint upserts the default profile:\n- If no profile exists, creates one\n- If a profile exists, updates it"
      },
      {
        "title": "update_shipping_profile()",
        "body": "Update the shipping address for the agent.\n\nParameters:\n- full_name: Recipient full name\n- address1: Street address\n- address2: Apt/suite (optional)\n- city: City\n- state: State (2-letter code)\n- postal_code: ZIP code\n- email: Contact email\n- phone: Contact phone\n\nProcess:\n1. Validate all required fields\n2. Validate US address (only US supported in v1)\n3. Call POST /v1/shipping_profiles (upserts default profile)\n4. Return updated profile\n\nUse cases:\n- \"Update my shipping address\"\n- \"Change my delivery address to...\"\n- First-time setup during bootstrap"
      },
      {
        "title": "catalog_search(query, constraints)",
        "body": "Search for products on Amazon via Moltpho.\n\nParameters:\n- query: Search terms (string)\n- constraints: Optional filters\n  - max_price: Maximum price in USD\n  - category: Product category keyword\n  - min_rating: Minimum star rating (1-5)\n\nProcess:\n1. Call GET /v1/catalog/search?query={query}&limit=20\n2. Apply local constraints if provided\n3. Present results with:\n   - Product title and brand\n   - Moltpho price (final price, includes 10% markup)\n   - Availability status\n   - Rating if available\n4. If cache expired, results include \"prices may have changed\" warning\n\nRate limit: 60 requests/minute"
      },
      {
        "title": "purchase(item, qty)",
        "body": "Execute a purchase through the x402 payment flow.\n\nParameters:\n- item: ASIN or product identifier\n- qty: Quantity (default 1)\n\nProcess:\n1. BUDGET CHECK: Call GET /v1/balance to verify available credit\n   - available_credit = balance - active_reservations\n   - Check against per_order_cap if set\n   - Check against daily_cap if set\n\n2. CREATE QUOTE: Call POST /v1/quotes\n   - Include: asin, quantity, shipping_profile_id\n   - Returns: quote_id, total_due_usd, expires_at (10 min TTL)\n   - Creates soft reservation against balance\n   - May fail with INVALID_SHIPPING_PROFILE if no profile set\n\n3. INITIATE ORDER: Call POST /v1/orders with quote_id\n   - First call returns 402 Payment Required with PAYMENT-REQUIRED header\n\n4. SIGN PAYMENT: Call POST /v1/wallets/x402/sign\n   - Include: payment_required blob, idempotency_key\n   - Returns: payment_signature for x402 header\n\n5. COMPLETE ORDER: Retry POST /v1/orders with PAYMENT-SIGNATURE header\n   - On success: returns order_id, status (PAID/PLACED)\n   - Soft reservation converted to actual spend\n\nAuto-retry on quote expiry:\n- If quote expires during flow, automatically retry up to 3 times\n- Only retry if new price is within 5% of original quote\n- Fail after 3 retries or if price changed >5%\n\nRate limits:\n- Quotes: 20/minute\n- Orders: 5/minute\n- Signing: 10/minute"
      },
      {
        "title": "proactive_monitoring()",
        "body": "Watch conversation for purchase need signals and act when appropriate.\n\nThis function runs passively during conversation to detect purchase opportunities.\n\nNEED SIGNALS (explicit):\n- \"I need\", \"we're out of\", \"buy\", \"order\", \"replace\"\n- \"running low on\", \"almost out of\"\n- Direct product mentions with urgency\n\nNEED SIGNALS (implicit):\n- Repeated complaints about missing items\n- Critical item shortages mentioned\n- Context suggesting immediate need\n\nCONFIDENCE SCORING:\n- 1.0: Explicit purchase request (\"buy me X\")\n- 0.8: Strong implied need (\"we're completely out of toilet paper\")\n- 0.5: Weak implied convenience (do NOT buy)\n- 0.0: Unknown/unclear\n\nBUDGET SIGNAL HANDLING:\n- Phrases like \"money is tight\", \"on a budget\", \"can't afford\"\n- Reduce confidence by 0.3-0.5\n- Proceed cautiously if still above threshold\n\nPROACTIVE PURCHASE ALLOWED IF ALL TRUE:\n- Owner has enabled proactive purchasing (default ON)\n- Confidence >= 0.8 (threshold)\n- Item matches low-risk categories:\n  - Household essentials\n  - Office supplies\n  - Cables/adapters\n  - Basic kitchen items\n  - Toiletries\n- Price <= min(per_order_cap, $75)\n- Item keywords not in denied categories\n- Item not in system blocklist\n- Shipping profile exists\n\nLOGGING:\nEvery purchase logs:\n- \"why we bought\" (decision reason)\n- Signals detected\n- Confidence tier (HIGH/MEDIUM/LOW)\n- Budget impact"
      },
      {
        "title": "budget_check()",
        "body": "Verify sufficient credit before any purchase.\n\nProcess:\n1. Call GET /v1/balance\n2. Response includes:\n   - available_credit_cents: Spendable amount\n   - staged_refunds: Pending refunds (shown with asterisk)\n   - target_limit: Owner's configured credit limit\n3. Compare against:\n   - Quote total\n   - per_order_cap (if set)\n   - daily_cap (if set, track daily spending)\n4. Return: can_purchase (bool), available_amount, reason_if_blocked"
      },
      {
        "title": "create_support_ticket(type, description, order_id)",
        "body": "Create a support ticket for returns, lost packages, or other issues.\n\nParameters:\n- type: Ticket type - RETURN, LOST_PACKAGE, or OTHER\n- description: Detailed description of the issue (1-2000 chars)\n- order_id: Order ID (required for RETURN and LOST_PACKAGE)\n\nProcess:\n1. Validate ticket type and description\n2. If RETURN or LOST_PACKAGE, verify order_id is provided\n3. Call POST /v1/support_tickets with { type, description, order_id }\n4. Return ticket ID and status\n\nUse cases:\n- \"I want to return this item\" → type=RETURN, link to order\n- \"My package never arrived\" → type=LOST_PACKAGE, link to order\n- \"I have a question about billing\" → type=OTHER, no order needed\n\nNote: Returns and lost packages require a support ticket.\n      Automated refunds only happen for order cancellations."
      },
      {
        "title": "list_support_tickets()",
        "body": "List the agent's support tickets.\n\nProcess:\n1. Call GET /v1/support_tickets\n2. Display tickets with: type, status, order link, creation date\n3. Status meanings:\n   - OPEN: Submitted, awaiting support review\n   - IN_PROGRESS: Being handled\n   - WAITING_CUSTOMER: Support needs more info from you\n   - RESOLVED: Issue resolved\n   - CLOSED: Ticket closed"
      },
      {
        "title": "logout()",
        "body": "Delete local credentials (agent persists server-side).\n\nProcess:\n1. Delete credentials file at platform-specific path\n2. Display: \"Credentials removed. Agent still exists on Moltpho servers.\"\n3. To fully delete agent, owner must use portal\n\nNote: This only removes LOCAL credentials. The agent account, wallet, and\n      purchase history remain on Moltpho servers until owner deletes via portal."
      },
      {
        "title": "Browser Portal Usage",
        "body": "The skill uses the browser for owner-sensitive operations."
      },
      {
        "title": "When to Open Browser",
        "body": "ActionMethodComplete setup (claim link)Auto-open with noticeAdd/manage payment cardsDirect owner to portalSet credit limitsDirect owner to portalConfigure shipping profileDirect owner to portalView order historyDirect owner to portal"
      },
      {
        "title": "Browser Guidelines",
        "body": "Always display notice: \"Opening portal in your browser...\"\nNEVER request card numbers, passwords, or sensitive credentials in chat\nPortal handles all PCI-sensitive operations via Stripe Elements\nOwner authenticates via magic link (email-based)"
      },
      {
        "title": "API Authentication",
        "body": "All API requests (except registration) require authentication."
      },
      {
        "title": "Headers",
        "body": "Authorization: Bearer <api_key_secret>\n\nOr preferably:\n\nX-Moltpho-Key-Id: <api_key_id>\nX-Moltpho-Signature: <HMAC signature>"
      },
      {
        "title": "Idempotency",
        "body": "For state-changing operations, always include:\n\nIdempotency-Key: <unique-key>\n\nRequired for:\n\nPOST /v1/quotes\nPOST /v1/orders\nPOST /v1/wallets/x402/sign"
      },
      {
        "title": "Common Errors",
        "body": "CodeErrorAction401UNAUTHORIZEDRe-bootstrap or check credentials402PAYMENT_REQUIREDSign and retry with x402 signature409PRICE_CHANGEDRe-quote if price increased >2%409INSUFFICIENT_CREDITInform user, suggest adding credit409QUOTE_EXPIREDAuto-retry (up to 3x) or re-quote422INVALID_SHIPPING_PROFILEPrompt owner to add shipping via portal422AGENT_SUSPENDEDInform owner, direct to portal429RATE_LIMITEDWait per Retry-After header503TOKEN_PAUSEDSystem halted, wait for admin"
      },
      {
        "title": "Quote Expiry Auto-Retry",
        "body": "When a quote expires during the x402 flow:\n\nFetch new quote for same item\nCompare price to original quote\nIf within 5% tolerance: continue with new quote\nIf >5% change: fail with PRICE_CHANGED\nMaximum 3 retry attempts"
      },
      {
        "title": "System Limits",
        "body": "LimitValueMaximum item price$10,000 USDQuote TTL10 minutes (fixed)Price tolerance2% increase allowedRetry price tolerance5% for auto-retryMax concurrent quotes5 per agentProactive purchase capmin(per_order_cap, $75)"
      },
      {
        "title": "Rate Limits",
        "body": "EndpointLimitCatalog search60/minuteQuotes20/minuteOrders5/minuteSigning10/minute"
      },
      {
        "title": "Blocked Items (System Enforced)",
        "body": "The following categories CANNOT be purchased regardless of owner settings:\n\nWeapons, firearms, ammunition\nControlled substances, prescription medications\nTobacco, nicotine products\nAlcohol\nAdult content\nHazardous materials"
      },
      {
        "title": "Credit Model",
        "body": "Owner sets target credit limit in USD\nWeekly automatic top-up restores credit to target\nCredit backed by mUSD tokens on Base mainnet\n10% markup over Amazon prices (covers fees + gas)"
      },
      {
        "title": "x402 Flow",
        "body": "POST /v1/orders returns 402 with PAYMENT-REQUIRED header\nCall POST /v1/wallets/x402/sign with payment blob\nWallet service signs EIP-3009 authorization\nRetry order with PAYMENT-SIGNATURE header\nFacilitator settles on Base mainnet\nOrder proceeds to fulfillment"
      },
      {
        "title": "Refunds",
        "body": "ScenarioRefund TargetProcurement failuremUSD balance (auto)Order canceled (within 5 min)mUSD balance (auto)Owner decreases credit limitCard via StripeReturn/lost packageSupport ticket required (use create_support_ticket)"
      },
      {
        "title": "Agent States",
        "body": "StateMeaningCan Order?UNCLAIMEDRegistered, awaiting owner claimNoCLAIMEDOwner claimed, fully operationalYesDEGRADEDPayment methods failed, using remaining balanceYes (if balance)SUSPENDEDAdmin action, requires manual resolutionNo"
      },
      {
        "title": "Before Any Purchase",
        "body": "Call budget_check() to verify available credit\nConfirm shipping profile exists\nCheck item against category denylist\nVerify confidence threshold for proactive purchases"
      },
      {
        "title": "Conversation Guidelines",
        "body": "Always confirm purchase with total price before executing\nReport order status and remaining credit after purchase\nIf budget signals detected, acknowledge constraints\nNever pressure user to add more credit"
      },
      {
        "title": "Error Recovery",
        "body": "On INSUFFICIENT_CREDIT: suggest adding credit via portal\nOn INVALID_SHIPPING_PROFILE: collect shipping info and call upsert_shipping_profile(), or direct to portal\nOn SUSPENDED: explain owner must resolve via portal"
      },
      {
        "title": "Essential Endpoints",
        "body": "EndpointPurposePOST /v1/agents/registerNew agent registrationGET /v1/agents/meCurrent agent statusGET /v1/balanceAvailable creditGET /v1/catalog/searchSearch productsPOST /v1/quotesCreate purchase quotePOST /v1/ordersPlace order (x402)POST /v1/wallets/x402/signSign paymentGET /v1/shipping_profilesList shipping profilesPOST /v1/shipping_profilesCreate/update shipping profilePOST /v1/support_ticketsCreate support ticketGET /v1/support_ticketsList support tickets"
      },
      {
        "title": "Portal URL",
        "body": "https://portal.moltpho.com\n\nOwner actions:\n\n/claim/{token} - Claim agent ownership\n/agents - Manage agents\n/cards - Payment methods\n/orders - Order history\n/settings - Credit limits and preferences"
      }
    ],
    "body": "Moltpho Shopping Skill\n\nShop for items on Amazon autonomously using credit-backed mUSD tokens on Base mainnet.\n\nOverview\n\nMoltpho is a headless shopping mall that enables AI agents to discover and purchase Amazon products using a credit system backed by mUSD (an ERC-20 token on Base mainnet). This skill handles:\n\nAgent registration and credential management\nProduct search and discovery\nAutonomous and proactive purchasing\nCredit balance monitoring\nx402 payment protocol integration\nBootstrap Flow\n\nOn first invocation, the skill MUST check for existing credentials and register if needed.\n\nCredentials Location\nPlatform\tPath\nLinux/macOS\t~/.config/moltpho/credentials.json\nWindows\t%APPDATA%\\moltpho\\credentials.json\nOverride\tMOLTPHO_CREDENTIALS_PATH environment variable\nRegistration Process\nCheck credentials file at the appropriate path\nIf missing, call POST /v1/agents/register with:\nopenclaw_instance_id (if available)\nagent_display_name\nagent_description\nNo shipping profile required at registration\nSave credentials with chmod 600 permissions\nAuto-open browser with notice: \"Opening portal in your browser to complete setup...\"\nRegistration proceeds WITHOUT shipping profile - orders will fail until owner adds one via portal\nCredentials File Format\n{\n  \"agent_id\": \"uuid\",\n  \"api_key_id\": \"moltpho_key_...\",\n  \"api_key_secret\": \"moltpho_secret_...\",\n  \"api_base_url\": \"https://api.moltpho.com\",\n  \"wallet_address\": \"0xabc123...\"\n}\n\nCore Functions\nbootstrap()\n\nInitialize agent credentials and open portal for owner setup.\n\n1. Check if credentials file exists at platform-specific path\n2. If exists and valid: load credentials, verify with GET /v1/agents/me\n3. If missing or invalid:\n   a. Call POST /v1/agents/register (no auth required)\n   b. Receive: agent_id, api_key_id, api_key_secret, claim_url, wallet_address\n   c. Write credentials file with chmod 600\n   d. Display: \"Opening portal in your browser to complete setup...\"\n   e. Open browser to claim_url (valid for 24 hours)\n4. Return agent status (UNCLAIMED, CLAIMED, DEGRADED, SUSPENDED)\n\ncollect_shipping_profile()\n\nOptionally collect shipping information from the owner.\n\nNote: This is OPTIONAL. Owners can configure shipping via the portal instead.\n      Orders will fail with INVALID_SHIPPING_PROFILE until a profile exists.\n\nIf collecting in conversation:\n1. Request full name\n2. Request address (street, city, state, ZIP)\n3. Request email\n4. Request phone\n5. Validate: US addresses only (international not supported in v1)\n6. Call POST /v1/shipping_profiles (upsert_shipping_profile)\n7. Confirm profile saved\n\nThe POST endpoint upserts the default profile:\n- If no profile exists, creates one\n- If a profile exists, updates it\n\nupdate_shipping_profile()\n\nUpdate the shipping address for the agent.\n\nParameters:\n- full_name: Recipient full name\n- address1: Street address\n- address2: Apt/suite (optional)\n- city: City\n- state: State (2-letter code)\n- postal_code: ZIP code\n- email: Contact email\n- phone: Contact phone\n\nProcess:\n1. Validate all required fields\n2. Validate US address (only US supported in v1)\n3. Call POST /v1/shipping_profiles (upserts default profile)\n4. Return updated profile\n\nUse cases:\n- \"Update my shipping address\"\n- \"Change my delivery address to...\"\n- First-time setup during bootstrap\n\ncatalog_search(query, constraints)\n\nSearch for products on Amazon via Moltpho.\n\nParameters:\n- query: Search terms (string)\n- constraints: Optional filters\n  - max_price: Maximum price in USD\n  - category: Product category keyword\n  - min_rating: Minimum star rating (1-5)\n\nProcess:\n1. Call GET /v1/catalog/search?query={query}&limit=20\n2. Apply local constraints if provided\n3. Present results with:\n   - Product title and brand\n   - Moltpho price (final price, includes 10% markup)\n   - Availability status\n   - Rating if available\n4. If cache expired, results include \"prices may have changed\" warning\n\nRate limit: 60 requests/minute\n\npurchase(item, qty)\n\nExecute a purchase through the x402 payment flow.\n\nParameters:\n- item: ASIN or product identifier\n- qty: Quantity (default 1)\n\nProcess:\n1. BUDGET CHECK: Call GET /v1/balance to verify available credit\n   - available_credit = balance - active_reservations\n   - Check against per_order_cap if set\n   - Check against daily_cap if set\n\n2. CREATE QUOTE: Call POST /v1/quotes\n   - Include: asin, quantity, shipping_profile_id\n   - Returns: quote_id, total_due_usd, expires_at (10 min TTL)\n   - Creates soft reservation against balance\n   - May fail with INVALID_SHIPPING_PROFILE if no profile set\n\n3. INITIATE ORDER: Call POST /v1/orders with quote_id\n   - First call returns 402 Payment Required with PAYMENT-REQUIRED header\n\n4. SIGN PAYMENT: Call POST /v1/wallets/x402/sign\n   - Include: payment_required blob, idempotency_key\n   - Returns: payment_signature for x402 header\n\n5. COMPLETE ORDER: Retry POST /v1/orders with PAYMENT-SIGNATURE header\n   - On success: returns order_id, status (PAID/PLACED)\n   - Soft reservation converted to actual spend\n\nAuto-retry on quote expiry:\n- If quote expires during flow, automatically retry up to 3 times\n- Only retry if new price is within 5% of original quote\n- Fail after 3 retries or if price changed >5%\n\nRate limits:\n- Quotes: 20/minute\n- Orders: 5/minute\n- Signing: 10/minute\n\nproactive_monitoring()\n\nWatch conversation for purchase need signals and act when appropriate.\n\nThis function runs passively during conversation to detect purchase opportunities.\n\nNEED SIGNALS (explicit):\n- \"I need\", \"we're out of\", \"buy\", \"order\", \"replace\"\n- \"running low on\", \"almost out of\"\n- Direct product mentions with urgency\n\nNEED SIGNALS (implicit):\n- Repeated complaints about missing items\n- Critical item shortages mentioned\n- Context suggesting immediate need\n\nCONFIDENCE SCORING:\n- 1.0: Explicit purchase request (\"buy me X\")\n- 0.8: Strong implied need (\"we're completely out of toilet paper\")\n- 0.5: Weak implied convenience (do NOT buy)\n- 0.0: Unknown/unclear\n\nBUDGET SIGNAL HANDLING:\n- Phrases like \"money is tight\", \"on a budget\", \"can't afford\"\n- Reduce confidence by 0.3-0.5\n- Proceed cautiously if still above threshold\n\nPROACTIVE PURCHASE ALLOWED IF ALL TRUE:\n- Owner has enabled proactive purchasing (default ON)\n- Confidence >= 0.8 (threshold)\n- Item matches low-risk categories:\n  - Household essentials\n  - Office supplies\n  - Cables/adapters\n  - Basic kitchen items\n  - Toiletries\n- Price <= min(per_order_cap, $75)\n- Item keywords not in denied categories\n- Item not in system blocklist\n- Shipping profile exists\n\nLOGGING:\nEvery purchase logs:\n- \"why we bought\" (decision reason)\n- Signals detected\n- Confidence tier (HIGH/MEDIUM/LOW)\n- Budget impact\n\nbudget_check()\n\nVerify sufficient credit before any purchase.\n\nProcess:\n1. Call GET /v1/balance\n2. Response includes:\n   - available_credit_cents: Spendable amount\n   - staged_refunds: Pending refunds (shown with asterisk)\n   - target_limit: Owner's configured credit limit\n3. Compare against:\n   - Quote total\n   - per_order_cap (if set)\n   - daily_cap (if set, track daily spending)\n4. Return: can_purchase (bool), available_amount, reason_if_blocked\n\ncreate_support_ticket(type, description, order_id)\n\nCreate a support ticket for returns, lost packages, or other issues.\n\nParameters:\n- type: Ticket type - RETURN, LOST_PACKAGE, or OTHER\n- description: Detailed description of the issue (1-2000 chars)\n- order_id: Order ID (required for RETURN and LOST_PACKAGE)\n\nProcess:\n1. Validate ticket type and description\n2. If RETURN or LOST_PACKAGE, verify order_id is provided\n3. Call POST /v1/support_tickets with { type, description, order_id }\n4. Return ticket ID and status\n\nUse cases:\n- \"I want to return this item\" → type=RETURN, link to order\n- \"My package never arrived\" → type=LOST_PACKAGE, link to order\n- \"I have a question about billing\" → type=OTHER, no order needed\n\nNote: Returns and lost packages require a support ticket.\n      Automated refunds only happen for order cancellations.\n\nlist_support_tickets()\n\nList the agent's support tickets.\n\nProcess:\n1. Call GET /v1/support_tickets\n2. Display tickets with: type, status, order link, creation date\n3. Status meanings:\n   - OPEN: Submitted, awaiting support review\n   - IN_PROGRESS: Being handled\n   - WAITING_CUSTOMER: Support needs more info from you\n   - RESOLVED: Issue resolved\n   - CLOSED: Ticket closed\n\nlogout()\n\nDelete local credentials (agent persists server-side).\n\nProcess:\n1. Delete credentials file at platform-specific path\n2. Display: \"Credentials removed. Agent still exists on Moltpho servers.\"\n3. To fully delete agent, owner must use portal\n\nNote: This only removes LOCAL credentials. The agent account, wallet, and\n      purchase history remain on Moltpho servers until owner deletes via portal.\n\nBrowser Portal Usage\n\nThe skill uses the browser for owner-sensitive operations.\n\nWhen to Open Browser\nAction\tMethod\nComplete setup (claim link)\tAuto-open with notice\nAdd/manage payment cards\tDirect owner to portal\nSet credit limits\tDirect owner to portal\nConfigure shipping profile\tDirect owner to portal\nView order history\tDirect owner to portal\nBrowser Guidelines\nAlways display notice: \"Opening portal in your browser...\"\nNEVER request card numbers, passwords, or sensitive credentials in chat\nPortal handles all PCI-sensitive operations via Stripe Elements\nOwner authenticates via magic link (email-based)\nAPI Authentication\n\nAll API requests (except registration) require authentication.\n\nHeaders\nAuthorization: Bearer <api_key_secret>\n\n\nOr preferably:\n\nX-Moltpho-Key-Id: <api_key_id>\nX-Moltpho-Signature: <HMAC signature>\n\nIdempotency\n\nFor state-changing operations, always include:\n\nIdempotency-Key: <unique-key>\n\n\nRequired for:\n\nPOST /v1/quotes\nPOST /v1/orders\nPOST /v1/wallets/x402/sign\nError Handling\nCommon Errors\nCode\tError\tAction\n401\tUNAUTHORIZED\tRe-bootstrap or check credentials\n402\tPAYMENT_REQUIRED\tSign and retry with x402 signature\n409\tPRICE_CHANGED\tRe-quote if price increased >2%\n409\tINSUFFICIENT_CREDIT\tInform user, suggest adding credit\n409\tQUOTE_EXPIRED\tAuto-retry (up to 3x) or re-quote\n422\tINVALID_SHIPPING_PROFILE\tPrompt owner to add shipping via portal\n422\tAGENT_SUSPENDED\tInform owner, direct to portal\n429\tRATE_LIMITED\tWait per Retry-After header\n503\tTOKEN_PAUSED\tSystem halted, wait for admin\nQuote Expiry Auto-Retry\n\nWhen a quote expires during the x402 flow:\n\nFetch new quote for same item\nCompare price to original quote\nIf within 5% tolerance: continue with new quote\nIf >5% change: fail with PRICE_CHANGED\nMaximum 3 retry attempts\nConstraints and Limits\nSystem Limits\nLimit\tValue\nMaximum item price\t$10,000 USD\nQuote TTL\t10 minutes (fixed)\nPrice tolerance\t2% increase allowed\nRetry price tolerance\t5% for auto-retry\nMax concurrent quotes\t5 per agent\nProactive purchase cap\tmin(per_order_cap, $75)\nRate Limits\nEndpoint\tLimit\nCatalog search\t60/minute\nQuotes\t20/minute\nOrders\t5/minute\nSigning\t10/minute\nBlocked Items (System Enforced)\n\nThe following categories CANNOT be purchased regardless of owner settings:\n\nWeapons, firearms, ammunition\nControlled substances, prescription medications\nTobacco, nicotine products\nAlcohol\nAdult content\nHazardous materials\nPayment System\nCredit Model\nOwner sets target credit limit in USD\nWeekly automatic top-up restores credit to target\nCredit backed by mUSD tokens on Base mainnet\n10% markup over Amazon prices (covers fees + gas)\nx402 Flow\nPOST /v1/orders returns 402 with PAYMENT-REQUIRED header\nCall POST /v1/wallets/x402/sign with payment blob\nWallet service signs EIP-3009 authorization\nRetry order with PAYMENT-SIGNATURE header\nFacilitator settles on Base mainnet\nOrder proceeds to fulfillment\nRefunds\nScenario\tRefund Target\nProcurement failure\tmUSD balance (auto)\nOrder canceled (within 5 min)\tmUSD balance (auto)\nOwner decreases credit limit\tCard via Stripe\nReturn/lost package\tSupport ticket required (use create_support_ticket)\nAgent States\nState\tMeaning\tCan Order?\nUNCLAIMED\tRegistered, awaiting owner claim\tNo\nCLAIMED\tOwner claimed, fully operational\tYes\nDEGRADED\tPayment methods failed, using remaining balance\tYes (if balance)\nSUSPENDED\tAdmin action, requires manual resolution\tNo\nBest Practices\nBefore Any Purchase\nCall budget_check() to verify available credit\nConfirm shipping profile exists\nCheck item against category denylist\nVerify confidence threshold for proactive purchases\nConversation Guidelines\nAlways confirm purchase with total price before executing\nReport order status and remaining credit after purchase\nIf budget signals detected, acknowledge constraints\nNever pressure user to add more credit\nError Recovery\nOn INSUFFICIENT_CREDIT: suggest adding credit via portal\nOn INVALID_SHIPPING_PROFILE: collect shipping info and call upsert_shipping_profile(), or direct to portal\nOn SUSPENDED: explain owner must resolve via portal\nQuick Reference\nEssential Endpoints\nEndpoint\tPurpose\nPOST /v1/agents/register\tNew agent registration\nGET /v1/agents/me\tCurrent agent status\nGET /v1/balance\tAvailable credit\nGET /v1/catalog/search\tSearch products\nPOST /v1/quotes\tCreate purchase quote\nPOST /v1/orders\tPlace order (x402)\nPOST /v1/wallets/x402/sign\tSign payment\nGET /v1/shipping_profiles\tList shipping profiles\nPOST /v1/shipping_profiles\tCreate/update shipping profile\nPOST /v1/support_tickets\tCreate support ticket\nGET /v1/support_tickets\tList support tickets\nPortal URL\nhttps://portal.moltpho.com\n\n\nOwner actions:\n\n/claim/{token} - Claim agent ownership\n/agents - Manage agents\n/cards - Payment methods\n/orders - Order history\n/settings - Credit limits and preferences"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/unifiedh/moltpho",
    "publisherUrl": "https://clawhub.ai/unifiedh/moltpho",
    "owner": "unifiedh",
    "version": "0.1.5",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/moltpho",
    "downloadUrl": "https://openagent3.xyz/downloads/moltpho",
    "agentUrl": "https://openagent3.xyz/skills/moltpho/agent",
    "manifestUrl": "https://openagent3.xyz/skills/moltpho/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/moltpho/agent.md"
  }
}