CIP-18: Payments (r2)

​

1. Abstract

• Presentation is the wire format clients speak. Two are supported in parallel: MPP (the IETF HTTP Authentication scheme Payment, primary) and x402 (Coinbase’s payment header convention, supported for compatibility).
• Settlement is the on-chain accounting performed by the PaymentGate system actor at address 0x12. Both wire formats normalize into the same internal PaymentIntent and settle against the same PaymentGate state.

​

2. Motivation

1. Free-rider problem. Any internet client can hit any actor at zero cost. Gateways bear the burden with no per-request compensation.
2. No actor monetization. Actors cannot charge for their services, blocking paid APIs, data feeds, micro-SaaS, and other revenue models.
3. Agent economy bottleneck. Autonomous agent-to-agent commerce requires per-request settlement. Without it, agents cannot transact for each other’s services.
4. Standards convergence. Two HTTP-native payment standards are emerging in parallel:
   • MPP (“Machine Payments Protocol”), authored by Tempo + Stripe, on the IETF standards track (draft-ryan-httpauth-payment). Uses the standard HTTP Authentication framework. Supports a registry of payment methods (evm, tempo, solana, stellar, lightning, card, stripe). Has companion specs for OpenAPI discovery and JSON-RPC/MCP transport.
   • x402, authored by Coinbase, in production use across the Base/Coinbase agent ecosystem. Uses custom headers (PAYMENT-REQUIRED, PAYMENT-SIGNATURE).

​

3. Design Goals

• One policy, two wires. Actors declare a single PaymentPolicy. Clients can pay using MPP or x402; both succeed against the same on-chain state.
• MPP as primary. The CIP is MPP-first in vocabulary (method, intent) and structure. x402 is a parallel presentation, not a peer.
• Multiple funding models. Per-call, actor-funded, prepaid passes, and epoch subscriptions, composable through a fallback chain.
• Multi-asset. Native CBY, CIP-20 tokens, and (via the bridge facilitator in §12) bridged stablecoins on EVM chains.
• Gateway-enforced, on-chain settled. Payment checks at the edge for low latency. Settlement on-chain for finality and replay protection.
• Composable with existing CIPs. Reuses CIP-3 gas metering for command-path recovery, CIP-7 epoch model for subscriptions, CIP-14 dispatch for HTTP request handling, CIP-20 for fungible token transfers.
• Discoverable. Gateways expose a per-actor OpenAPI document with MPP’s x-payment-info annotations so any MPP-aware agent can discover Cowboy actors.

​

4. Non-goals

• Fiat payment rails. ACH/SEPA/card-issuer flows are deferred. The MPP method="card" and method="stripe" registrations exist; a future CIP can wire them in.
• Cross-chain bridge protocol design. This CIP specifies the interface that a bridge facilitator must satisfy (§12) but defers the bridge protocol itself to the existing Cowboy bridge work and follow-on CIPs.
• Tempo bridge. No Cowboy⇄Tempo bridge exists yet. method="tempo" is reserved for future activation.
• Actor-to-actor payment gating. Internal send_message between actors is not gated by this CIP. Payments apply only to external ingress.
• Streaming metered billing. Pay-as-you-consume billing within a single long-running request (e.g., LLM token-by-token billing) is deferred.
• Activation of MCP gating. §13 specifies the wire format; the actor-as-MCP-server exposure path is delegated to CIP-19.

​

5. Definitions

• PaymentGate. System actor at 0x12 that manages payment policies, budgets, passes, subscriptions, and settles payments.
• PaymentPolicy. Per-actor configuration: pricing per endpoint, accepted assets, model selection (per-request / actor-funded / pass / epoch), and treasury address.
• PaymentIntent. The Gateway’s internal, wire-agnostic representation of a payment-bearing request: { method, intent, payer, recipient, asset, amount, binding }. Both MPP credentials and x402 payloads normalize to this shape before reaching PaymentGate.
• MPP. The Machine Payments Protocol, IETF draft draft-ryan-httpauth-payment. The HTTP Authentication scheme named Payment.
• x402. Coinbase’s payment header convention: PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE.
• Method. An MPP payment rail identifier: cowboy, evm, tempo, etc.
• Intent. An MPP payment-type identifier: charge, and (Cowboy-scoped) pass, subscription.
• Bridge facilitator. A trusted oracle that observes settlement on a non-Cowboy chain and submits a corresponding credit transaction on Cowboy. See §12.
• Serving Budget. CBY pool deposited by an actor owner so clients pay nothing.
• Prepaid Pass. A (client, actor)-bound block of request credits, purchased upfront.
• Epoch Subscription. Time-bounded unlimited access, extending CIP-7’s epoch model.

