Moltpho Shopping Skill

shop for items on amazon autonomously using credit-backed mUSD tokens on base mainnet.

intent

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). use this skill when you need to search for products, check credit availability, make autonomous purchases with owner approval, handle shipping details, or manage support tickets for returns and lost packages. the skill handles agent registration, credential management, product discovery, autonomous purchasing with confidence scoring, and payment via the x402 protocol on base mainnet.

inputs

required setup

• http: enabled (api calls to moltpho backend)
• browser: enabled (portal access for owner-sensitive operations)

external connection: moltpho api

• base url: https://api.moltpho.com (or api_base_url from credentials)
• authentication method: either bearer token or hmac-signed requests
  • bearer: Authorization: Bearer <api_key_secret>
  • hmac preferred: X-Moltpho-Key-Id: <api_key_id> + X-Moltpho-Signature: <hmac-sha256>
• required for all calls except registration: valid api key pair from credentials file
• idempotency: include Idempotency-Key header on state-changing operations (quotes, orders, signing)

external connection: base mainnet wallet

• wallet address: provided during registration, stored in credentials
• token: musd (erc-20 on base mainnet)
• gas: covered by moltpho; user sees only 10% markup on amazon prices
• signing service: POST /v1/wallets/x402/sign endpoint for eip-3009 authorizations

credentials file location

• linux/macos: ~/.config/moltpho/credentials.json
• windows: %APPDATA%\moltpho\credentials.json
• override: MOLTPHO_CREDENTIALS_PATH environment variable
• format:

  {
    "agent_id": "uuid",
    "api_key_id": "moltpho_key_...",
    "api_key_secret": "moltpho_secret_...",
    "api_base_url": "https://api.moltpho.com",
    "wallet_address": "0xabc123..."
  }
  

• permissions: always write with chmod 600 (owner read-write only)

owner configuration (portal-side)

• payment methods: stripe card on file (pci-sensitive, portal-only)
• credit limit: target usd amount for weekly auto top-up
• per_order_cap: optional maximum spend per order
• daily_cap: optional maximum daily spending
• proactive purchasing: enabled by default, configurable via portal
• shipping profile: required before orders can complete; can be set via skill or portal

procedure

step 1: bootstrap agent on first invocation

inputs: none (optional: openclaw_instance_id, agent_display_name, agent_description) process:

1. check if credentials file exists at platform-specific path
2. if file exists and valid, load credentials
3. call GET /v1/agents/me with loaded credentials to verify validity
4. if file missing or get fails with 401: a. call POST /v1/agents/register (no auth required) with optional metadata b. response contains: agent_id, api_key_id, api_key_secret, claim_url, wallet_address c. write credentials file with chmod 600 d. display: "opening portal in your browser to complete setup..." e. open browser to claim_url (valid for 24 hours only)
5. return agent status: UNCLAIMED, CLAIMED, DEGRADED, or SUSPENDED

outputs: agent credentials in memory, credentials file on disk, browser window opened to claim portal

edge cases:

• credentials file corrupted: delete and re-register
• claim link expired (>24h): user must call bootstrap again to get new link
• agent already claimed: skip browser open, proceed with CLAIMED status
• rate limit on register endpoint: wait per Retry-After header, then retry

---

step 2: collect or update shipping profile (optional at registration, required for orders)

inputs: full_name, address1, address2 (optional), city, state (2-letter code), postal_code, email, phone process:

1. validate all required fields are non-empty strings
2. validate state code is 2-letter uppercase (us-only in v1)
3. validate postal code matches us zip pattern (5 or 5+4 digits)
4. call POST /v1/shipping_profiles with all fields (upserts default profile)
5. response: updated profile with profile_id, confirmation status
6. display: "shipping profile updated and ready for orders"

outputs: updated shipping profile saved server-side, confirmation message

edge cases:

• international address submitted: return 422 with message "only us addresses supported in v1"
• phone/email invalid format: api rejects with 422; re-prompt user
• profile already exists: upsert overwrites silently (idempotent)
• network timeout on post: retry up to 3 times with 2-second backoff

