CIP-18: Payment Gating

​

1. Abstract

​

2. Motivation

• Query-path requests are free. The Gateway absorbs the compute cost of running the actor’s handler against committed state.
• Command-path gas is paid by the Gateway from its staked balance and recovered through the serving fee pool.

1. Free-rider problem. Any internet client can hit any actor’s endpoints at no cost. Gateways bear the compute burden with no direct per-request compensation, creating a tragedy of the commons.
2. No actor monetization. Actors cannot charge for their services. This blocks micro-SaaS, paid APIs, data feeds, and other business models that require per-request revenue.
3. Agent economy bottleneck. Autonomous agent-to-agent interaction requires per-request settlement. Without it, agents cannot transact for each other’s services.
4. x402 momentum. The x402 protocol is emerging as the HTTP payment standard for machine-to-machine commerce. Cowboy should be compatible from day one so that off-chain clients and agents can pay for actor services using familiar HTTP semantics.

​

3. Design Goals

• x402 wire compatibility. Use standard 402 Payment Required responses with PAYMENT-REQUIRED / PAYMENT-SIGNATURE headers so that x402-aware clients work out of the box.
• Multiple funding models. Different use cases need different payment patterns: pay-per-call for APIs, actor-subsidized budgets for onboarding, prepaid passes for bulk buyers, epoch subscriptions for regular consumers.
• Multi-asset support. Accept native CBY and CIP-20 fungible tokens, including bridged stablecoins.
• Gateway-enforced, on-chain settled. Gateways check payment at the edge for low latency. Settlement happens on-chain for finality.
• Composable. Works with CIP-7 streams (epoch billing model), CIP-14 ingress (Gateway dispatch), CIP-20 tokens (multi-asset), and CIP-3 gas metering (command-path cost recovery).

​

4. Non-goals

• Fiat payment rails. ACH, SEPA, and other fiat integrations are deferred to a future CIP.
• Cross-chain bridge design. This CIP assumes bridge infrastructure exists for settling EVM-side payments. Bridge specification is out of scope.
• Actor-to-actor payment gating. Internal send_message calls between actors are not gated by this CIP. Payment gating applies only to external HTTP ingress.
• Streaming metered billing. Pay-as-you-consume billing within a single long-running request (e.g., token-by-token LLM billing) is deferred.

​

5. Definitions

• PaymentGate: System actor at address 0x0013 that manages payment policies, budgets, passes, and subscriptions.
• Payment Policy: Actor-declared configuration specifying payment requirements per endpoint, including pricing, accepted assets, and payment model selection.
• Serving Budget: CBY pool deposited by an actor owner into the PaymentGate, used to subsidize client requests so clients pay nothing.
• Prepaid Pass: A client-purchased request quota bound to a (client, actor) pair. Each request decrements the pass balance.
• Epoch Subscription: A time-bounded access entitlement, analogous to CIP-7’s key-epoch model, granting unlimited access to gated endpoints for a purchased number of epochs.
• Price Table: An ordered list of rules matching request paths and methods to specific payment models and prices.

​

6. Payment Models

​

6.1 Per-Request (Client-Paid, x402)

1. Client sends a request to a gated endpoint without payment headers.
2. Gateway looks up the actor’s PaymentPolicy from its local state cache.
3. Gateway returns 402 Payment Required with a PAYMENT-REQUIRED header containing the x402 PaymentRequired JSON (see §9.1).
4. Client inspects the payment requirements, selects a payment scheme from the accepts array, and constructs a signed payment authorization.
5. Client retries the request with a PAYMENT-SIGNATURE header containing the signed payment payload.
6. Gateway verifies the payment via the PaymentGate, dispatches the request to the actor, and settles the payment on-chain.
7. Gateway returns the actor’s response with a PAYMENT-RESPONSE header containing settlement confirmation.

• actor_fee → actor’s treasury address
• protocol_fee → protocol treasury (burned or governed)
• gateway_recovery → Gateway (command-path gas recovery only; zero for query path)

​

6.2 Actor-Funded Budget

1. Actor owner calls PaymentGate.deposit_budget(actor, amount) to fund the budget.
2. The actor’s PaymentPolicy sets default_mode: "actor_funded" for the relevant endpoints.
3. Clients request endpoints normally — no payment headers needed.
4. Gateway checks that the actor’s budget has sufficient balance before serving the request.
5. Gateway deducts the per-request cost from the budget via PaymentGate.deduct_budget().
6. If the budget is depleted, the Gateway either falls back to client-paid 402 or returns 503, based on the actor’s BudgetConfig.fallback setting.

