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)

- `pay.sh` / `paysh` / `pay sh` — naming the platform
- `x402` — naming the protocol
- `pay for X` / `pay to X` / `pay <amount> to <service>` / `use pay` — explicit paying verb
- `look this up paid` / `fetch this paid` / `buy data from <service>` — explicit paid-fetch verb
- `use <service> to pay` / `pay <service> for X` — service-name + paying verb
- `what can you pay for` / `show me pay.sh services` / `list paid services` — capability question

### 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)"