​

6. Architecture

​

6.1 Two-layer model

┌─────────────────────────────────────────────────────────────────┐
│                         PRESENTATION                            │
│  ┌──────────────────────┐      ┌──────────────────────────┐     │
│  │  MPP (primary)       │      │  x402 (compatibility)    │     │
│  │  WWW-Authenticate    │      │  PAYMENT-REQUIRED        │     │
│  │  Authorization       │      │  PAYMENT-SIGNATURE       │     │
│  │  Payment-Receipt     │      │  PAYMENT-RESPONSE        │     │
│  └──────────┬───────────┘      └────────────┬─────────────┘     │
│             └─────────────┬─────────────────┘                   │
│                           ▼                                     │
│                  ┌────────────────┐                             │
│                  │ PaymentIntent  │   normalized, wire-agnostic │
│                  └────────┬───────┘                             │
└───────────────────────────┼─────────────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────────────┐
│                       SETTLEMENT                                │
│                  ┌────────▼───────┐                             │
│                  │  PaymentGate   │  policies, budgets,         │
│                  │  actor 0x12  │  passes, subscriptions,     │
│                  │                │  nonces, fee distribution   │
│                  └────────────────┘                             │
└─────────────────────────────────────────────────────────────────┘

​

6.2 Components

• Gateway (CIP-14 §5): unchanged role, extended responsibility. Now also enforces payment, advertises challenges in both wire formats, normalizes credentials, and (per §13/CIP-19) terminates MCP.
• PaymentGate (this CIP §8): new system actor at 0x12. Stateful: holds policies, budgets, passes, subscriptions, nonces.
• Bridge facilitator (this CIP §12): new runner role with a new entitlement. Watches EVM, submits inbound credit txs to PaymentGate. Specification only — implementation is follow-on work.
• Compute runners (CIP-10): unchanged. Continue to run actor handlers.

​

7. Payment Models

​

7.1 Per-request (client-paid)

1. Client requests a gated endpoint without an Authorization: Payment header.
2. Gateway looks up the actor’s PaymentPolicy from local state cache.
3. Gateway returns 402 Payment Required with a WWW-Authenticate: Payment challenge (and a parallel PAYMENT-REQUIRED x402 header for compatibility).
4. Client constructs a payment credential per the chosen method/intent (e.g., method="cowboy", intent="charge").
5. Client retries with Authorization: Payment <base64url-credential>.
6. Gateway verifies the credential, dispatches the request, settles via PaymentGate.
7. Gateway returns the response with a Payment-Receipt header.

​

7.2 Actor-funded budget

1. Actor owner calls PaymentGate.deposit_budget(actor, amount).
2. Policy sets default_mode: "actor_funded" for the relevant endpoints.
3. Clients request endpoints normally — no payment headers.
4. Gateway checks budget balance and rate limits before serving.
5. Gateway calls PaymentGate.deduct_budget(actor, amount, request_id).
6. On budget depletion, Gateway falls back per BudgetConfig.fallback: either 402 (degrade to client-paid) or 503 (degrade to unavailable).

​

7.3 Prepaid pass

1. Client calls PaymentGate.purchase_pass(actor, credits, beneficiary), paying credits × per_request_price.
2. PaymentGate returns a random pass_id : bytes32.
3. Client supplies the pass on subsequent requests:
   • MPP: method="cowboy", intent="pass", payload includes pass_id.
   • x402: X-Cowboy-Pass: {pass_id} header (or scheme="cowboy:pass" in payload).
