> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myproceeds.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Paywalls

> Create, list, get, update, and delete Proceeds paywalls from the CLI.

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

<Note>
  Prices are USDC **base-unit strings**: `1000000` = `$1.00`, `10000` = `$0.01`.
</Note>

## 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

```bash theme={null}
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):

```json theme={null}
{
  "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`:

```bash theme={null}
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):

```json theme={null}
{
  "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](#share-payment-urls).

## List

```bash theme={null}
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):

```json theme={null}
{
  "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

```bash theme={null}
proceeds paywalls get <id> --format json
```

Example response (trimmed):

```json theme={null}
{
  "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

```bash theme={null}
proceeds paywalls update <id> --name "CLI docs GET demo" --format json
```

Example response (trimmed):

```json theme={null}
{
  "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) |

<Warning>
  **`slug` and `serviceId` cannot be updated.** Supplied arrays **replace** existing arrays. Switching to **tiered** requires `priceTiers`. Switching to **exact** clears tiers.
</Warning>

## Delete

```bash theme={null}
proceeds paywalls delete <id> --yes
```

Permanent. Requires `--yes`.

## Share payment URLs

<Warning>
  Payment URLs are **not** returned in create responses. Construct them from the service ID and paywall slug:
</Warning>

```text theme={null}
https://myproceeds.xyz/api/x402/pay/{serviceId}/{slug}
https://myproceeds.xyz/api/mpp/pay/{serviceId}/{slug}
```

## Related

<CardGroup cols={2}>
  <Card title="Services" icon="server" href="/cli/services">
    Manage the owning service.
  </Card>

  <Card title="Transactions and events" icon="chart-line" href="/cli/transactions">
    List payments and request events.
  </Card>
</CardGroup>