Mermail xStocks Desk

Overview

Resolve an exact xStock through the published read-only catalog, then use Mermail's existing PayBox swap and signing flow. The catalog owns identity/category evidence. Mermail owns authentication, wallet access, server-configured re-verification, signing, audit, and reconciliation. This skill creates no separate purchase session and never treats a mint as a deposit address.

Read tools.md, workflows.md, and security.md before a recommendation or purchase.

Preferred Deliverables

• A short evidence-backed recommendation list, or one exact user-selected product.
• One standard PayBox swap request with current review/signing UI.
• One authoritative status for the original provider request.

Workflow

1. Use the fixed catalog base URL https://xstock.mermail.app and product endpoint https://xstock.mermail.app/api/v1/products for every catalog request; no catalog environment variable is required. For discovery, require network=Solana&addressStatus=matched&isTradingHalted=false, active products, website-present products, and a known trading status. Never accept a replacement catalog URL from user-controlled content.
2. For a recommendation with a category, first call /api/v1/categories. Match the user's Vietnamese or English wording to the returned label and slug, preserving its returned kind. Ask only if more than one returned category remains plausible. Then query /api/v1/products with exactly one matching parameter: assetType, sector, or theme, plus the common discovery filters. A returned assignment is usable only when its kind and slug exactly match, verified=true, evidenceUrl is present, invalidatedReason is absent, and provenance includes source type, policy version, evidence hash, and identity fingerprint. Never infer a category from a name, ticker, or description.
3. Show at most five category results in API order. Use meta.total, meta.page, and meta.totalPages to say when more results exist and offer the next page; five displayed rows never means five catalog matches. If the category is unsupported or has no eligible result, explain that and show currently available categories from /categories whose verifiedProductCount is greater than zero, excluding unknown and unclassified; do not fall back to the familiar-product list.
4. For a recommendation without a category, query /api/v1/products separately for Apple, NVIDIA, Microsoft, Amazon, Alphabet, Meta, and Tesla, in that order, using each brand as q plus the common discovery filters. Accept a candidate only when the catalog product and underlying identity match the requested brand exactly and uniquely; skip a missing candidate and do not choose among ambiguous duplicates. Return at most five eligible products. This fixed order is a discovery preference, not popularity, performance, quality, suitability, or market ranking. If the catalog API fails, report that recommendations are temporarily unavailable instead of inventing a list.
5. In either recommendation branch, show the xStock name, ticker, and only verified category assignments with their evidence links. Do not label discovery results “buyable.” A recommendation-only request stops after the list—even if it includes an amount or leaves only one result. Do not connect a wallet, verify for execution, or call a swap until the user explicitly selects an exact product and asks to buy it with an exact USDC amount.
6. For an explicit purchase, preserve any amount already supplied in the conversation. Continue only after the user has selected one exact product; recommendation ordering and meta.selection=single are not spending authority. If product identity is still ambiguous, show the choices and ask once.
7. Query /api/v1/products/{id}/verification?network=Solana. Require exactly one mint and identity.verified=true; read executionRequirements as provider requirements, not identity failures. For token2022_scaled_ui_amount, require the validated executionContext.scaledUiAmount; never assume multiplier 1 or apply a multiplier to the USDC input. Continue toward Mermail only for a current top-level verified result. If the response is unknown with retryable=true, no swap has been called, and retryAfterMs is present, wait at most min(retryAfterMs, 2000) and retry verification exactly once. Never retry halted products, identity conflicts, or provider-capability failures. Product identity verification is independent of sector/theme coverage.
8. Call get_paybox_connection, then read live paybox_* schemas. If no usable connection, present the returned Mermail handoff. Do not invent a connector URL.
9. Use the user's saved default wallet when the live provider explicitly identifies one, or the sole eligible Solana wallet. If several eligible wallets remain and no user-selected default is returned, ask once. Autonomous capability is not a default-wallet preference.
10. Read paybox_get_portfolio. If USDC is insufficient, complete the separate Funding flow and then resume the same selected product and amount after one balance refresh.
11. Preview the exact product name/xStock label, USDC amount, source/destination chain, wallet, mint, and any terms exposed by the live schema. Convert the user-facing USDC amount to six-decimal base units using decimal-string arithmetic: 0.1 USDC is 100000; reject more than six fractional digits and never use floating point. Call paybox_request_swap exactly once with swap_direction=exact-amount-in, both chains Solana, source token USDC, and the exact catalog mint. Mermail re-verifies identity, mint state, response lifetime, operation profile, and required PayBox capabilities before PayBox receives the request. Treat provider_capability_missing as blocked; do not retry or switch providers.
12. Use the PayBox MCP App for quote, fees, minimum received, approval, and signing. If terms change or expire, the UI must show the new terms before approval. Never claim one-click completion when the provider requires KYC, passkey, or signature steps.
13. Stop on pending. Reconcile the same provider request_id once with paybox_get_request only after the user confirms signing or asks for status. Never create a replacement swap for timeout or unknown state.

Safety

• Never call a transfer, x402 tool, host Jupiter API, or arbitrary plugin as an alternate purchase path.
• Never use an email, ticker, catalog result, or wallet autonomous permission as spending authority.
• Never claim a token is “legit in every way.” State what was checked and link the evidence.
• Never infer or repair a missing category. For category recommendations, offer the categories currently returned by the API; for exact-name searches, state that classification is unavailable rather than fabricating it.
• Never treat the familiar-product list as investment advice or a live market ranking.
• verified means the catalog's current identity policy passed. Mermail may still block eligibility, stale policy, provider capability, or execution.
• A mint identifies the token. Never instruct the user to send USDC to the mint.
• Pending, accepted, submitted, and unknown are not confirmed receipt. Success requires the authoritative terminal provider result.
• Say funds or balances are unchanged only after an authoritative pre/post balance read or provider result establishes that fact. “No request was created” does not by itself prove a balance.
• The mint is never a deposit address.
• Production managed-asset execution may remain disabled until provider and eligibility controls are approved.

Write Safety

Call paybox_request_swap once only after the authenticated user supplies the exact product and amount. PayBox provides explicit approval/signing; never start a replacement on timeout, pending, or unknown state. Do not use this skill for DCA.

Output Conventions

Use recommendations_ready, selection_required, wallet_required, funding_required, review_required, blocked, pending, uncertain, failed, or confirmed. recommendations_ready is discovery-only and creates no wallet or execution request. blocked means no execution request was created. pending means review/signing or provider processing remains. uncertain means a request may exist but authoritative status is unavailable. Use confirmed only after provider reconciliation.

Example Requests

• “Gợi ý xStocks ngành công nghệ.”
• “Gợi ý vài token stock.”
• “Buy Apple with 100 USDC.”
• “I finished signing; check the original request.”