4. Gateway verifies, decrements credits, serves.
5. Passes expire after PASS_EXPIRY_BLOCKS.

​

7.4 Epoch subscription

1. Client calls PaymentGate.purchase_epoch(actor, epochs, beneficiary, payer).
2. PaymentGate records (beneficiary, actor, active_until_epoch). Idempotent: re-purchasing during an active window extends active_until_epoch (rolling window, same as CIP-7). Buying epochs already covered is a no-op.
3. Sponsor model: payer and beneficiary may differ.
4. Subsequent requests need no payment headers; the Gateway checks the entitlement directly.
   • MPP: when no Authorization: Payment is present and an entitlement exists, the Gateway proceeds without challenge. A challenge with intent="subscription" is used only when the client wants to verify or extend.
   • x402: equivalent behavior; no headers needed when entitled.

​

7.5 Hybrid / fallback chain

1. Endpoint is free (no matching price rule, default_mode="free")
2. Client has an active subscription covering this endpoint
3. Client supplied a valid pass with credits remaining
4. Actor's budget has balance and rate-limit headroom
5. Client supplied a valid per-request credential (MPP or x402)
6. → 402 Payment Required (challenge advertises remaining payable models)

​

8. PaymentGate System Actor

​

8.1 PaymentPolicy

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],   // see §8.2
    treasury:           Address,
}

PriceRule {
    path_pattern:   string,       // glob or exact
    methods:        [string],     // ["GET"], ["*"], etc.
    model:          "client_paid" | "actor_funded" | "pass" | "epoch",
    amount:         u256,         // atomic units of default asset
    asset:          Address | null,
}

​

8.2 AssetConfig

AssetConfig {
    asset:          Address,             // 0x0 = native CBY
    network:        string,              // CAIP-2: "cowboy:1", "eip155:8453"
    method:         string,              // MPP method: "cowboy", "evm", "tempo"
    intents:        [string],            // MPP intents: ["charge", "pass", "subscription"]
    x402_scheme:    string | null,       // x402 compat, e.g. "cowboy:exact" or null
    decimals:       u8,
    symbol:         string,
}

​

8.3 API

​

9. Wire Format — MPP (Primary)

​

9.1 Challenge

HTTP/1.1 402 Payment Required
Cache-Control: no-store
WWW-Authenticate: Payment id="<binding-id>",
    realm="<actor>.cowboy.network",
    method="cowboy",
    intent="charge",
    expires="2026-04-28T12:05:00Z",
    request="<base64url(JCS-JSON)>",
    digest="sha-256=:<base64>:"            ; only for requests with body
PAYMENT-REQUIRED: <base64(x402 PaymentRequired JSON)>
X-Cowboy-Block: <block_height>

​

9.2 Credential

GET /api/data HTTP/1.1
Host: <actor>.cowboy.network
Authorization: Payment <base64url(JSON)>

{
  "challenge": { "id": "...", "realm": "...", "method": "...", "intent": "...",
                 "request": "...", "expires": "...", "digest": "..." },
  "source":  "did:cowboy:0x1234...abcd",       // RECOMMENDED, see §16
  "payload": { ... }                            // method-specific, see §9.6
}

​

9.3 Receipt

HTTP/1.1 200 OK
Payment-Receipt: <base64url(JSON)>
PAYMENT-RESPONSE: <base64(x402 SettleResponse JSON)>
X-Cowboy-Block: <block_height>

{
  "status":    "success",
  "method":    "cowboy",
  "timestamp": "2026-04-28T12:01:23Z",
  "reference": "0x<cowboy-tx-hash>",
  "extra":     { "settled_amount": "1000000", "asset": "0x..." }
}

​

9.4 Challenge binding (HMAC-SHA256)

input = realm | method | intent | request | expires | digest | opaque
id    = base64url(HMAC-SHA256(gateway_secret, input))

​

9.5 Payment Methods

​

9.5.1 method="cowboy"

