sepivip/seekerclaw/paysh-catalog

pay.sh Service Catalog

A curated directory of HTTPS endpoints the agent can pay for using agent_pay and the burner wallet, only when the user explicitly opts in via a pay-intent keyword.

Default: this skill is DORMANT

For the vast majority of user messages, this skill should not activate. The agent's default behavior for any question is:

1. Try training data (facts, definitions, well-established knowledge)
2. Try web_search / web_fetch (live web data, free)
3. If neither answers and the user did NOT explicitly invoke pay/x402, give a best-effort honest answer noting the limitation — do NOT autonomously reach for a paid catalog service

This skill activates ONLY when the user's message contains one of the explicit pay-intent keywords listed below. If you're unsure whether a message is opting in, prefer the free path — paid lookups cost USDC and the user did not authorize a charge implicitly.

Opt-in keywords (skill activates)

The authoritative activation contract is the triggers: list in this file's frontmatter (BAT-1035). The skill activates only when the user's message contains one of those exact phrases:

• pay.sh / paysh — naming the platform
• x402 — naming the protocol
• pay with burner — explicit burner-pay intent
• pay for — explicit paying verb
• what can you pay for / show me pay.sh services / list paid services — capability question

Intentionally NOT triggers: pay to <person> (that is a normal SOL/SPL transfer — use solana_send, not a paid API) and pay with main (agent_pay settles from the burner only, never the main wallet). If a message is ambiguous, prefer the free path — paid lookups cost USDC and the user did not authorize a charge implicitly.

NOT opt-in (skill stays dormant)

• Topical / factual questions: "what's the mass of the sun", "who founded Solana", "what time is it in Tokyo" → training data or web_search
• Live-data questions WITHOUT a paying verb: "find me a hotel in Rome", "current price of SOL", "best deal on a PS5" → web_search
• General Solana / Jupiter operations: "check my balance", "send 0.1 SOL to Alice", "swap SOL for USDC" → use the relevant tool directly (solana_balance, solana_send, solana_swap); these are NOT x402 and don't involve this skill

What this skill does (once activated)

Once an opt-in keyword fires the skill, the agent's job is:

1. Match intent → entry by reading catalog.json (the index in this folder). v2 schema: top-level object with entries[] array; each entry has id, service_id, name, endpoint.{method, path, cost_usdc}, intents[], summary, doc_file, verification.*. Pick the entry whose intents[] best matches user request.
2. Build the URL by combining entry.upstream_ref.service_url + entry.endpoint.path. Add URL-encoded query params for GET endpoints (see encoding rules below).
3. Read the matching `entry.doc_file` (e.g. services/wolfram-alpha.md) for body schema (POST endpoints), example calls, and any safety scoping. If the entry has a doc_anchor, jump to that section within the doc.
4. Call `agent_pay` with object-shaped args: { url: "<constructed-url>", max_usdc: "<decimal-string-ceiling>", method?: "GET"|"POST", body?: <JSON object or array, required for POST> }. max_usdc MUST be a decimal STRING (not number) — e.g. "0.05". body MUST be a JSON object or array (or a JSON string that parses to one); primitives like numbers/strings/booleans are rejected with body_not_json. GET calls run silently when under cap. POST calls always prompt the user for confirmation regardless of caps (POST can send SMS, post content, or trigger paid actions — the confirmation is by design). Use entry.endpoint.method to pick GET vs POST.
5. Return the response to the user

Examples

Activates → paid call

User: "Use pay.sh to look up the current GDP of Japan in USD."

Why it activates: contains pay.sh + naming a paid lookup.

1. Read catalog.json → 'wolfram-alpha' matches the math/facts intent.
2. Read services/wolfram-alpha.md → URL pattern is
   https://wolframalpha.x402.paysponge.com/v1/result?i=<URL-encoded query>
3. URL-encode the query with `encodeURIComponent`. It encodes spaces
   as `%20` and percent-encodes most special characters (`&` → `%26`,
   `=` → `%3D`, `+` → `%2B`, `#` → `%23`, `/` → `%2F`, etc.).
   **NOT encoded** by `encodeURIComponent` (per the JS spec — kept
   unchanged): A-Z a-z 0-9 `- _ . ~ ! * ' ( )`. These chars are valid
   in HTTP query strings as-is, so leaving them unencoded is fine for
   pay.sh's services. If a specific service requires stricter
   RFC3986-style encoding (rare), the service's `services/<id>.md`
   will say so.
   Example for this query:
     encodeURIComponent("current GDP of Japan in USD")
     → "current%20GDP%20of%20Japan%20in%20USD"
   Final URL:
     https://wolframalpha.x402.paysponge.com/v1/result?i=current%20GDP%20of%20Japan%20in%20USD
   Do NOT mix `+` for spaces with `encodeURIComponent` — `+` is form-
   encoded space, and applying encodeURIComponent over a string that
   already contains `+` would turn `+` into `%2B` (literal plus).
