Skills

pay-skills is the registry behind pay skills search. It's a curated repository of provider definitions, each pointing at an x402- or MPP-gated endpoint, with the metadata an agent needs to understand pricing, authentication, and shape.

If you've ever wondered "where does pay skills search 'translate' get its answers?" — it's this repo, built and published to a CDN.

Layout

The source of truth is the providers/ directory:

providers/
  quicknode/rpc/PAY.md                       ← native operator (2 levels)
  paysponge/2captcha/PAY.md                  ← proxied gateway (3 levels)
  merit-systems/stableenrich/enrichment/PAY.md
  solana-foundation/google/translate/PAY.md

The path is the provider's fully-qualified name (FQN): quicknode/rpc, paysponge/2captcha. Two levels for an operator running its own endpoint; three levels for a gateway operator proxying somebody else's API.

Each provider directory contains:

A typical PAY.md frontmatter:

---
name: rpc
title: 'Quicknode'
description: 'Pay-per-request JSON-RPC endpoints for 140+ blockchain networks…'
use_case: 'Use for blockchain JSON-RPC, querying account or contract state…'
category: compute
service_url: https://x402.quicknode.com
openapi:
  path: openapi.json
---

The frontmatter is what the agent reads when deciding whether a provider matches a task. use_case is the most important field for discovery — it's prose-shaped guidance for an LLM.

How pay consumes it

pay-skills is the input repository. The CLI doesn't read it directly; it reads the built index from a CDN.

The lifecycle:

1. A contributor edits providers/<fqn>/PAY.md and opens a PR.
2. GitHub Actions runs pay catalog check on the PR — frontmatter validation, live HTTP probes, Solana-payment verdicts. A bad PAY.md or a dead endpoint blocks the merge.
3. On merge to main, the workflow runs pay catalog build . and publishes dist/skills.json to gs://pay-skills/v1/index.json plus per-provider detail files.
4. pay skills update (called explicitly or automatically) fetches the index from the CDN. pay skills search queries it.
5. When the user selects a provider, the agent fetches the per-provider detail file (gs://pay-skills/v1/<fqn>.json) — that holds the OpenAPI document.

Within a few minutes of merge, the new provider is discoverable from any pay skills search worldwide.

Two artifacts to know about

index.json

The built catalog index — generated, not hand-edited. Contains metadata for every provider: FQN, title, description, category, declared currencies, endpoint count, and the URL to the per-provider detail JSON. Published at gs://pay-skills/v1/index.json. Don't commit changes here; commit changes to providers/ and let CI rebuild.

x402-solana-catalog.md

A human-readable inventory of every x402-on-Solana endpoint accepting USDC. Organized by category (analytics, social, enrichment, e-mail, voice, etc.). It's manually curated and serves as a reference document — useful for browsing, not used as a build input.

Add a provider

pay catalog scaffold acme/search https://api.acme.example/openapi.json

This generates ./acme/search/PAY.md from the upstream OpenAPI doc with TODO markers for the discovery-critical fields. Fill in category and use_case, then validate locally:

pay catalog check providers/acme/search/PAY.md

PR CI runs the same command across the whole registry on --changed-from main. A merged PR auto-publishes. See Commands → catalog for the full reference.

Add a provider source

A team running its own catalog (not the official one) can publish their own skills.json and register it locally:

pay install your-org/your-repo
pay skills update
pay skills search "your search"

pay install is shorthand for pay skills add — see Commands → other. Multiple sources stack; pay skills search queries all of them.

Browse the catalog

The canonical browser view is built into the pay.sh site at /services (the same data, surfaced on the web). For CLI-side discovery:

pay skills search "translate"
pay skills search "data" --category data
pay skills endpoints google/bigquery jobs