• Rate limits (rate_limit_rps): Maximum free requests per second to prevent abuse.
• Daily caps (daily_cap): Maximum daily spend from the budget.
• Auto-refill (auto_refill): Automatically refill from the actor’s account balance when the budget drops below a threshold.

​

6.3 Prepaid Pass

1. Client calls PaymentGate.purchase_pass(actor, credits, beneficiary) and pays credits × per_request_price.
2. PaymentGate returns a pass_id — a random bytes32 identifier for the prepaid allocation.
3. On subsequent requests, the client includes an X-Cowboy-Pass: {pass_id} header.
4. Gateway verifies pass validity and remaining credits.
5. Each served request decrements the pass balance by the endpoint’s configured cost.
6. Passes expire after PASS_EXPIRY_BLOCKS (configurable per actor, max ~1 year).

• No per-request cryptographic signing — one-time purchase, then simple header inclusion.
• Reduced Gateway verification overhead (pass lookup vs. signature verification).
• Predictable cost for clients purchasing in bulk.

​

6.4 Epoch Subscription

1. Client calls PaymentGate.purchase_epoch(actor, epochs, beneficiary, payer).
2. PaymentGate records the entitlement on-chain: (beneficiary_account, actor_address, active_until_epoch).
3. Entitlement uses a rolling window (same as CIP-7): purchasing additional epochs extends active_until_epoch rather than creating a new subscription.
4. Idempotent purchases: if the requested epoch is already covered, no charge is applied.
5. Gateway checks the entitlement before serving — no payment headers needed.
6. Supports sponsored subscriptions: the payer and beneficiary may differ.

• fee_per_epoch: price per epoch in the actor’s default asset.
• epoch_blocks: blocks per epoch (max MAX_EPOCH_BLOCKS).
• min_purchase / max_purchase: bounds on epochs per purchase.

​

6.5 Hybrid Mode

• Use epoch subscriptions for most endpoints, but per-request pricing for expensive compute endpoints.
• The price table (§8.1) supports per-path overrides with model selection.
• Gateway evaluates the fallback chain in order: subscription → pass → budget → per-request 402.
• If a client has an active subscription covering the endpoint, the request is served without checking passes or budget.

​

7. PaymentGate System Actor

​

7.1 Payment Policy

PaymentPolicy {
    actor:              Address,
    enabled:            bool,
    default_mode:       "client_paid" | "actor_funded" | "free",

    price_table:        [PriceRule],

    budget_config:      BudgetConfig | null,
    epoch_config:       EpochConfig | null,
    pass_config:        PassConfig | null,

    accepted_assets:    [AssetConfig],
    treasury:           Address,
}

PriceRule {
    path_pattern:       string,          // glob: "/api/*", exact: "/api/inference"
    methods:            [string],        // ["GET"], ["POST"], ["*"]
    model:              "client_paid" | "actor_funded" | "pass" | "epoch",
    amount:             u256,            // price in atomic units of default asset
    asset:              Address | null,  // override asset (null = actor's default)
}

BudgetConfig {
    rate_limit_rps:     u32,             // max free requests per second
    daily_cap:          u256,            // max daily spend from budget
    fallback:           "402" | "503",   // behavior when budget is depleted
    auto_refill:        bool,            // auto-refill from actor's account balance
}

EpochConfig {
    fee_per_epoch:      u256,            // price per epoch in default asset
    epoch_blocks:       u32,             // blocks per epoch
    min_purchase:       u32,             // minimum epochs per purchase
    max_purchase:       u32,             // maximum epochs per purchase
}

PassConfig {
    min_credits:        u32,             // minimum credits per purchase
    max_credits:        u32,             // maximum credits per purchase
    expiry_blocks:      u64,             // pass validity window in blocks
}

AssetConfig {
    asset:              Address,         // token address (0x0 = native CBY)
    scheme:             string,          // "cowboy:exact", "exact"
    network:            string,          // CAIP-2 chain ID: "cowboy:1", "eip155:8453"
    decimals:           u8,
    symbol:             string,
}

​

7.2 PaymentGate API

​

8. x402 Wire Format

​

8.1 Gateway 402 Response

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: base64(PaymentRequired JSON)
X-Cowboy-Block: {block_height}