{
  "amount":     "1000000",
  "asset":      "0x0000000000000000000000000000000000000000",   // CBY
  "recipient":  "0x<actor-treasury>",
  "actor":      "0x<actor-address>",
  "valid_after":  <block_height>,
  "valid_before": <block_height>
}

{
  "type":           "authorization",
  "signature":      "<base64url(ed25519-sig)>",
  "authorization": {
      "from":         "0x<payer>",
      "to":           "0x<actor-treasury>",
      "amount":       "1000000",
      "asset":        "0x0000000000000000000000000000000000000000",
      "valid_after":  <block_height>,
      "valid_before": <block_height>,
      "nonce":        "<bytes32>",
      "actor":        "0x<actor-address>",
      "request_hash": "<bytes32>"
  }
}

​

9.5.2 method="evm"

• type="permit2" (RECOMMENDED): client signs an EIP-712 Permit2 authorization. Bridge facilitator submits on EVM, observes settlement, and credits Cowboy.
• type="authorization": client signs an EIP-3009 transferWithAuthorization (USDC, EURC, etc.). Same facilitator path.

​

9.5.3 method="tempo" (reserved)

​

9.6 Intents

​

9.6.1 intent="charge"

​

9.6.2 intent="pass" (Cowboy-scoped)

{
  "actor":     "0x<actor-address>",
  "endpoint":  "/api/data",
  "credits":   1                   // credits required for this request
}

{
  "pass_id":   "<bytes32>",
  "signature": "<base64url(ed25519-sig over (pass_id, request_hash))>"
}

​

9.6.3 intent="subscription" (Cowboy-scoped)

Upstream note. intent="pass" and intent="subscription" are net-new intents. v1 scopes them to method="cowboy". Once production experience justifies it, the same intents should be proposed to the IETF working group as cross-method registrations so other methods (evm, solana, lightning) can adopt the same vocabulary.

​

10. Wire Format — x402 (Compatibility)

​

10.1 402 response

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64(JSON)>
WWW-Authenticate: Payment ...                ; MPP, in parallel
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,
        "mpp_method": "cowboy",
        "mpp_intent": "charge"
      }
    }
  ],
  "version": "2"
}

​

10.2 x402 schemes

• cowboy:exact — native CBY or CIP-20. Payload mirrors the MPP method="cowboy"/intent="charge" authorization (§9.5.1) with the same fields and the same Cowboy Ed25519 signature. The bytes are essentially identical; only the framing differs.
• exact (EVM) — standard x402 EIP-3009 / Permit2 scheme. Same facilitator path as MPP method="evm".
• cowboy:pass — pass redemption. Payload mirrors §9.6.2.
• cowboy:epoch — subscription verification. Payload mirrors §9.6.3.

​

10.3 Payment retry

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

​

11. Wire-Format Normalization

PaymentIntent {
    method:        string,           // MPP method, normalized
    intent:        string,           // MPP intent, normalized
    payer:         Address,
    recipient:     Address,
    asset:         Address,
    amount:        u256,
    binding:       PaymentBinding,   // signature + nonce + request_hash
    source_wire:   "mpp" | "x402"    // for telemetry / receipts
}

• An x402 scheme="cowboy:exact" payload normalizes to method="cowboy", intent="charge".
• An x402 scheme="exact" (EVM) payload normalizes to method="evm", intent="charge".
• An x402 scheme="cowboy:pass" payload normalizes to method="cowboy", intent="pass".
• An x402 scheme="cowboy:epoch" payload normalizes to method="cowboy", intent="subscription".

​

12. Inbound EVM Bridge Facilitator

​

12.1 Role

1. Watches an EVM chain for a defined set of settlement events (EIP-3009 transferWithAuthorization, Permit2 Transfer from Permit2.permitTransferFrom).
2. Verifies that each observed transfer corresponds to a Cowboy payment authorization (matching nonce, recipient, amount).
3. Submits a PaymentGate.credit_inbound(evidence) Cowboy transaction that credits the corresponding CIP-20 balance to the payer’s Cowboy account and consumes the payment nonce.

​

12.2 Relationship to the existing withdrawal bridge

​

12.3 BridgeEvidence

