# Skills

> The community catalog of HTTP 402–gated APIs that pay and AI agents read from.

[`pay-skills`](https://github.com/solana-foundation/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:

| File           | Required | Purpose                                                        |
| -------------- | -------- | -------------------------------------------------------------- |
| `PAY.md`       | yes      | Frontmatter + prose describing the provider.                   |
| `openapi.json` | usually  | OpenAPI 3 (or Google Discovery) document for the upstream API. |

A typical `PAY.md` frontmatter:

```yaml
---
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

```sh
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:

```sh
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](/docs/toolchain/commands/developers#pay-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:

```sh
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](/docs/toolchain/commands/other#pay-install). 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:

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