Publish to pay-skills

Publish a provider entry after your gateway returns valid 402 challenges and the API is ready for agent discovery.

Agent summary

Registry entries live at providers/<operator>/<name>/PAY.md or providers/<operator>/<origin>/<name>/PAY.md.
Runtime YAML is for pay gate api; public catalog entries are PAY.md plus sidecar files.
Commit OpenAPI snapshots next to PAY.md and reference them with openapi.path. Do not publish openapi.url entries.
Run pay catalog check providers/<fqn>/PAY.md before opening a PR.
Paid endpoints must return MPP or x402 402 challenges on Solana mainnet and accept USDC or USDT.

Quick start

# 1. Fork and clone the registry.
git clone git@github.com:<you>/pay-skills.git
cd pay-skills

# 2. Scaffold a provider entry under providers/.
pay catalog scaffold <operator>/<name> https://api.example.com/openapi.json --output-dir providers

# 3. Edit providers/<operator>/<name>/PAY.md.
# Replace TODO values for category and use_case, then refine the prose.

# 4. Validate the provider. This is the check to run most often.
pay catalog check providers/<operator>/<name>/PAY.md

# 5. Optional: walk the whole registry without live probes.
pay catalog check . --no-probe

If pay is not installed, use npx @solana/pay catalog ... in place of pay catalog ....

Directory layout

providers/
  <operator>/<name>/PAY.md              # FQN: <operator>/<name>
  <operator>/<origin>/<name>/PAY.md     # FQN: <operator>/<origin>/<name>

Use the two-level layout when you operate the API directly. Use the three-level layout when your gateway proxies another provider's API.

Sidecar files such as openapi.json live in the same directory as PAY.md:

providers/acme/search/
  PAY.md
  openapi.json

The name: field must match the parent directory name. For providers/acme/search/PAY.md, use name: search.

PAY.md shape

---
name: search
title: 'Acme Search'
description: 'Search Acme records and return normalized matches, source URLs, and confidence scores.'
use_case: 'Use for Acme record lookup, entity search, source-backed matching, and confidence-scored results.'
category: search
service_url: https://api.acme.example
openapi:
  path: openapi.json
---

Explain what the API offers, when an agent should use it, and how to keep paid calls narrow.

Required frontmatter: name, title, description, use_case, category, service_url, plus exactly one of openapi: or inline endpoints:.

Use openapi.path for co-located specs or openapi.content for tiny inline specs. The public registry rejects openapi.url; fetch the spec once and commit the snapshot:

curl -fsSL https://api.example.com/openapi.json -o providers/<operator>/<name>/openapi.json

Validation commands

Command	Use
`pay catalog check providers/<fqn>/PAY.md`	Validate one provider with frontmatter checks, OpenAPI resolution, live probe, and Solana verdict.
`pay catalog check providers/<fqn>/PAY.md --no-probe`	Run a faster frontmatter and OpenAPI smoke test.
`pay catalog check providers/<fqn>/PAY.md -v`	Print per-endpoint probe and verdict tables.
`pay catalog check providers/<fqn>/PAY.md --strict`	Treat every non-Solana endpoint as a blocking error.
`pay catalog check . --no-probe`	Check every `PAY.md` in the registry without live probes.
`pay catalog check . --changed-from origin/main`	Probe providers changed since `origin/main`. This mirrors local PR prep.
`pay catalog build .`	Build `dist/skills.json` and per-provider detail JSON. Main-branch CI runs this; local provider PRs usually do not need it.

PR checklist

pay catalog check providers/<fqn>/PAY.md is green locally.
The OpenAPI spec is committed as openapi.path or inline openapi.content, not referenced by URL.
name: matches the parent directory name.
description is 64-255 characters and describes capabilities and result shapes.
use_case is 32-255 characters and names concrete agent tasks.
No TODO placeholders remain.
service_url is a production HTTPS domain, not localhost or an IP address.
Free endpoints omit pricing.
Paid endpoints return a valid Solana 402 challenge accepting USDC or USDT.

Agents discover merged providers through pay skills search, pay skills show, and Pay MCP catalog tools within a few minutes of publication.