Developers
pay server, pay gate, and pay catalog — gate APIs or local inference, then make services discoverable.
The Developers group covers the publisher side: run a payment gateway in front of your API or local inference server, 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
Manage gateway demos, paywall specs, and subscription plans.
pay server <subcommand>| Subcommand | Purpose |
|---|---|
demo | Local demo with a dashboard for tracing payments. |
scaffold | Generate a starter paywall.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 scaffold
Generate a starter paywall.yml.
pay server scaffold paywall.yml| Argument | Type | Default | Description |
|---|---|---|---|
[OUTPUT] | positional | paywall.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 gate
Gate APIs or local inference with stablecoin payments.
pay gate <subcommand>| Subcommand | Purpose |
|---|---|
api | Run a gateway against a paywall YAML spec. |
inference | Discover and gate local OpenAI-compatible inference servers. |
pay gate api
Start a proxy that gates your API with stablecoin payments. Reads endpoint pricing and payment requirements from a paywall YAML.
pay --sandbox gate api paywall.yml
pay gate api paywall.yml --bind 0.0.0.0:8080
pay gate api paywall.yml --openapi openapi.json --public-url https://gateway.example.com| Flag | Type | Default | Description |
|---|---|---|---|
<PAYWALL> | positional | — | Path to the paywall YAML 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 paywall. |
--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. |
--no-register | bool | false | Skip decentralized provider registration when --public-url and a versioned API profile are present. |
See YAML Specification for the paywall format and Defining pricing for how to price each endpoint.
pay server start and pay serve start remain accepted for backward compatibility. Use pay gate api in new scripts and documentation.
pay gate inference
Discover local Ollama, LM Studio, llama.cpp, vLLM, and exo servers, then expose them through one OpenAI-compatible gateway.
pay gate inference
pay --sandbox gate inference paywall.yml
pay --sandbox gate inference --price '*=0.10/0.30'
pay gate inference --providers ollama,vllm --no-tui --no-web| Flag | Type | Default | Description |
|---|---|---|---|
[PAYWALL] | positional | — | Optional YAML with per-model input/output USD rates per 1 million tokens. |
--bind | HOST:PORT | 127.0.0.1:1402 | Public gateway bind address. |
--public-url | URL or host | — | Public address to advertise. Pass auto to discover the public IP. |
--no-register | bool | false | Skip decentralized provider registration when --public-url is set. |
--providers | CSV | all | Probe only the listed provider slugs, such as ollama,vllm. |
--probe-timeout | integer | 400 | Per-endpoint probe timeout in milliseconds. |
--no-tui | bool | false | Print log lines instead of the live terminal UI. |
--no-web | bool | false | Disable the embedded web UI. |
--watch-interval | integer | 10 | Seconds between provider probes. Set to 0 to disable watching. |
--spec | path | — | Add a hand-written API spec alongside discovered providers. Repeat for multiple specs. |
--sandbox | bool | false | Require localnet specs. The global pay --sandbox flag applies the same guard. |
--price | string | — | Inline model=input/output rates. Use *=input/output for the default. |
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 --output-dir providers
pay catalog scaffold quicknode/rpc https://example.com/openapi.json --output-dir providers --force| 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. Use providers from the registry root. |
--force | bool | false | Overwrite the output file if it already exists. |
The scaffold command fetches a remote OpenAPI document as input. Published registry entries should commit that snapshot next to PAY.md and reference it with openapi.path.
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 origin/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. |