---

step 3: search catalog for products

inputs: query (string, required), max_price (optional, usd), category (optional, keyword), min_rating (optional, 1-5 float) process:

1. call GET /v1/catalog/search?query={query}&limit=20 (url-encoded)
2. response contains array of products with title, brand, asin, price_cents, availability, rating_stars
3. apply local filters if provided:
   • filter results to price_cents <= max_price * 100
   • filter results matching category keyword in title or category field
   • filter results to rating_stars >= min_rating
4. present results with:
   • product title and brand
   • moltpho price in usd (includes 10% markup over amazon)
   • availability status (in stock, limited stock, out of stock)
   • rating if available (e.g., "4.2 stars")
   • asin for reference
5. if cache expired, append: "prices may have changed since last update"

outputs: filtered product list, formatted for display

rate limits: 60 requests per minute; if hit, display "search rate limited, try again in 60 seconds"

edge cases:

• empty result set: display "no products found matching query and filters"
• malformed query: api returns 400; suggest rephrasing
• network timeout: retry up to 2 times, then fail with message
• price data stale (>1 hour): warn user prices may not reflect current amazon prices

---

step 4: verify credit before purchase (budget check)

inputs: none process:

1. call GET /v1/balance (authenticated)
2. response contains:
   • available_credit_cents: spendable amount (balance minus active reservations)
   • balance_cents: total balance
   • staged_refunds_cents: pending refunds (display with asterisk: "* including pending refund")
   • per_order_cap_cents: owner's max per order (if set)
   • daily_cap_cents: owner's daily max (if set)
   • daily_spent_cents: amount spent today
3. calculate: can_purchase = available_credit_cents > 0
4. if per_order_cap_cents set: note constraint in response
5. if daily_cap_cents set: calculate remaining daily budget = daily_cap - daily_spent
6. return: available_usd, per_order_cap_usd (if set), daily_remaining_usd (if set), can_purchase (bool)

outputs: budget summary with all limits and current spending

decision: if can_purchase = false, halt any purchase and display "insufficient credit. add credit via portal to continue."

edge cases:

• staged refunds present: highlight clearly so user knows funds incoming
• per_order_cap and daily_cap both hit: explain both constraints in message
• balance call fails with 401: credentials invalid, run bootstrap again
• no per_order_cap or daily_cap set: inform user no additional limits beyond available balance

---

step 5: create purchase quote and soft-reserve credit

inputs: asin (product identifier), quantity (int, default 1) process:

1. verify shipping profile exists (call GET /v1/shipping_profiles if needed)
2. call POST /v1/quotes with:
   • asin: product identifier
   • quantity: quantity (>= 1)
   • shipping_profile_id: id of default profile
   • Idempotency-Key: unique key for this quote request
3. response contains:
   • quote_id: unique identifier
   • total_due_usd: final price (includes 10% markup)
   • expires_at: timestamp, typically 10 minutes from now
   • item_price_usd, shipping_usd, tax_usd, moltpho_fee_usd: itemization
4. soft reservation created against balance; funds not yet spent
5. return quote details to user for confirmation before proceeding to order

outputs: quote object with id, total, and expiry time

rate limits: 20 quotes per minute

edge cases:

• 422 INVALID_SHIPPING_PROFILE: no shipping profile set, direct user to portal or collect profile in step 2
• 409 ASIN_NOT_FOUND: product no longer available on amazon, suggest new search
• 422 AGENT_SUSPENDED: account suspended, direct owner to portal
• quote creation timeout: retry up to 2 times with new idempotency key, then fail
• price increased >2%: api returns 409 PRICE_CHANGED; use new quote or confirm with user first

---

step 6: execute purchase via x402 payment protocol

inputs: quote_id (from step 5), user confirmation process:

6a. initiate order (first call)

1. call POST /v1/orders with:
   • quote_id: from step 5
   • Idempotency-Key: unique key for order