{
  "accepts": [
    {
      "scheme": "cowboy:exact",
      "network": "cowboy:1",
      "maxAmountRequired": "1000000",
      "resource": "https://myactor.cowboy.network/api/data",
      "description": "Query the data API",
      "maxTimeoutSeconds": 30,
      "asset": "0x0000000000000000000000000000000000000000",
      "extra": {
        "actor": "0x1234...abcd",
        "treasury": "0x5678...ef01",
        "protocol_fee_bps": 500
      }
    }
  ],
  "version": "2"
}

​

8.2 Cowboy Payment Schemes

​

8.2.1 cowboy:exact — Native CBY or CIP-20 Token Transfer

payload: {
    signature:      bytes,              // Cowboy Ed25519 signature over authorization
    authorization: {
        from:           Address,        // payer account
        to:             Address,        // actor treasury
        amount:         u256,           // total amount (actor_fee + protocol_fee + gateway_recovery)
        asset:          Address,        // 0x0 for native CBY, token address for CIP-20
        valid_after:    u64,            // block height (authorization not valid before)
        valid_before:   u64,            // block height (authorization expires after)
        nonce:          bytes32,        // unique nonce for replay protection
        actor:          Address,        // target actor address (cross-actor replay protection)
        request_hash:   bytes32,        // hash of request envelope (request binding)
    }
}

​

8.2.2 exact (EVM) — Standard x402 ERC-20 Scheme

1. Client signs an EIP-3009 authorization for the EVM-side token.
2. Gateway or external facilitator submits the transfer on the EVM chain.
3. Bridge credits the equivalent amount on the Cowboy side.
4. PaymentGate settles the Cowboy-side distribution.

​

8.3 Client Payment Retry

GET /api/data HTTP/1.1
Host: myactor.cowboy.network
PAYMENT-SIGNATURE: base64(PaymentPayload JSON)

GET /api/data HTTP/1.1
Host: myactor.cowboy.network
X-Cowboy-Pass: {pass_id}

​

8.4 Settlement Response

HTTP/1.1 200 OK
PAYMENT-RESPONSE: base64(SettleResponse JSON)
X-Cowboy-Block: {block_height}

​

9. Gateway Integration

​

9.1 Request Flow (Updated)

1. Gateway receives an HTTP request for a registered actor (CIP-14 §7 Route Registry).
2. Payment check (NEW): Gateway reads the actor’s PaymentPolicy from its local state cache.
3. If the endpoint is free (no matching price rule and default_mode: "free") → proceed to dispatch.
4. If default_mode: "actor_funded" and budget has sufficient balance → deduct and proceed.
5. If the client has an active epoch subscription covering this endpoint → proceed.
6. If the request includes X-Cowboy-Pass → verify pass, check remaining credits, deduct, and proceed.
7. If the request includes PAYMENT-SIGNATURE → verify payment via PaymentGate → proceed.
8. Otherwise → return 402 Payment Required with payment requirements.
9. Dispatch via query path (GET/HEAD) or command path (POST/PUT/PATCH/DELETE) per CIP-14 §8.

​

9.2 Query Path Payment

1. Gateway verifies the payment authorization locally (reads PaymentGate state from its committed state view).
2. Gateway executes the actor’s query handler via queryActor.
3. Gateway submits a settlement transaction asynchronously (fire-and-forget to the mempool).
4. If settlement fails (e.g., nonce already consumed due to double-spend attempt), the Gateway absorbs the cost. This incentivizes correct verification.

​

9.3 Command Path Payment

1. Gateway verifies the payment authorization.
2. Gateway constructs a GatewayRegistry.dispatch() transaction (CIP-14 §9.2) with payment context attached.
3. The PaymentGate settles the payment atomically with request execution within the same transaction.
4. Revenue distribution: actor_fee → treasury, protocol_fee → protocol treasury, gas cost → Gateway (via existing CIP-14 gas recovery).

​

9.4 Payment Policy Caching

​

10. Client Identity

​

10.1 Cowboy Account Signature

X-Cowboy-Account: {account_address}
X-Cowboy-Signature: {signature_over_request}

​

10.2 Payment-Derived Identity

​

10.3 Session Token

​

11. Reserved Paths

​

12. Revenue Distribution

Per-request payment flow:

    Client pays total_amount
    ├── actor_fee ──────────> Actor Treasury
    ├── protocol_fee ───────> Protocol Treasury (burned or governance-directed)
    └── gateway_recovery ──> Gateway (command-path gas recovery only)

    protocol_fee = floor(actor_fee × PROTOCOL_PAYMENT_FEE_BPS / 10_000)
    gateway_recovery = estimated_gas_cost (command path only, 0 for query path)
    total_amount = actor_fee + protocol_fee + gateway_recovery