BridgeEvidence {
    chain_id:        u256,                 // CAIP-2 chain identifier numeric form
    tx_hash:         bytes32,              // EVM tx hash containing the transfer
    block_number:    u64,
    block_hash:      bytes32,
    log_index:       u32,                  // index of the Transfer log
    payer:           Address,              // EVM payer
    cowboy_payer:    Address,              // mapped Cowboy account
    recipient:       Address,              // actor treasury (Cowboy)
    asset_evm:       Address,              // EVM token contract
    asset_cowboy:    Address,              // mirror CIP-20 asset on Cowboy
    amount:          u256,
    nonce:           bytes32,              // Cowboy payment nonce being settled
    confirmations:   u32,                  // observed at submission time
    facilitator_sig: bytes,                // facilitator's signature over the above
}

​

12.4 PaymentGate.credit_inbound

credit_inbound(evidence: BridgeEvidence) -> void

1. Verify facilitator_sig against a registered facilitator key (held by runners with bridge.facilitate.evm).
2. Verify evidence.confirmations >= MIN_BRIDGE_CONFIRMATIONS_EVM.
3. Verify evidence.nonce is unconsumed in PaymentGate’s nonce table for (payer, asset_cowboy).
4. Mint or transfer amount of asset_cowboy to the actor’s treasury.
5. Consume the nonce.
6. Emit InboundCredited(payer, recipient, asset_cowboy, amount, evidence.tx_hash).

​

12.5 bridge.facilitate.evm entitlement

EntitlementGrant {
    id: "bridge.facilitate.evm",
    params: {
        "chains":             [u256],   // chain IDs the runner will watch
        "min_confirmations":  u32,
        "facilitator_pubkey": bytes
    }
}

​

12.6 Failure modes

• Reorg. If a watched EVM transfer is reorged out before min_confirmations, the facilitator MUST NOT submit credit_inbound. If submitted prematurely and the evidence becomes invalid post-reorg, the facilitator runner forfeits the reverted gas — this is the design incentive to wait for finality.
• Facilitator equivocation. Multiple facilitators MAY observe the same transfer. The first valid credit_inbound succeeds; subsequent ones revert because the nonce is consumed.
• Stuck payments. Authorizations with valid_before < current_evm_block MUST be rejected at the facilitator layer. The Gateway’s challenge MUST set valid_before to leave sufficient finality headroom (EVM_FINALITY_HEADROOM_BLOCKS).

​

13. MCP Gating

​

13.1 Endpoint

https://<actor>.cowboy.network/_cowboy/mcp

​

13.2 tools/list generation

​

13.3 tools/call dispatch

​

13.4 Payment challenges over JSON-RPC

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "error": {
    "code": -32402,
    "message": "Payment Required",
    "data": {
      "challenges": [
        {
          "id": "...",
          "realm": "<actor>.cowboy.network",
          "method": "cowboy",
          "intent": "charge",
          "expires": "...",
          "request": "<base64url(JCS-JSON)>"
        }
      ]
    }
  }
}

​

