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.

Public registry entries must commit the OpenAPI document next to PAY.md and reference it with openapi.path (or inline it with openapi.content). openapi.url is not accepted for published providers.

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/skills.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

skills.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/skills.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 --output-dir providers

This generates providers/acme/search/PAY.md from the upstream OpenAPI doc with TODO markers for the discovery-critical fields. Fill in category and use_case, make sure the OpenAPI snapshot is committed next to PAY.md, then validate locally:

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

Before opening a PR, run the changed-provider check against the upstream branch:

pay catalog check . --changed-from origin/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 show google/bigquery jobs