Pass purchase:
    total = credits × per_request_price
    protocol_fee = floor(total × PROTOCOL_PAYMENT_FEE_BPS / 10_000)
    actor_receives = total - protocol_fee

Epoch purchase:
    total = epochs × fee_per_epoch
    protocol_fee = floor(total × PROTOCOL_PAYMENT_FEE_BPS / 10_000)
    actor_receives = total - protocol_fee

​

13. Protocol Constants

PAYMENT_GATE_ADDRESS            = 0x0013
PROTOCOL_PAYMENT_FEE_BPS        = 500           // 5% protocol fee
MAX_PRICE_TABLE_ENTRIES          = 100
MIN_BUDGET_DEPOSIT               = <governance-set>
MAX_EPOCH_BLOCKS                 = 2_592_000     // ~30 days at 1 block/s
DEFAULT_EPOCH_BLOCKS             = 86_400        // ~1 day at 1 block/s
PASS_EXPIRY_BLOCKS               = 31_536_000    // ~1 year at 1 block/s
MAX_PREPAID_CREDITS              = 1_000_000
CBY_ASSET_ADDRESS                = 0x0000000000000000000000000000000000000000
PAYMENT_POLICY_CACHE_TTL_BLOCKS  = 1             // refresh every block
MAX_ACCEPTED_ASSETS              = 10

​

14. Entitlement: payment.gate

EntitlementGrant {
    id: "payment.gate",
    params: {
        "accepted_schemes": ["cowboy:exact", "exact", "cowboy:pass", "cowboy:epoch"],
        "max_price_per_request": u256,
    }
}

​

15. Security Considerations

• Replay attacks. Payment authorizations include a unique nonce consumed atomically on settlement, a request_hash binding the payment to a specific request, and valid_before / valid_after block-height bounds. An attacker cannot replay a captured payment authorization.
• Budget draining DoS. Actor-funded budgets are protected by configurable rate_limit_rps and daily_cap values. Gateways enforce these limits before deducting from the budget.
• Cross-Gateway double-spend. On-chain settlement consumes the payment nonce atomically. If two Gateways attempt to settle the same payment authorization, only the first succeeds. The second Gateway absorbs the cost, incentivizing correct local verification.
• Stale payment authorization. The valid_before block height bounds the authorization’s lifetime. Gateways MUST reject authorizations where current_block > valid_before.
• Price manipulation. Payment policy changes are committed on-chain and take effect only in the following block. A malicious actor cannot change prices between the 402 response and the client’s retry within the same block.
• Pass enumeration. Pass IDs are random bytes32 values, not sequential integers. An attacker cannot enumerate valid passes by incrementing an ID.
• Protocol fee evasion. All payment flows route through the PaymentGate system actor. Actors cannot bypass the protocol fee because Gateways only accept settlements processed by the PaymentGate.

​

16. Rationale

• Per-request is the most flexible but requires per-call signing, which is friction for high-frequency consumers.
• Actor-funded budgets enable free-tier access, onboarding flows, and freemium models.
• Prepaid passes reduce per-request overhead for bulk consumers and avoid repeated signing.
• Epoch subscriptions provide the simplest UX for regular consumers (subscribe once, access for a period).

​

17. Future Work

• Fiat payment rails. Extend the accepts array with fiat schemes (ACH, SEPA) using x402 network extensions.
• Session tokens. Browser-friendly authentication for subscriptions without per-request signing (§10.3).
• Actor-to-actor payment gating. Extend payment enforcement to internal send_message calls between actors.
• Streaming metered billing. An upto payment scheme for pay-as-you-consume billing within long-running requests (e.g., LLM token streaming).
• Cross-chain facilitator specification. Define the bridge relay protocol for EVM-side exact scheme settlement.
• Discovery and Bazaar integration. Registry of gated actors with pricing metadata for agent discovery.

​

18. Backwards Compatibility

• Actors without the payment.gate entitlement are completely unaffected. Their endpoints remain free (or Gateway-subsidized) as before.
• Gateways continue to serve free requests for non-gated actors using the existing CIP-14 flow.
• The PaymentGate system actor is deployed at address 0x0013, which is previously unallocated.
• The new /_cowboy/payment/* reserved paths do not conflict with existing CIP-14 reserved paths (/_cowboy/requests/*, /_cowboy/health, /_cowboy/info).
• The payment.gate entitlement is a new entitlement ID that does not affect existing entitlement grants.
• No changes to the CIP-3 fee model, CIP-7 stream protocol, or CIP-20 token standard are required.