Developers
pay server and pay catalog — gate an API with stablecoin payments, then make it discoverable.
The Developers group covers the publisher side: run a payment gateway in front of your service, then publish a provider entry so agents can discover it.
For the narrative ("how do I gate my API and ship it?") see Building with pay → Getting started. This page is the syntax reference.
pay server
Gate your API with stablecoin payments.
pay server <subcommand>| Subcommand | Purpose |
|---|---|
demo | Local demo with a dashboard for tracing payments. |
start | Run the gateway against a provider YAML spec. |
scaffold | Generate a starter provider.yml. |
plans publish | Derive on-chain Plan PDAs from a spec. |
pay server demo
Start a local demo with a dashboard for tracing payments. Uses bundled endpoints — no spec required.
pay --sandbox server demo
pay --sandbox server demo --local| Flag | Type | Default | Description |
|---|---|---|---|
--bind | string | 0.0.0.0:1402 | Address to bind to. |
--recipient | string | — | Recipient wallet address for payments. |
--currency | string | USDC | Payment currency (USDC, USDT, SOL, …). |
--local | bool | false | Use local Surfpool (http://localhost:8899) instead of the hosted sandbox. |
--otlp-sidecar | HOST:PORT | — | Export traces and metrics to an OTLP HTTP sidecar. |
pay server start
Start a proxy that gates your API with stablecoin payments. Reads endpoint pricing and payment requirements from a YAML spec.
pay --sandbox server start provider.yml
pay server start provider.yml --bind 0.0.0.0:8080
pay server start provider.yml --openapi openapi.json --public-url https://gateway.example.com| Flag | Type | Default | Description |
|---|---|---|---|
<SPEC> | positional | — | Path to the provider YAML spec file. Required. |
--bind | string | 0.0.0.0:1402 | Address to bind to. |
--recipient | string | — | Recipient wallet address for payments. Overrides operator.recipient in the spec. |
--currency | string | USDC | Default payment currency for endpoints that don't specify one. |
--rpc-url | string | — | RPC URL for payment verification. |
--debugger | bool | false | Launch the Payment Debugger UI alongside the gateway. Automatic under --sandbox. |
--otlp-sidecar | HOST:PORT | — | Export traces and metrics to an OTLP HTTP sidecar. |
--openapi | path | — | OpenAPI 3 or Google Discovery JSON describing the upstream API. The gateway re-serves it at GET /openapi.json with URLs rewritten to point at itself. |
--public-url | URL | — | Override the public base URL used when rewriting servers[].url / rootUrl. Derived from the request Host header when omitted. |
See YAML Specification for the spec format and Defining pricing for how to price each endpoint.
pay server scaffold
Generate a starter provider.yml.
pay server scaffold provider.yml| Argument | Type | Default | Description |
|---|---|---|---|
[OUTPUT] | positional | provider.yml | Output file path. |
pay server plans publish
Derive on-chain Plan PDAs for subscription: endpoints in a spec. The default is a dry run that prints the derived PDAs without modifying the YAML.
pay server plans publish
pay server plans publish --spec pay-demo.yaml --dry-run
pay server plans publish --spec pay-demo.yaml --write| Flag | Type | Default | Description |
|---|---|---|---|
--spec | path | pay-demo.yaml | YAML spec containing subscription: endpoints. |
--owner | base58 | — | Plan owner pubkey. Falls back to operator.recipient in the spec. |
--dry-run | bool | true | Print the derived Plan PDAs without modifying the YAML. |
--write | bool | false | Write the derived Plan PDAs back into the YAML. Use after publishing the Plan accounts on-chain through another tool — pay does not broadcast them in v0. |
pay catalog
Make your API discoverable in pay's public catalog.
pay catalog <subcommand>| Subcommand | Purpose |
|---|---|
scaffold | Scaffold a starter PAY.md from an OpenAPI document. |
check | Read-only validation — parse, frontmatter check, probe, Solana verdict. |
build | Full registry build: validate, then emit dist/skills.json and per-provider detail files. |
pay catalog scaffold
Scaffold a new provider PAY.md from an OpenAPI document URL. The leaf segment of the FQN becomes the name: field; the full FQN is used as a comment hint.
pay catalog scaffold quicknode/rpc https://example.com/openapi.json
pay catalog scaffold quicknode/rpc https://example.com/openapi.json --output-dir ./providers| Flag | Type | Default | Description |
|---|---|---|---|
<FQN> | positional | — | Fully-qualified provider name, e.g. quicknode/rpc. Required. |
<OPENAPI_URL> | positional | — | URL to the OpenAPI document (JSON or YAML). Required. |
--output-dir | path | . | Output directory. Written as <dir>/<fqn>/PAY.md. |
--force | bool | false | Overwrite the output file if it already exists. |
pay catalog check
Read-only validation: parse, frontmatter check, live probe, Solana verdict. Used by PR CI and local development. Never writes to disk.
pay catalog check
pay catalog check ./providers/quicknode/rpc/PAY.md
pay catalog check --changed-from main
pay catalog check --files providers/google/translate/PAY.md providers/google/maps/PAY.md| Flag | Type | Default | Description |
|---|---|---|---|
[PATH] | positional | . | Registry root, or a single PAY.md. When pointed at a file, the FQN is derived from parent directories. |
--no-probe | bool | false | Skip live probing (frontmatter-only check). |
--probe-timeout | seconds | 10 | Per-endpoint probe timeout. |
--probe-concurrency | int | 5 | Max concurrent provider probes. |
--currencies | csv | USDC,USDT | Accepted stablecoin symbols. Non-listed currencies are flagged as wrong_currency. |
--strict | bool | false | Treat every non-Solana endpoint as a blocking error (default: warn). |
--format | enum | table | Verdict output format. table, json, or github (emits Actions ::warning::/::error:: annotations). |
--verbose (-v) | bool | false | Print per-provider, per-endpoint probe + verdict breakdown. |
--summary-out | path | — | Also write a GitHub-flavored markdown summary to this path, regardless of --format. |
--files | paths | — | Specific PAY.md files to check (relative to the registry root when PATH is a directory). Mutually exclusive with --changed-from. |
--changed-from | git-ref | — | Check providers whose PAY.md or sidecar files changed between <REF> and HEAD. Requires git on $PATH. |
pay catalog build
Full registry build: run the same checks as check, then write dist/skills.json and per-provider detail files.
pay catalog build
pay catalog build --base-url https://catalog.pay.sh/v1
pay catalog build --only quicknode/rpc,helius/das --previous-dist ./dist-prev| Flag | Type | Default | Description |
|---|---|---|---|
[PATH] | positional | . | Registry root containing providers/, affiliates/, aggregators/. |
--base-url | URL | https://catalog.pay.sh/v1 | CDN base URL for detail-file references in the index. |
--output (-o) | path | <path>/dist | Output directory. |
--no-probe | bool | false | Skip live probing. Output omits probe-derived pricing/protocol/supported_usd metadata. |
--probe-timeout | seconds | 10 | Per-endpoint probe timeout. |
--probe-concurrency | int | 5 | Max concurrent provider probes. |
--only | csv FQNs | — | (Re)build these providers from source; copy every other provider from --previous-dist. Fast partial rebuild at merge time. |
--previous-dist | path | — | Path to a previously-built dist/ directory. Required when --only is set. |