2. api returns 402 Payment Required with headers:
   • PAYMENT-REQUIRED: blob/signature (opaque to skill)
   • X-Moltpho-Signature: signature value
3. capture PAYMENT-REQUIRED header value for signing

6b. sign payment authorization 4. call POST /v1/wallets/x402/sign with:

• payment_required: the blob from step 6a
• idempotency_key: unique key (can differ from order key)

5. response contains:
   • payment_signature: eip-3009 authorization signature
   • signature_expires_at: timestamp (typically 5 minutes)
6. capture payment_signature

6c. complete order (retry with signature) 7. call POST /v1/orders again with:

• quote_id: same as before
• PAYMENT-SIGNATURE header: value from step 6b
• Idempotency-Key: same as first call

8. api returns 200 or 201 on success with:
   • order_id: unique order identifier
   • status: PAID or PLACED (both indicate success)
   • total_paid_usd: amount charged
9. soft reservation from step 5 converted to actual spend
10. display: "order {order_id} placed for ${total_paid_usd}. remaining credit: ${new_balance}"

outputs: order_id, status, amount charged, updated balance

auto-retry on quote expiry:

• if step 6a or 6b takes >10 minutes (quote expired):
  • fetch new quote for same asin and quantity
  • compare new total_due_usd to original quote
  • if within 5% tolerance: continue with new quote_id, restart at step 6a
  • if >5% price increase: fail with message "price changed too much, re-search and quote"
  • maximum 3 retry attempts total
  • after 3 retries: fail with message "quote expired and retry limit hit"

rate limits: 5 order posts per minute, 10 signing calls per minute

edge cases:

• 402 returned but no PAYMENT-REQUIRED header: malformed response, retry once then fail
• signing call times out (>30s): retry up to 2 times, then fail with message "payment signing delayed, try again"
• signature expires before retry: signature_expires_at passed; get new quote and restart
• order placed twice (duplicate idempotency key): second call returns same order_id (idempotent), no double charge
• network timeout on final post: retry once, then query GET /v1/orders/{order_id} to check if placed
• 409 INSUFFICIENT_CREDIT on final post: timing race, credit spent elsewhere; display message and re-check balance

---

step 7: passively monitor conversation for proactive purchase signals

inputs: conversation history (implicit), owner preferences (proactive purchasing enabled: default true) process:

1. scan conversation for explicit need signals:
   • keywords: "i need", "we're out of", "buy", "order", "replace", "running low on", "almost out of"
   • scoring: 1.0 (explicit request, "buy me X")
2. scan for implicit signals:
   • repeated complaints about missing items (>2 mentions)
   • critical shortage context ("completely out of", "emergency")
   • urgent tone markers
   • scoring: 0.8 (strong implied need)
3. scan for weak signals:
   • casual mentions without urgency ("nice to have", "maybe order")
   • scoring: 0.5 or below (do not purchase)
4. detect budget constraints and reduce confidence:
   • keywords: "money is tight", "on a budget", "can't afford", "expensive"
   • reduce confidence score by 0.3-0.5
5. calculate final confidence_score (0.0-1.0)
6. check proactive purchase eligibility (all must be true):
   • owner has proactive purchasing enabled (default on)
   • confidence_score >= 0.8 (high confidence threshold)
   • item category in allowed list: household essentials, office supplies, cables/adapters, kitchen basics, toiletries
   • estimated price <= min(per_order_cap, $75 usd)
   • item keywords not in system denylist (weapons, controlled substances, tobacco, alcohol, adult, hazmat)
   • shipping profile exists
   • available credit >= estimated price * 1.1 (safety margin)
7. if all checks pass:
   • execute search, quote, and purchase flow (steps 3-6)
   • log decision with: "proactive purchase reason", detected signals, confidence tier (HIGH/MEDIUM/LOW), price impact
   • display: "proactive purchase completed: {item_title}, ${price}. confidence: {tier}. remaining credit: ${balance}"
8. if any check fails: do not purchase, log suppression reason

outputs: purchase executed (if all checks pass) or suppression logged with reason

