Paywalls

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

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

Every operation below requires a Bearer token. See Authentication.

REST API for Gate, the x402 gateway. 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

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.

Pricing models

pricing_model selects how the per-call price is resolved:

Gateway protocol

The 402 challenge is delivered base64-encoded in the PAYMENT-REQUIRED response header (x402Version 2). The JSON body of the 402 is a human-readable hint: clients read the header, not the body.

Payment goes back in the PAYMENT-SIGNATURE request header. X-PAYMENT is still accepted for x402 v1 compatibility, and a v2 client may send both.

The settlement result comes back in the PAYMENT-RESPONSE response header (also mirrored to X-PAYMENT-RESPONSE for v1 clients). Both are listed in Access-Control-Expose-Headers, so a browser client can read them.

An optional Idempotency-Key request header makes a paywall call settle at most once, even across re-signed retries. A retry that arrives while the first is still in flight gets 409 idempotency_in_progress; a completed call replays the stored response with Idempotent-Replay: true.

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",
  "refunded_atomic": "0",
  "refunded": "0.00",
  "net_atomic": "1280000",
  "net": "1.28",
  "last_settled_at": "2026-07-10T21:04:11Z"
}

gross is what payers authorized, refunded is what went back to them, and net is what the paywall kept. On flat, tiered, and dynamic paywalls there are no refunds, so gross equals net. On a metered paywall gross is the sum of the signed ceilings and net is the actual metered revenue, so the two read as ceiling versus actual.

Errors

See also

• Monetized MCP servers: per-tool pricing for an MCP server you already run, managed on /v1/mcp-servers and served at gw.codespar.dev/mcp/<slug>.
• Getting discovered: the public manifest at gw.codespar.dev/.well-known/x402 that lists your active paywalls with their x402 terms.

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET /v1/paywalls

List paywalls

Responses

Response 200

Example response

{
  "paywalls": [
    {
      "id": "obj_0000000000000000",
      "project_id": "prj_0000000000000000",
      "slug": "example",
      "name": "Example",
      "upstream_url": "https://example.com/hook",
      "price": "string",
      "price_atomic": "string",
      "currency": "BRL",
      "environment": "live",
      "payto_kind": "byo",
      "payto_address": "string",
      "pricing_model": "flat",
      "metered_config": {
        "basis": "string",
        "base_atomic": "string",
        "min_mult": 1,
        "max_mult": 1,
        "units_header": "string"
      },
      "active": true,
      "gateway_url": "https://example.com/hook",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/paywalls \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/paywalls/{id}

Read one paywall

Path parameters

Responses

Response 200

Example response

{
  "id": "obj_0000000000000000",
  "project_id": "prj_0000000000000000",
  "slug": "example",
  "name": "Example",
  "upstream_url": "https://example.com/hook",
  "price": "string",
  "price_atomic": "string",
  "currency": "BRL",
  "environment": "live",
  "payto_kind": "byo",
  "payto_address": "string",
  "pricing_model": "flat",
  "metered_config": {
    "basis": "string",
    "base_atomic": "string",
    "min_mult": 1,
    "max_mult": 1,
    "units_header": "string"
  },
  "active": true,
  "gateway_url": "https://example.com/hook",
  "created_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X GET https://api.codespar.dev/v1/paywalls/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

DELETE /v1/paywalls/{id}

Delete a paywall

Path parameters

Responses

Example request

curl -X DELETE https://api.codespar.dev/v1/paywalls/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/paywalls/{id}/stats

Earnings for one paywall

Path parameters

Responses

Response 200

Example response

{
  "paywall_id": "paywall_0000000000000000",
  "slug": "example",
  "currency": "BRL",
  "settled_count": 1,
  "gross_atomic": "string",
  "gross": "string",
  "refunded_atomic": "string",
  "refunded": "string",
  "net_atomic": "string",
  "net": "string"
}

Example request

curl -X GET https://api.codespar.dev/v1/paywalls/{id}/stats \
  -H "Authorization: Bearer $CODESPAR_API_KEY"