Agent payments

prxy.monster exposes a dedicated Machine Payments Protocol route for agents that can handle HTTP 402 Payment Required.

Why MPP exists

Autonomous agents sometimes need to purchase one machine-readable resource without creating an account, choosing a subscription, or going through a human checkout. MPP gives that flow a predictable shape:

1. Agent requests the resource.
2. prxy.monster returns a 402 payment challenge.
3. The agent wallet pays or asks its operator to approve.
4. The agent retries with Authorization: Payment ....
5. When settlement is enabled, prxy.monster returns the result and a Payment-Receipt header.

For prxy.monster, the paid MPP resource is one optimized PRXY pipeline execution: MCP tool pruning, cache lookup, context compression/preservation, pattern injection, cost guarding, optional upstream model call, and an itemized receipt.

Billing model

MPP and API-key traffic are different products.

Regular API-key routes such as /v1/messages and /v1/chat/completions are not MPP-payable. They require Authorization: Bearer <prxy_key>.

Discovery

Wallet-aware agents discover paid routes from either surface:

GET https://api.prxy.monster/.well-known/mpp
GET https://api.prxy.monster/openapi.json

Current discovery advertises the dedicated agent route only:

{
  "spec_version": "0.1",
  "realm": "api.prxy.monster",
  "payment_methods": [
    {
      "method": "stripe",
      "wallet_provider": "stripe-link",
      "currency": "usd",
      "status": "protocol_live_settlement_gated_on_stripe_link_spt_ga"
    }
  ],
  "routes": [
    {
      "path": "/v1/agent/messages",
      "method": "POST",
      "price_usd_per_call": 0.05,
      "category": "llm-generation"
    }
  ],
  "capabilities": {
    "idempotency": true,
    "refunds": false,
    "receipts": "header",
    "content_digest": "rfc-9530 sha-256",
    "ledger_public": true
  }
}

There is no separate quote endpoint mounted today. The quote is the route advertisement plus the concrete per-request challenge.

Agent route

POST https://api.prxy.monster/v1/agent/messages

The request body uses the Anthropic-compatible Messages shape.

402 challenge

curl -i https://api.prxy.monster/v1/agent/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bedrock/us.amazon.nova-micro-v1:0",
    "max_tokens": 256,
    "messages": [{ "role": "user", "content": "Say hi" }]
  }'

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="mpp_...", realm="api.prxy.monster", method="stripe", intent="charge", expires="2026-05-03T21:55:00.000Z", digest="sha-256=:...:", request="eyJhbW91bnQiOiI1IiwiY3VycmVuY3kiOiJ1c2QiLCJyZWNpcGllbnQiOiJhY2N0Xy4uLiJ9"
Content-Type: application/problem+json
Cache-Control: no-store
 
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Pay $0.05 per call to access this endpoint via MPP. See api.prxy.monster/openapi.json for full discovery. Method accepted: stripe (Shared Payment Token).",
  "challenge": {
    "id": "mpp_...",
    "realm": "api.prxy.monster",
    "method": "stripe",
    "intent": "charge",
    "expires": "2026-05-03T21:55:00.000Z",
    "digest": "sha-256=:...:",
    "description": "Pay $0.05 per LLM call via Stripe Shared Payment Token.",
    "request": {
      "amount": "5",
      "currency": "usd",
      "recipient": "acct_..."
    }
  },
  "amount": "5",
  "currency": "usd",
  "method": "stripe",
  "intent": "charge"
}

request in the header is base64url JSON for the inner Stripe request object. The digest binds the challenge to the original request body.

Paid retry

When the wallet has a Shared Payment Token, retry with Authorization: Payment:

curl -i https://api.prxy.monster/v1/agent/messages \
  -H "Authorization: Payment id=\"mpp_...\", credential=\"<SPT>\"" \
  -H "Content-Type: application/json" \
  -d '{ "...": "same request body as the challenge" }'

Current settlement-pending response:

{
  "type": "https://paymentauth.org/problems/verification-failed",
  "title": "Payment Verification Failed",
  "status": 402,
  "detail": "SPT verification is not yet enabled on this instance. The protocol layer issues discovery and 402 challenges, but paid retries are gated until Stripe Link agent-payment settlement is enabled."
}

Receipts

Successful settled calls will include:

Payment-Receipt: <base64url-json>

Decoded shape:

{
  "method": "stripe",
  "reference": "ch_...",
  "externalId": "optional",
  "status": "success",
  "timestamp": "2026-05-03T21:55:00.000Z"
}

Receipts are header-format-ready and the public ledger URL is advertised, but production receipts require successful settlement. Refunds are not currently supported; the refund policy is planned for production MPP payments.

Error cases

Idempotency

Challenges are persisted with a five-minute TTL and intended to be single-use. Once production Stripe SPT settlement is enabled, clients should retry the same request body against the same challenge id and let the gateway consume it exactly once.

Test mode

No public test credential is honored by the current /v1/agent/messages route. Use discovery and the 402 challenge response for integration work until a test settlement path is explicitly advertised.

Why a separate route?

MPP wallets and API-key clients use different auth shapes. Keeping /v1/agent/messages separate from /v1/messages prevents wallet retries from colliding with bearer-token auth and keeps production API-key traffic boring.

See also

• POST /v1/messages
• POST /v1/chat/completions
• Pricing
• OpenAPI