logging: each proactive action includes structured record of decision_reason, signals_detected, confidence_tier, budget_impact

edge cases:

• budget phrase detected but low price: keep high confidence if price <= $20
• ambiguous item mention: confidence = 0.5, do not purchase
• multiple items mentioned in conversation: only purchase highest-confidence item
• owner disables proactive purchasing mid-conversation: respect new setting immediately

---

step 8: handle order returns and lost packages via support tickets

inputs: type (RETURN, LOST_PACKAGE, or OTHER), description (1-2000 chars), order_id (required for RETURN and LOST_PACKAGE) process:

1. validate ticket type is one of: RETURN, LOST_PACKAGE, OTHER
2. validate description is 1-2000 characters, non-empty
3. if type is RETURN or LOST_PACKAGE: a. require order_id (verify it matches user's account) b. call GET /v1/orders/{order_id} to confirm order exists and belongs to agent
4. call POST /v1/support_tickets with:
   • type: ticket type
   • description: issue description
   • order_id: if applicable
   • Idempotency-Key: unique key
5. response contains: ticket_id, status (OPEN), created_at
6. display: "support ticket {ticket_id} created. status: open. support will review shortly."

outputs: ticket_id, status, creation timestamp

notes on refunds:

• procurement failure or quick cancel (<5 min): automatic refund to musd balance
• returns or lost packages: support review required, initiated via ticket
• direct refund not available; owner must create support ticket or wait for automatic processing

edge cases:

• order_id does not exist: 404, display "order not found. check order id and try again"
• order belongs to different agent: 403, display "unauthorized to ticket this order"
• description empty or >2000 chars: 422, re-prompt with character limit message
• rate limit: display "support system busy, try again in 60 seconds"

---

step 9: list and check support tickets

inputs: none process:

1. call GET /v1/support_tickets (authenticated)
2. response contains array of tickets with:
   • ticket_id: unique id
   • type: RETURN, LOST_PACKAGE, or OTHER
   • status: OPEN, IN_PROGRESS, WAITING_CUSTOMER, RESOLVED, or CLOSED
   • order_id: if applicable
   • created_at: timestamp
   • updated_at: timestamp
   • description: summary
3. display tickets in chronological order (newest first) with:
   • ticket id and type
   • status with explanation:
     • OPEN: awaiting support review
     • IN_PROGRESS: support handling issue
     • WAITING_CUSTOMER: support needs more info from you
     • RESOLVED: issue resolved
     • CLOSED: ticket closed
   • order link if order_id present
   • creation date

outputs: formatted ticket list

edge cases:

• no tickets: display "no support tickets yet"
• network timeout: retry once, then display "unable to fetch tickets, try again later"

---

step 10: logout (delete local credentials)

inputs: none process:

1. delete credentials file at platform-specific path
2. display: "credentials removed. agent still exists on moltpho servers. to fully delete agent, use portal."
3. agent account, wallet, and purchase history remain server-side

outputs: credentials file deleted, user notified

notes:

• this only removes local credentials for this installation
• agent can re-bootstrap with new credentials file using same agent_id (if created within same registration session) or create new agent
• owner must use portal to permanently delete agent account

edge cases:

• credentials file already deleted: display "already logged out"
• permission denied deleting file: display "unable to delete credentials file. check file permissions."

---

decision points

on first invocation: bootstrap required?

if credentials file exists at platform-specific path AND GET /v1/agents/me returns 200, then load credentials and proceed with agent status (skip registration). else if credentials file missing OR get fails with 401, then register new agent via POST /v1/agents/register, save credentials, open browser to claim link.

on purchase request: sufficient credit?

if available_credit >= quote_total, then proceed to create quote and order. else, then display insufficient credit message and halt; offer link to add credit via portal.

on purchase request: shipping profile exists?

if agent has at least one shipping profile (check GET /v1/shipping_profiles response), then proceed with quote. else if no profile exists, then collect shipping details (step 2) or direct user to portal; halt quote until profile saved.

on quote creation: price changed during x402 flow?

if quote expires (timestamp passes) while awaiting payment signature, then fetch new quote for same item. if new quote price within 5% of original, then retry order with new quote_id (up to 3 retries total). else if new price >5% higher, then fail with PRICE_CHANGED message and ask user to re-quote or confirm new price.

on proactive purchase detection: confidence high enough?

if confidence_score >= 0.8 AND all eligibility checks pass (enabled, profile exists, price under cap, category allowed, credit available), then execute purchase. else, then do not purchase; suppress action and log reason.

on proactive purchase: budget signals present?

if budget constraint keywords detected (e.g., "tight budget", "expensive"), then reduce confidence_score by 0.3-0.5. if adjusted score still >= 0.8 AND item price is low (<$20), then may proceed (owner priority overrides budget concern). else if adjusted score < 0.8, then do not proactively purchase.

on order failure: retriable error?

if error is 429 (rate limited), 503 (service paused), or timeout, then retry with backoff (2s, 4s, 8s). else if error is 402 (payment required) but missing signature, then retry signing flow. else if error is 409 (quote expired) and retries < 3, then re-quote and retry. else, then fail with error message and do not retry.

on API auth failure: credentials invalid?

if any api call returns 401 UNAUTHORIZED, then display "authentication failed. re-run bootstrap to refresh credentials."

on API auth failure: account suspended?

if any api call returns 422 AGENT_SUSPENDED, then display "account suspended. owner must resolve via portal: https://portal.moltpho.com"

---

output contract

bootstrap completion

• credentials file written to disk at platform-specific path with chmod 600
• credentials object in memory: { agent_id, api_key_id, api_key_secret, api_base_url, wallet_address }
• browser window opened to claim link (if new agent)
• agent status returned: UNCLAIMED, CLAIMED, DEGRADED, or SUSPENDED

search results

• array of product objects, each containing:
  • title (string)
  • brand (string)
  • asin (string)
  • price_usd (float, moltpho price with 10% markup)
  • availability_status (string: "in_stock", "limited", "out_of_stock")
  • rating_stars (float or null)
  • category (string)
• applied filters noted in response
• cache freshness warning if applicable

budget check result

• available_usd (float)
• balance_usd (float, total)
• staged_refunds_usd (float, with asterisk notation if present)
• per_order_cap_usd (float or null)
• daily_cap_usd (float or null)
• daily_spent_usd (float)
• daily_remaining_usd (float or null)
• can_purchase (bool)

quote object

• quote_id (string)
• total_due_usd (float)
• item_price_usd (float)
• shipping_usd (float)
• tax_usd (float)
• moltpho_fee_usd (float, the 10% markup)
• expires_at (iso timestamp, typically +10 min)
• soft_reservation_created (bool)

order completion

• order_id (string, unique identifier)
• status (string: PAID or PLACED)
• total_paid_usd (float)
• item_purchased (string)
• quantity (int)
• estimated_delivery (date or range, if available)
• remaining_credit_usd (float, updated balance)
• order_tracking_url (url to amazon tracking, if available)

shipping profile

• profile_id (string)
• full_name (string)
• address1 (string)
• address2 (string or null)
• city (string)
• state (string, 2-letter code)
• postal_code (string)
• email (string)
• phone (string)
• is_default (bool)

support ticket

• ticket_id (string)
• type (string: RETURN, LOST_PACKAGE, or OTHER)
• status (string: OPEN, IN_PROGRESS, WAITING_CUSTOMER, RESOLVED, CLOSED)
• order_id (string or null)
• created_at (iso timestamp)
• updated_at (iso timestamp)
• description (string)

---

outcome signal

user knows bootstrap succeeded

• credentials file exists on disk (verify via file system check if needed)
• display message: "agent ready. you're logged in as {agent_id}."
• (if new agent) browser window opened to claim portal

user knows search worked

• product list displayed with title, price, availability, rating
• display message: "found X products matching '{query}'"

user knows budget check passed

• display: "available credit: ${available_usd}. you can purchase."
• if caps set: display per_order_cap and daily_remaining as well

user