4. Invoke agent_pay with JSON args:
   agent_pay({ url: "<constructed-url-above>", max_usdc: "0.05" })
   max_usdc MUST be a decimal STRING (not number). Burner signs
   silently for this GET call since $0.01 << $0.05 ceiling.
5. Return Wolfram's answer with a brief framing.

Activates → catalog browsing (no paid call yet)

User: "What can you pay for?"

Why it activates: matches the capability-ask phrase "what can you pay for". (NOT every message containing the word "pay" — only the specific capability-ask phrases listed in the opt-in section above.) Agent reads catalog.json, lists the 44 supported entries (across 10 services — many services have multiple endpoints now: stablecrypto-market-data has 21, perplexity has 2, others 1-5 each) with costs, mentions the 63 known-but-not-usable ones. No agent_pay call. For "what can you pay for" the agent should GROUP by service in the reply (e.g. "Wolfram Alpha — 2 endpoints (math facts, structured pods); Tripadvisor — 5 endpoints (search, details, reviews, photos); StableCrypto — 21 endpoints (CoinGecko price/chart/markets, DefiLlama TVL/yields)") rather than dumping 44 individual lines.

Does NOT activate → vanilla answer

User: "What's the mass of the sun?"

Why it stays dormant: no opt-in keyword. The agent answers from training data: "The Sun's mass is about 1.989 × 10³⁰ kg." — no USDC charge.

User: "Find me a hotel in Rome."

Why it stays dormant: "find" + "hotel" without any paying verb or service name. Use web_search. If the user then says "pay Tripadvisor to find one" the skill activates and we hit the catalog.

User: "Check my Solana balance."

Why it stays dormant: not an x402 query at all. Use solana_balance directly. The paysh-catalog skill is unrelated to Solana balance / send / swap operations.

Reading the catalog efficiently

catalog.json is small-ish (currently 44 entries across 10 services, ~30KB in v2 schema — services are now genuinely multi-endpoint: stablecrypto-market-data has 21 endpoints, tripadvisor has 5, rentcast has 5, crushrewards has 4, wolframalpha/reducto/perplexity have 2, others 1). Always load it first to pick the entry by intent match. Then read only the matching entry.doc_file (potentially scrolling to entry.doc_anchor within it) — never load every services/*.md at once. That's the whole point of the per-entry / per-service-doc layout.

v2 schema (see SCHEMA.md in this folder for the full spec):

• One entry per ENDPOINT (not per service) — a service exposing N catalogued endpoints has N entries, all sharing the same service_id
• entry.doc_file may carry an optional doc_anchor pointing at the endpoint-specific section within the shared service doc
• entry.verification.last_captured_at tells you how fresh the 402 capture is; if very old, the service may have drifted upstream (run node tests/paysh/probe-catalog.js --refresh <id> from the dev workstation to re-verify)

The unsupported.json companion registry

unsupported.json lists 63 additional entries that exist on pay.sh today but the agent cannot end-to-end use yet — either because agent_pay can't pay them (protocol/auth gap), it can pay but can't deliver the response (binary content with no channel attachment path), the endpoint didn't return a 402 at probe time (broken / moved / re-routed), or the paid-response shape is contested and unverified.

v2 schema: top-level object with entries[] (same shape as catalog entries + reason field) AND a top-level reasons object — a registry of { <bucket>: { label, explanation, actionable } } you compose your "why can't you use X?" answers from. Several entries also carry audit_pending[] — sibling endpoints found by the BAT-706 audit that aren't catalogued yet (with deferred_to: BAT-XXX pointer).

Read unsupported.json when:

• The user asks "do you know about service X?" or "is X on pay.sh?"
• The user asks for a capability (translation, image OCR, video analysis, screenshots, Google Vision, image generation, etc.) that the supported 10 don't cover
• You want to give an honest "I know it exists but can't deliver it because of Y" answer instead of a generic "I don't have a service for that"

Six reason buckets:

Some endpoint_not_402_at_probe and invalid_demand entries also carry BAT-706 audit notes about sibling endpoints on the same host that ARE payable but aren't catalogued yet (e.g. paysponge/nyne person-search endpoints — deferred to BAT-772 Tier 2c). Each pending endpoint's deferred_to field is either a BAT-XXX follow-up ticket id, or null when the endpoint is unscheduled (no ticket yet — known to exist, but no decision on when/how to catalog). Read each entry's note field — it tells you whether the audit found more and what their status is. (Note: paysponge/perplexity also had audit-discovered siblings; BAT-769 promoted /search and /v1/agent to the catalog, leaving only /v1/async/sonar in audit_pending as unscheduled.)

NEVER call `agent_pay` on a service in `unsupported.json`. Reasons and what to tell the user: