Paywalls

Paywalls price a route under a service. This page covers create, listing, updates, delete, and share URLs.

Prices are USDC base-unit strings: 1000000 = $1.00, 10000 = $0.01.

Create

A paywall is either Exact or Tiered:

Exact — one fixed USDC price for one upstream URL. Agents pay that amount, then Proceeds forwards the request.
Tiered — several named prices under one paywall, each mapped to its own path. Agents pick a tier (or the path selects it), pay that tier’s price, then Proceeds forwards to that path.

	Exact	Tiered
What you set	A single `price`	A list of `priceTiers` (name, price, path)
How you create	Field flags or `--file` / `--data`	`--file` or `--data` only (nested tiers)
`pricingMode`	`exact` (server default)	`tiered`

--file / --data cannot be combined with field flags. Pass --pricing-mode exact when you want Exact spelled out in the command; omit it and the server still defaults to Exact.

Exact

proceeds paywalls create \
  --slug current-weather \
  --name "Current weather" \
  --target-url https://weather.example.com/current \
  --price 10000 \
  --currency USDC \
  --pricing-mode exact \
  --networks base-sepolia \
  --allowed-methods GET \
  --service-id SERVICE_ID \
  --format json

Replace SERVICE_ID with the owning service id from services create / services list. Example response (trimmed — ids only, no payment URL):

{
  "data": {
    "id": "vrxf…",
    "slug": "current-weather",
    "name": "Current weather",
    "targetUrl": "https://weather.example.com/current",
    "price": "10000",
    "currency": "USDC",
    "pricingMode": "exact",
    "priceTiers": null,
    "networks": ["base-sepolia"],
    "timeout": 300000,
    "allowedMethods": ["GET"],
    "enabled": true,
    "serviceId": "cmu…"
  }
}

Tiered

Tiered create needs --file or --data for nested priceTiers:

cat > paywall-tiered.json <<'JSON'
{
  "slug": "weather-tiers",
  "name": "Weather tiers",
  "targetUrl": "https://weather.example.com/current",
  "currency": "USDC",
  "pricingMode": "tiered",
  "priceTiers": [
    { "name": "basic", "price": "10000", "targetPath": "/current" },
    { "name": "plus", "price": "50000", "targetPath": "/forecast" }
  ],
  "networks": ["base-sepolia"],
  "allowedMethods": ["GET"],
  "serviceId": "SERVICE_ID",
  "enabled": true
}
JSON

proceeds paywalls create --file paywall-tiered.json --format json

Example response (trimmed — API also echoes a top-level price, often the first tier):

{
  "data": {
    "id": "is86…",
    "slug": "weather-tiers",
    "name": "Weather tiers",
    "targetUrl": "https://weather.example.com/current",
    "price": "10000",
    "currency": "USDC",
    "pricingMode": "tiered",
    "priceTiers": [
      { "name": "basic", "price": "10000", "targetPath": "/current" },
      { "name": "plus", "price": "50000", "targetPath": "/forecast" }
    ],
    "networks": ["base-sepolia"],
    "timeout": 300000,
    "allowedMethods": ["GET"],
    "enabled": true,
    "serviceId": "cmu…"
  }
}

Payment URLs are not returned in create responses — see Share payment URLs.

List

proceeds paywalls list --service-id <serviceId> --limit 2 --format json

Flag	Notes
`--limit`	Page size (1–100), default `20`
`--offset`	Records to skip, default `0`
`--service-id`	Filter by owning service
`--enabled` / `--no-enabled`	Filter by enabled status

Example response (trimmed):

{
  "data": [
    {
      "id": "mmmo…",
      "slug": "cli-docs-flags",
      "name": "CLI docs flags exact",
      "targetUrl": "https://httpbin.org/uuid",
      "price": "10000",
      "currency": "USDC",
      "pricingMode": "exact",
      "networks": ["base-sepolia"],
      "allowedMethods": ["GET"],
      "enabled": true,
      "serviceId": "cmu…"
    },
    {
      "id": "is86…",
      "slug": "cli-docs-tiered",
      "pricingMode": "tiered",
      "priceTiers": [
        { "name": "basic", "price": "10000", "targetPath": "/get" },
        { "name": "plus", "price": "50000", "targetPath": "/anything/plus" }
      ],
      "serviceId": "cmu…"
    }
  ],
  "meta": {
    "pagination": { "total": 3, "limit": 2, "offset": 0, "hasMore": true }
  }
}

Get

proceeds paywalls get <id> --format json

Example response (trimmed):

{
  "data": {
    "id": "mmmo…",
    "slug": "cli-docs-flags",
    "name": "CLI docs flags exact",
    "targetUrl": "https://httpbin.org/uuid",
    "price": "10000",
    "currency": "USDC",
    "pricingMode": "exact",
    "networks": ["base-sepolia"],
    "allowedMethods": ["GET"],
    "enabled": true,
    "serviceId": "cmu…"
  }
}

Update

proceeds paywalls update <id> --name "CLI docs GET demo" --format json

Example response (trimmed):

{
  "data": {
    "id": "mmmo…",
    "slug": "cli-docs-flags",
    "name": "CLI docs GET demo",
    "price": "10000",
    "pricingMode": "exact",
    "enabled": true,
    "updatedAt": "2026-09-19T07:46:10.225Z"
  }
}

Flag	Purpose
`--name`	Display name
`--description`	Description
`--target-url`	Upstream target URL
`--price`	USDC base-unit string
`--pricing-mode`	`exact` or `tiered`
`--networks`	Accepted network; repeat for multiple
`--allowed-methods`	HTTP method; repeat for multiple
`--enabled` / `--no-enabled`	Enable or disable
`--file` / `--data`	Complete JSON (exclusive with field flags)

slug and serviceId cannot be updated. Supplied arrays replace existing arrays. Switching to tiered requires priceTiers. Switching to exact clears tiers.

Delete

proceeds paywalls delete <id> --yes

Permanent. Requires --yes.

Payment URLs are not returned in create responses. Construct them from the service ID and paywall slug:

https://myproceeds.xyz/api/x402/pay/{serviceId}/{slug}
https://myproceeds.xyz/api/mpp/pay/{serviceId}/{slug}

Services

Manage the owning service.

Transactions and events

List payments and request events.

Getting Started

Guides

Manage

API Reference

CLI

Agent Wallets

Create

Exact

Tiered

List

Get

Update

Delete

Services

Transactions and events

​Create

​Exact

​Tiered

​List

​Get

​Update

​Delete

​Share payment URLs

​Related

Services

Transactions and events

Create

Exact

Tiered

List

Get

Update

Delete

Share payment URLs

Related