13.5 Credentials and receipts via _meta

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "method": "tools/call",
  "params": {
    "name": "fetch_data",
    "arguments": { ... },
    "_meta": {
      "payment-authorization": "<base64url(MPP-credential)>"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": <request-id>,
  "result": {
    "content": [...],
    "_meta": {
      "payment-receipt": "<base64url(MPP-receipt)>"
    }
  }
}

​

13.6 Out of scope here

• The streamable HTTP endpoint, MCP capability negotiation, and tools/list generation rules are specified in CIP-19.
• x402 has no MCP transport equivalent; MCP gating is MPP-only.

​

14. Discovery via OpenAPI

GET https://<actor>.cowboy.network/_cowboy/payment/openapi.json

openapi: 3.1.0
info:
  title: <actor> API
  x-service-info:
    categories: [...]
    docs: https://...
paths:
  /api/data:
    get:
      summary: Query the data API
      x-payment-info:
        method: cowboy
        intent: charge
        amount: "1000000"
        asset: "0x0000000000000000000000000000000000000000"
        currency: CBY
      responses:
        '200': { ... }
        '402': { ... }

• Routes registered for the actor (CIP-14 Route Registry).
• The actor’s PaymentPolicy price_table and accepted_assets.
• Any optional openapi_metadata declared in the policy (titles, descriptions, schemas).

​

15. Gateway Integration

​

15.1 Request flow (HTTP)

1. Gateway receives an HTTP request for a registered actor (CIP-14 §7).
2. Payment check (NEW): Gateway reads PaymentPolicy from local cache.
3. If endpoint is free → dispatch (CIP-14 §8).
4. If client has an active subscription covering this endpoint → dispatch.
5. If a pass credential (MPP intent="pass" or x402 cowboy:pass) is present → verify, decrement, dispatch.
6. If actor-funded budget has balance and rate-limit headroom → deduct, dispatch.
7. If a per-request credential is present (MPP Authorization: Payment or x402 PAYMENT-SIGNATURE) → normalize to PaymentIntent, verify with PaymentGate, dispatch, settle.
8. Otherwise → return 402 with parallel MPP and x402 challenges.

​

15.2 Query path payment

1. Gateway verifies the credential locally (against its committed view of PaymentGate state).
2. Gateway runs the actor handler via queryActor (no consensus).
3. Gateway submits PaymentGate.settle_payment(intent) as a fire-and-forget transaction.
4. If settlement fails (e.g., nonce already consumed by a concurrent Gateway), the Gateway absorbs the cost. This incentivizes correct local verification.

​

15.3 Command path payment

1. Gateway verifies the credential.
2. Gateway constructs a GatewayRegistry.dispatch() transaction (CIP-14 §9.2) with payment context attached.
3. PaymentGate settles atomically with request execution in the same transaction.
4. Gas recovery (gateway_recovery) is paid out per CIP-14’s existing model.

​

15.4 Policy caching

​

16. Client Identity

​

16.1 DID format

did:cowboy:<lowercase-hex-address>

​

16.2 Payment-derived identity

​

16.3 Account signature for non-paying flows

​

16.4 Session tokens

​

17. Reserved Paths

​

18. Revenue Distribution

Per-request payment:
    total_amount = actor_fee + protocol_fee + gateway_recovery
    actor_fee     ─────────> Actor treasury
    protocol_fee  ─────────> Protocol treasury (burned or governed)
    gateway_recovery ──────> Gateway (command-path gas only; 0 for query path)

    protocol_fee = floor(actor_fee × PROTOCOL_PAYMENT_FEE_BPS / 10_000)

total = credits × per_request_price       (pass)
total = epochs × fee_per_epoch            (subscription)
protocol_fee = floor(total × PROTOCOL_PAYMENT_FEE_BPS / 10_000)
actor_receives = total - protocol_fee

​

19. Protocol Constants

PAYMENT_GATE_ADDRESS              = 0x12
PROTOCOL_PAYMENT_FEE_BPS          = 500           // 5%
MAX_PRICE_TABLE_ENTRIES           = 100
MAX_ACCEPTED_ASSETS               = 10
MIN_BUDGET_DEPOSIT                = <governance-set>
MAX_EPOCH_BLOCKS                  = 2_592_000     // ~30 days
DEFAULT_EPOCH_BLOCKS              = 86_400        // ~1 day
PASS_EXPIRY_BLOCKS                = 31_536_000    // ~1 year
MAX_PREPAID_CREDITS               = 1_000_000
CBY_ASSET_ADDRESS                 = 0x0000000000000000000000000000000000000000
PAYMENT_POLICY_CACHE_TTL_BLOCKS   = 1
MIN_BRIDGE_CONFIRMATIONS_EVM      = 32            // governance, per chain
EVM_FINALITY_HEADROOM_BLOCKS      = 64
JSONRPC_PAYMENT_REQUIRED_CODE     = -32402

BudgetConfig { rate_limit_rps: u32, daily_cap: u256,
               fallback: "402"|"503", auto_refill: bool }
EpochConfig  { fee_per_epoch: u256, epoch_blocks: u32,
               min_purchase: u32, max_purchase: u32 }
PassConfig   { min_credits: u32, max_credits: u32, expiry_blocks: u64 }

​

20. Entitlement: payment.gate

EntitlementGrant {
    id: "payment.gate",
    params: {
        "accepted_methods":      ["cowboy", "evm"],
        "accepted_intents":      ["charge", "pass", "subscription"],
        "max_price_per_request": u256
    }
}

​

21. Security Considerations

• Replay (single chain). Authorizations carry a nonce consumed atomically on settlement. Replay across endpoints is prevented by request_hash binding the credential to the request envelope. valid_before / valid_after block-height bounds limit lifetime.
• Replay (cross-wire). A credential submitted as both MPP and x402 in the same request is allowed; the Gateway settles once. Submitting the same payment payload across two requests is prevented by nonce + request_hash.
• Replay (inbound bridge). The facilitator’s credit_inbound consumes the same nonce table as direct Cowboy authorizations, so an EVM-side payment cannot be claimed twice.
• Cross-Gateway double-spend. PaymentGate consumes the nonce atomically. Two Gateways that both verify the same credential locally will not both successfully settle; the loser absorbs the gas.
• Stale challenges. The MPP expires parameter and the Cowboy valid_before block height bound credential lifetime independently. Both MUST be respected.
• HMAC binding. The challenge id is HMAC-bound to the challenge parameters per §9.4. A client cannot tamper with the request body, recipient, or amount and reuse the id.
• Price manipulation. Policy changes commit on-chain and take effect in the following block. Within a single block’s challenge-then-retry, the price cannot change.
• Pass enumeration. pass_id is a random bytes32. Sequential enumeration is infeasible.
• Budget DoS. Actor-funded budgets are protected by rate_limit_rps, daily_cap, and the auto-refill threshold.
• Bridge facilitator compromise. A compromised facilitator could submit fraudulent credit_inbound calls. Mitigated by:
  • Multi-runner facilitator quorum (governance-set threshold).
  • PaymentGate verifying facilitator_sig against the registered facilitator key set.
  • MIN_BRIDGE_CONFIRMATIONS_EVM providing reorg headroom.
  • The same recovery mechanisms as the withdrawal-attestation runner set (CIP-12 governance).
• Protocol fee evasion. All payment paths route through PaymentGate. Gateways only accept settlements processed by PaymentGate.

​

22. Rationale

​

23. Future Work

• Fiat rails. method="card" and method="stripe" (already MPP-registered) wired into PaymentGate via a Stripe facilitator role.
• Tempo bridge. method="tempo" becomes implementable once a Cowboy⇄Tempo bridge exists.
• Session tokens. Browser-friendly subscriptions without per-request signing.
• Streaming metered billing. A intent="meter" for pay-as-you-consume billing within long-running requests (e.g., LLM token-by-token).
• Upstream intent="pass" and intent="subscription". Propose to the IETF working group as cross-method intents once production usage justifies the RFC.
• Actor-to-actor payment gating. Extend payment enforcement to internal send_message calls.
• MPP discovery beyond OpenAPI. Bazaar / actor index integration with x-service-info metadata for cross-actor agent discovery.

​

24. Backwards Compatibility

• Actors without payment.gate are unaffected. Their endpoints remain free / Gateway-subsidized.
• Gateways continue to serve free traffic for non-gated actors using the existing CIP-14 flow.
• The PaymentGate system actor is deployed at 0x12, previously unallocated (the v2 sequence runs 0x0C SESSION_ACTOR → 0x0D STREAM_KEY_MANAGER → 0x0E ROUTE_REGISTRY → 0x0F GATEWAY_REGISTRY → 0x10 RECEIPT_REGISTRY → 0x11 CONTAINER_REGISTRY → 0x12 PAYMENT_GATE).
• /_cowboy/payment/* and /_cowboy/mcp reserved paths do not conflict with CIP-14’s reserved paths.
• The payment.gate and (future) bridge.facilitate.evm entitlement IDs are new.
• No changes to the CIP-3 fee model, CIP-7 stream protocol, or CIP-20 token standard are required.