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 payment settles, 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 plus funded sessions:

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

Use /v1/agent/quote for a machine-readable quote and /v1/agent/sessions to fund a short agent session at the published effective per-call price.

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="<base64url-json>"
Content-Type: application/problem+json
Cache-Control: no-store
 
{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Pay $0.50 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.50 per LLM call via Stripe Shared Payment Token.",
    "request": {
      "amount": "50",
      "currency": "usd",
      "recipient": "acct_..."
    }
  },
  "amount": "50",
  "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 an MPP credential in Authorization: Payment:

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

If the credential is malformed, expired, already consumed, or rejected by the wallet/payment provider, the route fails closed:

{
  "type": "https://paymentauth.org/problems/verification-failed",
  "title": "Payment Verification Failed",
  "status": 402,
  "detail": "Payment verification failed. Retry with a fresh challenge and a valid Shared Payment Token."
}

Receipts

Successful settled calls include:

Payment-Receipt: <base64url-json>

Decoded shape:

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

Successful managed-MPP calls emit the same canonical receipt schema as BYOK calls, plus settlement metadata. 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. 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