HTTP API reference for the Monetize Gateway — create and manage x402 paywalls that charge agents per call, and read per-paywall earnings.

Paywalls API

REST API for the Monetize Gateway concept. A paywall charges agents per call for an endpoint you own, settling in USDC over x402.

Base URL: https://api.codespar.dev

All endpoints require authentication. See Authentication. Endpoints marked admin require a bearer api key OR service auth with an x-codespar-user header for an account admin/owner. Paywalls are project-scoped.

Paywall object

Field	Type	Description
`id`	`string`	Paywall ID, `pw_<...>`
`project_id`	`string`	Owning project
`slug`	`string`	URL slug; global namespace. `/^[a-z0-9_-]+$/`
`name`	`string`	Display name, max 128
`upstream_url`	`string`	Where paid calls are proxied
`price`	`string`	USDC per call, decimal (min `"0.01"`)
`price_atomic`	`string`	Same price in atomic USDC (6 dp)
`currency`	`string`	`USDC`
`payto_kind`	`"provisioned" \| "byo"`	Where settlement lands
`payto_address`	`string \| null`	The `0x` address for `byo`
`consumer_id`	`string \| null`	The consumer whose wallet receives for `provisioned`
`active`	`boolean`	Paused paywalls return 402 with no settlement
`gateway_url`	`string`	`https://gw.codespar.dev/<slug>`
`created_at`	`string`	ISO 8601

Create a paywall

POST /v1/paywalls (admin)

Body

{
  "slug": "market-data",
  "name": "Market data API",
  "upstream_url": "https://api.yourservice.com/quote",
  "price": "0.01",
  "currency": "USDC",
  "consumer_id": "your-consumer",
  "payto": { "kind": "provisioned" }
}

payto.kind: "provisioned" — settles to the CodeSpar wallet of consumer_id (required for this kind).
payto.kind: "byo" — settles to payto.address (a 0x EVM address).

Response — 201 Created with the paywall object.

List paywalls

GET /v1/paywalls

Response

{ "paywalls": [/* Paywall */] }

Get a paywall

GET /v1/paywalls/:id — the paywall object, or 404 paywall_not_found.

Update a paywall

PATCH /v1/paywalls/:id (admin)

Body (at least one field)

{ "name": "...", "upstream_url": "...", "price": "0.02", "active": false }

Set active: false to pause (callers get 402, nothing settles); true to resume.

Delete a paywall

DELETE /v1/paywalls/:id (admin) — 204 No Content. Paywalls are config, not audit data; settled receipts are retained independently.

Earnings

GET /v1/paywalls/:id/stats

Read-only aggregate over the paywall's settled payments.

Response

{
  "paywall_id": "pw_...",
  "slug": "market-data",
  "currency": "USDC",
  "settled_count": 128,
  "gross_atomic": "1280000",
  "gross": "1.28",
  "last_settled_at": "2026-07-10T21:04:11Z"
}

Errors

HTTP	code	when
`400`	`invalid_body`	body failed validation
`403`	`forbidden`	non-admin caller on an admin endpoint
`404`	`paywall_not_found`	unknown id in this project
`409`	`slug_conflict`	the slug is already taken

Paywalls API

On this page